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.
refactor(core): evict the ambient class-registry reads from the Concept wire model (#1072)
Louis Choquel96b992786d21
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 6d4c84800..ea68af3b3 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:09f94e6d035a51c81826253418a309516615845ba1a07445932313d7f8b18bfd"-reviewed_by = "Claude (Opus 5)"-reviewed_at = "2026-07-29T12:21:19Z"-rationale = "Fourth consecutive import-line-only opening. Triggers are three files: agent_cli/commands/run/_run_core.py and cli/commands/run/_run_core.py each change one from-line (PipeRunMode moved from pipelex.pipe_run.pipe_run_mode to pipelex.system.pipe_run_mode when the leaf models left the interpreter packages), and dev_cli/commands/hub_layering_guard.py changes a five-line comment to a three-line one — a declaration rationale, not code. No option, default, choice list, output shape or error class moved. Opened both targets and grepped them for PipeRunMode, pipe_run_mode, PipeRunParamKey, PipeRunError and pipeline_models: zero hits, structurally so, since neither target cites a Python import path. Verified the affected surface live: 'pipelex-agent run pipe --help' still lists --dry-run ('Run pipeline in dry mode') and --mock-inputs ('requires --dry-run'), matching docs/tools/cli/agent-cli.md lines 37-38 verbatim. The dev CLI has no doc target here at all. Nothing stale."+digest = "sha256:37b06818f4a4c24d93fd33f5e3bf6e4c344e794e0eeb11333c22f8f32de87f87"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-07-29T17:05:46Z"+rationale = "Trigger is one call site inside the --save-csv block of cli/commands/run/_run_core.py: the CSV row-model lookup moved from Concept.get_structure_class() to ConceptLibrary.make_empty().get_structure_class(concept=...), plus one import line and a comment. No option, default, choice list, exit code, output shape or error class changed — the guard is still except (CsvError, ConceptValueError, OSError) and ConceptStructureClassNotFoundError is a ConceptValueError, so an unresolvable class is still framed as 'Failed to --save-csv to <path>: ...' with exit 1, exactly as before. Grepped both targets for 'structure class', 'structure_class', 'ConceptValueError' and 'concept library': zero hits, structurally so, since docs/tools/cli/ documents the option surface and observable behavior rather than the resolution internals. Verified live: 'pipelex run pipe --help' still renders --save-csv with the same description docs/tools/cli/run.md lines 36/89/136 carry verbatim, and the absence-path paragraph at line 214 (--save-csv fails for any non-flat main output) is untouched by this change. The agent-CLI contract doc has no --save-csv surface at all. Nothing stale."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -109,7 +109,7 @@ rationale = "Fourth consecutive import-line-only opening. Triggers are three fil"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049""pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"-"pipelex/cli/commands/run/_run_core.py" = "blob:0960c339ebfdbdb086af3dee220451e8b9ad28e4"+"pipelex/cli/commands/run/_run_core.py" = "blob:5774e72d68107fcf49355bcb95cfac2924c2af30""pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148""pipelex/cli/commands/run/bundle_cmd.py" = "blob:cb420bf4879c863d64c5e20ed535c42732b720a2""pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"diff --git a/.test_durations b/.test_durationsindex 4f8cc3f67..bfd0c392a 100644--- a/.test_durations+++ b/.test_durations@@ -3952,26 +3952,15 @@"tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_wrapping.py::TestStructureGeneratorWrapping::test_long_field_description_wraps_to_implicit_concat": 0.0022688329918310046,"tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_wrapping.py::TestStructureGeneratorWrapping::test_short_class_docstring_stays_single_line": 0.6346519169746898,"tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_wrapping.py::TestStructureGeneratorWrapping::test_short_field_description_stays_single_line": 0.0008319170447066426,- "tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_are_concept_compatible": 0.039424501068424433,- "tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_refining_text_is_strictly_compatible": 0.0004137070500291884,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_cross_package_domain_code[my_lib->legal.contracts]": 0.001136249047704041,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_cross_package_domain_code[scoring_lib->scoring]": 0.0010045410017482936,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_invalid_cross_package_domain_code[lib->.scoring]": 0.0003634170279838145,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_invalid_cross_package_domain_code[lib->Legal]": 0.0006086259963922203,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_invalid_cross_package_domain_code[lib->]": 0.001208583009429276,- "tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_concept_with_same_structure_as_text_content": 0.002416167058981955,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_construct_concept_ref_with_domain": 0.00042454106733202934,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_get_validated_native_concept_ref": 0.6787016249727458,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_is_native_concept": 0.002148957923054695,- "tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_nested_image_content_strict_false_nonstrict_true": 0.12344787607435137,"tests/unit/pipelex/core/concepts/test_concept.py::TestConcept::test_validate_concept_ref": 0.0006676249322481453,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_both_refine_same_cross_package_concept_siblings": 0.001237209013197571,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_local_refines_unaffected": 0.10966741701122373,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_refines_cross_package_different_structure_with_resolver": 0.0004182500415481627,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_refines_cross_package_different_structure_without_resolver": 0.0002731669810600579,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_refines_cross_package_with_resolver_compatible": 0.6862403750419617,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_refines_cross_package_without_resolver_not_compatible": 0.0002716250019147992,- "tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py::TestConceptCrossPackageRefines::test_resolver_returns_none_not_compatible": 0.0007365000201389194,"tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py::TestConceptFindImageFieldPaths::test_direct_image_concept": 0.0003667499986477196,"tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py::TestConceptFindImageFieldPaths::test_find_image_fields[CompanyInfo]": 0.00041524897096678615,"tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py::TestConceptFindImageFieldPaths::test_find_image_fields[ComplexNestedGallery]": 0.0004618330276571214,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f3ee47994..1628d6168 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@### Added+- **`Concept` is pure data again, and the property is pinned.** `pipelex/core/concepts/concept.py` — a subclass of the MTHDS-protocol wire model `ConceptAbstract` — no longer reads the process-global class registry. `tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py` asserts a golden set over an AST walk of `pipelex/core/concepts/**`: exactly two modules may touch the registry, and both are the **materialization write side** (`concept_factory` registering generated structure classes, `structure_generation/generator.py` looking up base classes to generate against). A golden set rather than a rule, for the reason the `cogt` boundary test gives — there is no predicate separating a sanctioned write-side read from a new read-side one, and no other gate can see the edge at all, since both the accessor and its users are runtime-layer. Documented in [Hub layering convention](contribute/hub-layering.md).+- **Renaming an error class is now a reviewable diff instead of a silent wire break.** `ErrorReport.error_type` is `type(self).__name__` with no indirection, and consumers outside this repo `switch` on that string — so a rename leaves their build green and their branch silently unmatched. Nothing in the repo flagged that, which is how `PipelexInterpreterError` → `MthdsParserError` reached four consumer sites unannounced. `tests/data/errors/error_identity.txt` now pins the `(error_type, title, type_uri)` triple of every discoverable `PipelexError` subclass, regenerated with `make generate-error-identity` (alias `make gei`, or `pipelex-dev generate-error-identity`) and gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. The rendering is pure — no Pipelex bootstrap — and the population comes from the same `iter_pipelex_error_subclasses()` helper the docs generator uses, so it cannot silently miss a deferred-import error module. Documented in [Error Model](under-the-hood/error-model.md).- **The vendor-neutrality of `pipelex.cogt` is now pinned, not just documented.** `tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py` asserts two golden sets over an AST walk of `pipelex/cogt/**`: its third-party import roots (framework and infrastructure only — no inference-provider SDK), and the exact `cogt → pipelex.providers` statements, each recorded with its import form so promoting a deferred import to module level shows up too. These are the edges [Known inversions](contribute/hub-layering.md#known-inversions) documents in prose, and no other gate can see them — `pipelex.cogt` and `pipelex.providers` are both runtime-layer, so the hub-layering guard and the import-closure test are blind to an edge between them by construction. Golden sets rather than a rule, because these are accepted inversions: the point is to turn a sixth edge into a diff a reviewer reads. The img-gen neutrality test's coverage comment is corrected in the same change to claim only what its glob proves.@@ -14,6 +16,19 @@### Changed+- **Breaking: class resolution left the `Concept` wire model for the concept provider, fixing two live bugs on the way.** `ConceptProviderAbstract` gains `get_structure_class(concept)`, implemented by `ConceptLibrary` against the active registry with a `StuffContent` subclass bound. Four members of `Concept` change or go:++ | was | is now |+ | --- | --- |+ | `Concept.are_concept_compatible(..., strict=)` | `Concept.are_compatible_by_declaration(...)` — the pure declaration tier — composed with the new pure `are_structure_classes_compatible` (`tools/typing/class_utils.py`) by `ConceptLibrary.is_compatible` |+ | `Concept.get_structure_class()` | `ConceptProviderAbstract.get_structure_class(concept=…)` |+ | `Concept.is_valid_structure_class(name)` | a private module-level helper in `concept_factory.py`, its only caller |+ | `Concept.search_for_nested_image_fields_in_structure_class()` | compose `get_structure_class` with the existing free `search_for_nested_image_fields(content_class=…)` |++ `Concept.render_concept_representation` now takes the already-resolved `structure_class`, and `StuffSpec.render_stuff_spec` / `InputStuffSpecs.build_inputs_template` / `render_inputs` take a `concept_provider` and resolve once. Three defects close with it. **Cross-package `refines` aliases now resolve at five call sites** that compared two `Concept` values directly (`pipe_llm` ×2, `template_image_analyzer` ×2, `template_document_analyzer`) and therefore had no `concept_resolver` — wrong compatibility verdicts at authoring time and on the PipeLLM text-vs-object run branch. **An unresolvable structure class raises `ConceptStructureClassNotFoundError`** (a `ConceptValueError`) instead of silently answering `False`: "unknown" and "incompatible" are different answers, and conflating them was a latent wrong-verdict bug. **`native.Anything` is answered rather than raised** — it deliberately has no content class, so `NativeConceptCode.is_structureless_concept` / `Concept.declares_a_structure_class` make that a declared property instead of a missing registration; verdicts are unchanged, the reasoning is now correct.++ One further tightening rides along, in the class tier rather than in `get_structure_class`: resolution now applies a `StuffContent` subclass bound (`get_required_subclass`) where the old path used an unbounded `get_class`. A name registered as something other than a `StuffContent` subclass used to reach `are_classes_equivalent` / `issubclass` and could answer `True`; it now raises `ConceptStructureClassNotFoundError`. Deliberate — a class that cannot hold stuff content is as unusable as a missing one — and unreachable through the loader, which refuses to build such a concept in the first place.+- **Fixed: five built-in vendor adapters were pulling the whole interpreter into the runtime layer, through the public exceptions aggregate.** `providers/{anthropic,bedrock,google,mistral}/*_list.py` imported `MissingDependencyError` from `pipelex.exceptions` — the all-errors aggregate, which re-exports every interpreter package's errors — instead of from its definition site, `pipelex.system.exceptions`. Each one therefore loaded 15 interpreter modules, inside a package (`pipelex.providers`) the layer declaration already claimed was clean. Both gates were blind to it: the hub-layering guard only tracks `interpreter_hub` reachability, and the aggregate never reaches it; the closure test's `providers.builtins` entry point does not cover these modules because the vendor plugins import them *inside a function*, hiding them from the static graph and from the aggregator's own closure alike. The imports now point at the definition site, per this repo's "direct full-path imports everywhere" rule, and `providers.anthropic.anthropic_list` joins `RUNTIME_LAYER_ENTRY_POINTS` so the fix cannot silently regress. `pipelex.test_extras` — measured clean, shipped, and imported at boot — is declared runtime-layer in the same change, leaving every top-level package accounted for.- **Breaking: the four leaf models that kept `pipeline` and `pipe_run` out of the layer predicate moved to runtime-layer homes.** With them gone, the import-closure test names **every** interpreter package, and the property it pins loses its last qualification: *importing the Pipelex runtime loads zero interpreter modules* — previously "zero modules from the packages the predicate could name", because two documented interpreter homes had to be left out. Naming them was never blocked by a broken hub arrow; it was blocked by an address, and the remedy is the one `mthds_parsing` used — move the leaf, then widen the predicate. Excluding it would only have recorded the problem.diff --git a/TODOS.md b/TODOS.mddeleted file mode 100644index abdf47acc..000000000--- a/TODOS.md+++ /dev/null@@ -1,783 +0,0 @@-# Modularity refactors — implementation tracker--**Design doc:** [`wip/refactoring/modularity-refactors.md`](wip/refactoring/modularity-refactors.md) — the *why*, the rulings, the measurement snippets. This file is the *how*: ordered work, checkboxes, hard checkpoints.--**Worktree:** `_hub/` · **Branch:** `refactor/Modularity-3` (M3 + M1 + M2 + F1, pushed at `6e74c6f26`; `refactor/Modularity-4` merged in via PR #1065 and deleted) · **Base:** `refactor/Hub-2` (PR #1064, still open — see [Gating](#gating)) · **PR:** [#1067](https://github.com/Pipelex/pipelex/pull/1067), open **against `refactor/Hub-2`** so the diff carries the modularity work only; GitHub retargets it to `dev` when #1064 lands · **Status:** **F1 complete and reviewed three times — CHECKPOINT F1 cleared.** All four tracks reviewed and their fixes committed. Only Phase 5 remains.--**Reviewed 2026-07-27** (`/plan-eng-review`, 8 issues, all ruled). The review reversed **D-M1-2**, ruled **D-M1-4**/**D-M1-5**/**D-M1-6**, re-scoped **F1**, and corrected the cross-repo blast radius in both directions. The changes are folded in below; see [Review findings](#review-findings) for what moved and why.--Three tracks, ordered by dependency: **M3 → M1** (M3 is a prerequisite slice of M1), **M2** independent, then one small follow-up. Each track is its own PR.-------## How to use this file--- Work top to bottom. Tick a box only when the thing is *done and verified*, not when it is written.-- **Checkpoints are hard stops.** At a `🛑 CHECKPOINT` you finish the phase, run the gates, update this file, fan out the reviews, and stop for the user. Do not start the next phase in the same session.-- The [Cold-start brief](#cold-start-brief) at the bottom is what a fresh session reads first. Keep it true.-- Measured numbers are recorded as of the date noted. Re-measure rather than trusting them; the *shape* (which modules, zero vs non-zero) is the criterion, not the absolute count.-------## Gating--- [ ] **PR #1064 (`refactor/Hub-2`) is merged to `dev`.** All three tracks build on the F1 remedy (`pipelex/interpreter_plugins/`, the transitive guard rule). This branch is already based on it, so work can *start* before the merge — but no track may be opened as a PR against `dev` until #1064 lands, or the diff will carry #1064's changes.-- [ ] **PR topology — ruled 2026-07-27: three PRs, with M1 STACKED on M3.** The plan previously said both "M3 → M1" and "each track is based on #1064 and opened against `dev`", which cannot both be true. The topology is:-- ```- #1064 (refactor/Hub-2)- └─ M3 ─────────── PR → dev- └─ M1 ─────── PR → M3 (retarget to dev once M3 merges)- └─ M2 ─────────── PR → dev (independent)- └─ F1 ─────── PR → M2- ```-- ⚠ **Superseded in practice by [D-M2-4](#decisions).** M3, M1 and M2 all landed as commits on `refactor/Modularity-3`, in that order. The prescribed *landing order* is what mattered and it is satisfied; splitting the branch into three PRs after the fact would re-create exactly the three-file conflict the topology existed to avoid. Open it as **one PR against `dev`** once #1064 merges (or split M3 off first if a smaller review is wanted — it is the only one of the three that is genuinely self-contained). F1 stays a separate PR on top, since it is the only behavior change in the track.--- [x] **Landing order is prescribed, not optional.** M1 and M2 both modify `hub_layering_guard.py`, `test_runtime_layer_import_closure.py` and `docs/contribute/hub-layering.md`. They are *architecturally* independent but **not operationally** independent — parallel branches conflict on those three files. Land M3 → M1 first, then rebase M2. ⚠ **A drift ack does not survive the rebase**: the digest reads the git index, so re-review and re-ack `hub-layering-convention` after rebasing M2.- → **Resolved by construction (D-M2-4): M2 was built directly on top of M1 on this branch, not on a parallel branch.** The prescribed landing order is satisfied, the three-file conflict never arises, and the rebase-and-re-ack step disappears — the `hub-layering-convention` ack recorded at CHECKPOINT M2 is already against the final tree. The PR topology below collapses accordingly.-- [ ] **M2 is NOT release-gated.** Measured 2026-07-27 across every sibling repo: **zero** external consumers import `pipelex.plugins.<vendor>`. The "one breaking wave" argument covers M3 and M1 only. M2 may land whenever it is ready — it does not have to wait for the sweep, and its row comes out of the [Phase 5](#phase-5--close-out) table.-------## Ground rules for every move--These are cross-cutting and each one has already been the cause of a confusing failure somewhere in this repo. Read them before the first `git mv`.--- [ ] **Re-path `subject_grants.toml` in the same commit as the move — and *before* running `make agent-check`.** Grants are keyed `<path>::<qualname>` and staleness is symmetric: a grant whose def moved **hard-fails** `check-keyword-only`. Worse, `make agent-check` runs `fix-keyword-only` *first*, which will silently rewrite the now-"ungranted" subjects to keyword-only — corrupting the diff. Order is always: `git mv` → rewrite grant paths → `make cko` (read-only, must be green) → then `make agent-check`.- Measured grant hits by moving path (2026-07-27): `core/bundles` 6 · `core/interpreter` 15 · `core/pipes/pipe_abstract` 5 · `core/pipes/rendering` 15 · `core/pipes/pipe_factory` 0 · `core/registry_models` 0 · `plugins/` 160.-- [ ] **Regenerate error pages when an exceptions module moves.** `docs/errors/<slug>.md` carries a `Defined in | <module path>` row, so every moved error class churns its page. Verified: the page **filename and `type_uri` derive from the class name, not the module path** — so a pure move is URL-stable, and only a class *rename* changes a published `type_uri`. Run `make gep` after each move and inspect the diff.-- [ ] **Mirror the test tree in the same commit** — and **derive the list from each test module's actual subject, never from an inventory written in advance.** M1 proved this twice: the tracker's M1a and M1b test inventories were both materially incomplete. Grep each candidate for the source module it imports and route it by that. For M2: `tests/unit/pipelex/plugins/`, `tests/integration/pipelex/plugins/`.-- [ ] **Check every moved test for a path derived from its own depth.** `Path(__file__).parents[N]` silently resolves to a different directory after a move — no import rewrite, type checker or import-graph tool sees a parent count, and it fails only when the test runs. M1b hit exactly this. Re-anchor on a named directory (`next(p for p in Path(__file__).parents if p.name == "tests")`) rather than fixing the index.-- [ ] **`make cleanderived` after every batch of moves**, before running linters or pytest — stale `__pycache__` and collection state make the linters chase ghosts.-- [ ] **Rewrite imports by exact module path, never by prefix substring.** Two live traps:- - `pipelex.plugins.secrets` (vendor dir) vs `pipelex.plugins.secrets_provider_registry` (mechanism module) — same for `storage`. A prefix `sed` corrupts the mechanism modules.- - `pipelex.core.interpreter` (the package) vs `pipelex.interpreter_hub` / `interpreter_plugins` (unrelated). Anchor on `pipelex.core.interpreter.` and `pipelex.core.interpreter import`.-- [ ] **Rewrite string-literal module references too — they are not imports and nothing sees them.** `mocker.patch("pipelex.plugins.fal.fal_img_gen_worker.ImgGenArgsFactory.make_args_for_model")` is a module path that no import rewrite, no type checker, and no import-graph tool will touch. They fail loudly at test time, but only *after* the move, and a naive import-only rewrite turns the suite red in bulk. Measured 2026-07-27: **M2 = 189** literals, **M1 = 15** (the closure test's own config strings are among them). The `secrets` / `storage` ambiguity above is worse in string form — the sample includes `"pipelex.plugins.storage.storage_plugin..."`.-- [ ] **Use `git mv`** so history follows the file; do the import rewrite as a separate hunk in the same commit.-- [ ] **Sweep with `git grep` or `/usr/bin/grep`, never a bare `grep -r`.** This shell's `grep` is a **ugrep wrapper that honours `.gitignore`** — from the workspace root it silently skips every sibling repo, and inside `_hub` it skips the stale `site/` tree. It returns a *false clean* on exactly the completeness sweep a rename refactor depends on, and it fails silently by construction. Found during M2's review round; M2's own verdict survived re-verification only because the load-bearing pass happened to use `git grep`.-- [ ] **A brace-glob is a module reference no per-name regex will match.** `plugins/{google,openai}/*_img_gen_factory.py` names two modules and matches neither a `google` nor an `openai` substitution keyed on a single vendor. Same class of miss as a string literal, one level further out — and it survives into *unchecked plan items*, where it is worst, because those are instructions for work not yet done. Grep for the brace form explicitly before declaring a rename complete.-- [ ] **Every measurement/guard set is a matched set.** Whenever a module changes layer or package, four places must agree: `RUNTIME_LAYER_PACKAGES` (the guard), `INTERPRETER_PACKAGES` (the closure test), the `INTERPRETER` set in `docs/contribute/hub-layering.md`'s verification snippet, and the classification snippet's `I` in the design doc. Updating one and not the others makes a check pass vacuously.- **Two of the four are now mechanically bound** (M1c): a test asserts the closure predicate and the doc snippet name the same packages, and two more assert that every entry in `RUNTIME_LAYER_PACKAGES` / `INTERPRETER_PACKAGES` resolves on disk — so a typo can no longer guard nothing. `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` are **gone**; do not re-add them. The design doc's copy stays manual (it lives in `wip/`, which is archived at track end).-------## Phase 0 — baseline--Cheap, and it is what every exit criterion is measured against.--- [x] Confirm the tree is clean and gates are green *before* touching anything: `make agent-check`, `make agent-test`, `make drift-check`, `make chl`. — all green on `95a1e9bf7`.-- [x] Re-run the [core classification snippet](wip/refactoring/modularity-refactors.md#measurement) and paste the result into [Measurements](#measurements) below with today's date. — reproduced the [Measurements](#measurements) table exactly (97 / 51×3 / 33 / 30×4, same nine modules).-- [x] Note any drift from the design doc's numbers. **Known already:** re-measured on `bc30149c7` the counts are uniformly higher than the doc's (`registry_models` 97 vs 92, the 48s are 51, the 30 is 33, the 28s are 30). The *set of nine* modules and their ordering are unchanged, so the plan holds; only the absolute figures moved. — confirmed on `95a1e9bf7`; no further drift.-- Also baselined here because M3's exit criteria need them: **43** inverted `core → pipe_*` import statements (24 `registry_models` · 12 `pipelex_bundle_blueprint` · 4 `bundle_elaborator` · 2 `output_renderer` · 1 `pipe_abstract`).-- ⚠ **Gotcha, cost ~10 min:** `make cleanderived` deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`, which is gitignored but *not* regenerated by `agent-check` — only by the test targets. So the ground rules' "`cleanderived` before the linters" order makes pyright fail with 12 unrelated `reportMissingImports` in `model_selection.py`. Regenerate with `.venv/bin/pipelex-dev preprocess-test-models --generate-fixtures --profile ci` before re-running `agent-check`.-------## M3 — split the boot manifest by layer--Removes core's fattest interpreter edge and seeds `pipe_machinery/`. Small, self-contained, no behavior change.--### Work--- [x] Create `pipelex/pipe_machinery/__init__.py` (empty, per repo convention).-- [x] Create `pipelex/pipe_machinery/registry_models.py` holding `PipeRegistryModels(RegistryModels)` with the six pipe lists: `PIPE_OPERATORS`, `PIPE_OPERATORS_FACTORY`, `PIPE_CONTROLLERS`, `PIPE_CONTROLLERS_FACTORY`, `PIPE_SIGNATURES`, `PIPE_SIGNATURES_FACTORY`, plus the ~24 `pipe_operators` / `pipe_controllers` / `pipe_signature` imports that come with them. — 24 imports, as measured.-- [x] Strip those six lists and their imports out of `pipelex/core/registry_models.py`. `CoreRegistryModels` keeps `STUFF`, `EXPERIMENTAL`, `FIELD_EXTRACTION` and the `core.stuffs` imports only. It should end up importing nothing from `pipe_operators` / `pipe_controllers` / `pipe_signature`, and no longer needing `PipeAbstractType` / `PipeFactoryProtocol` / `Any`. — all three dropped as predicted.-- [x] `pipelex/pipelex.py`: import both and register both — two adjacent `register_classes` lines. (`RegistryModels.get_all_models()` reflects over `dir(cls)` and dedups through a `set`, so the split is mechanical and double-registration is impossible.)-- [x] Add `"pipe_machinery"` to `INTERPRETER_PACKAGES` **and** drop `"pipelex.core.registry_models"` from `INTERPRETER_CORE` in `tests/unit/pipelex/test_runtime_layer_import_closure.py`. Do this in M3, not M1 — the moment an interpreter module lives under a new top-level package the predicate must count it, or the test under-counts silently. (The design doc puts this in M1 move 4; it belongs here for `pipe_machinery`, and in M1 for `mthds_parsing`.)- Also **proved the new token is live**, rather than trusting `DIRTY_ENTRY_POINT` (which only proves *some* token matches): ran `_CLOSURE_SCRIPT` against `pipelex.pipe_machinery.registry_models` and asserted both that it exits 1 and that the offenders list contains a `pipe_machinery` module of its own. This is M1c's "one leaf probe per new package" step, done early for M3's token.-- [x] Update the guard's `RUNTIME_LAYER_PACKAGES` docstring where it enumerates `registry_models` as part of core's interpreter half (`hub_layering_guard.py` ~line 101). The declaration tuple itself does not change in M3.-- [x] `docs/contribute/hub-layering.md`: update the two places naming `core.registry_models` as Pipe machinery inside `core/` (~lines 111, 242).- ⚠ **There were four, not two.** The drift review found two more, and they are the load-bearing ones: the *"`runtime_hub` must not name anything from …"* list under "Why the boundary exists" (line 80) and the **`INTERPRETER` set inside the page's own verification snippet** (line 91). Both enumerate the interpreter top-level packages, so both go stale on any new one — and a reader running the stale snippet measures zero interpreter modules and believes it. Expect the same pair in M1a (`mthds_parsing`). The tracker's grep for `registry_models` finds neither; grep for `interpreter_plugins` to find them.-- [x] Write the **registration-surface doc** — new page under `docs/contribute/`, registered in **two** places in `mkdocs.yml`: the `llmstxt-md` plugin's section list (~line 330) and the real `nav:` (~line 569). Missing the first one silently drops the page from `llms.txt`. Content: adding a pipe kind touches the kind's package, the type tag (`PipeType`/`PipeCategory`), the blueprint union in `core/bundles/pipelex_bundle_blueprint.py`, `PipeRegistryModels`, and the spec map (`builder/pipe/pipe_spec_map.py` + `pipe_spec_union.py`). Include the note that the spec-layer parallel in `builder/pipe/` is deliberate (see `pipelex/builder/CLAUDE.md`, spec vs blueprint), not duplication to collapse. — `docs/contribute/registration-surface.md`, both mkdocs registrations done.-- [x] **Not doing:** the `PipeBlueprintUnion` extraction (cut in design doc v2 — it would move twice, since M1 hoists `core/bundles/` wholesale). **Not doing:** moving `PipeType` / `PipeCategory` out of `core/pipes/pipe_blueprint.py` — measured 0, runtime-layer, stays in `core/` permanently (D-M1-2). — respected; note `PipeType`/`PipeCategory` move with `pipe_blueprint.py` in M1b under the *reversed* D-M1-2, so "stays in `core/` permanently" here is superseded by the reversal (see [Decisions](#decisions)).-- [x] **CRITICAL — regression test for the split registration.** Nothing in the suite asserts that pipe classes reach the class registry: `tests/unit/pipelex/test_hub_lifecycle.py:39-51` asserts hub singletons and scoping, and the class-registry tests use a synthetic `ScopedModel`. If either `register_classes` line is dropped or mis-wired, **boot still succeeds** and kajson deserialization of a pipe fails later, in production.- **Assert the full set, not a sample.** One pipe + one stuff only catches a missing *whole* registration call — it cannot catch dropping one of the six lists, or one model out of a list, while hand-splitting `core/registry_models.py:53-93`. So: freeze the pre-split `CoreRegistryModels.get_all_models()` set, assert `CoreRegistryModels ∪ PipeRegistryModels` equals it exactly, **and** assert the two manifests are disjoint. That pins every model across the split and is the only new failure mode M3 introduces.- → **`tests/unit/pipelex/test_registry_models_split.py`** (new module — the repo's one-TestClass-per-module rule rules out appending to `test_hub_lifecycle.py`, which T1 named). Three tests, and the third is the one T1's verify step is about: the frozen-set and disjointness assertions are computed *from the manifests* and would stay green if `Pipelex.make` never registered them, so a third test reads the **booted class registry** through `get_class_registry()`. **Both mutation checks run, both red as intended:** deleting the `PipeRegistryModels` `register_classes` line → *"booted class registry is missing 24 registered model(s)"*; deleting one model from `PIPE_OPERATORS` → set-equality failure *and* *"missing 1 registered model(s): ['PipeSearch']"*. The frozen set is 42 class names; names are unique, and the test asserts that too so the set comparison cannot lie.-- [x] **`make drift-ack CONTRACT=hub-layering-convention`.** M3 edits `hub_layering_guard.py` (the docstring above the tuple), which is a trigger file in `drift.toml:65-69` — so the contract opens and M3's checkpoint `make drift-check` fails without an ack. Review `docs/contribute/hub-layering.md` for real first: M3 moves the pipe manifest out of `core/`, which the doc describes in two places. Stage the trigger files before acking (the digest reads the git index).-- [x] Changelog entry under `[Unreleased] → ### Changed`, marked **breaking** (`CoreRegistryModels` no longer carries the pipe lists; `pipelex.pipe_machinery.registry_models.PipeRegistryModels` is new).-- [x] **Not in the plan, done anyway (matched-pair ground rule).** The design doc's classification snippet gained `"pipe_machinery"` in its `I` set — it is the *third* copy of the interpreter-package list, alongside the closure test's `INTERPRETER_PACKAGES` and the hub-layering page's `INTERPRETER`. The plan deferred this to M1 ("after M1, extend `I` with …"); leaving it would have made the design doc's own measurement under-count for the whole M3→M1 window. Snippet preamble now names all three copies explicitly so the next package cannot update one and miss two.-- [x] **Not in the plan, done anyway.** `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py:52` asserted `not is_runtime_layer("pipelex.core.registry_models")` under the comment *"Everything that names a `Pipe` … stays in the interpreter layer"*. Post-M3 that module names no `Pipe`, so the assertion was still passing under a false rationale — it now belongs with `pipelex.core.qualified_ref` (undeclared because `pipelex.core` is not a declared package). Regrouped, and added `assert not is_runtime_layer("pipelex.pipe_machinery.registry_models")` for the new home. ⚠ This is the same test M1c rewrites wholesale (T5) — expect a conflict there and resolve in M1c's favour.--### Exit criteria--| | baseline | target | **actual** |-| --- | --- | --- | --- |-| interpreter modules loaded by `pipelex.core.registry_models` | 97 | **0** | ✅ **0** (and `hub=0`) |-| inverted `core → pipe_*` import statements | 43 | 19 | ✅ **19** |-| pipe-kind manifests filed inside `core/` | 2 | 1 | ✅ **1** (`PipeBlueprintUnion` only; it moves in M1a) |-| tests pinning pipe classes into the class registry | 0 | **1** | ✅ **1** module / 3 tests, all three mutation checks red |--> **On the "97 interpreter modules" framing.** `registry_models.py` is a boot-time composition manifest with exactly one consumer (`pipelex.py:500`) and it appears in no runtime entry-point closure — so the 97 is not a live problem, and M2's exit criteria explicitly bless the same shape (`builtins.py`, "by design"). M3's real justification is the *directory*: a pipe-kind manifest filed in `core/` makes `core` look like it depends on pipes. Do not oversell the metric in the PR description.--### 🛑 CHECKPOINT M3 — HARD STOP--1. **Gates** (in this order): `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make tb`.-2. **Verify:** re-run the core classification snippet; `pipelex.core.registry_models` must report `0 0`. Confirm the closure test still passes *and* that its `DIRTY_ENTRY_POINT` control still fails (it is what proves the predicate is live).-3. **Update this file:** tick the boxes, record measured actuals in [Measurements](#measurements), refresh the [Cold-start brief](#cold-start-brief), log any decision taken or question raised.-4. **Commit** the phase, then **fan out the reviews** per [Review fan-out protocol](#review-fan-out-protocol) with the commit SHA. M3 reviews: `correctness-and-boot` + `over-engineering`.-5. **Stop.** Report the review verdicts to the user and wait.--#### Review round — done 2026-07-27, fixes applied on Louis' call--`correctness-and-boot`: **no defects.** It re-derived the move independently (six lists byte-identical, both `register_classes` calls live, no other call-site rebuilds from `CoreRegistryModels` alone, no new cycle, no cross-repo consumer of the old path) and re-ran the gates itself.--`over-engineering`: **production change clean and load-bearing**; three defects, all in the new test module. All three confirmed against the code and fixed:--- **The frozen 42-name `PRE_SPLIT_REGISTERED_MODEL_NAMES` literal was spent scaffolding.** Its job — "nothing dropped while hand-splitting" — expired at commit time, after which it billed a hand-edit on every legitimate addition. Confirmed non-hypothetical: the registered-model set grew in each of the last four substantive commits to that file (#953, #1014, #1028, #1039). Replaced with a **derived structural invariant**: every pipe kind must declare the factory that `pipe_factory.py:121` will look up for it by string (`f"{pipe_type.value}Factory"`). That catches the realistic error (a half-dropped kind/factory pair), stays green on a deliberate removal of both halves, and needs no maintenance ever.-- **The disjointness assertion was redundant** with the name-collision check in the same module (`union` is a list concat, so `len(names) == len(union)` already fails on exactly that input) and guarded a runtime-harmless state. Dropped; the collision check was **kept and is load-bearing** — the registry is keyed by class name and kajson's `register_classes` skips a name it already holds.-- **The name-prefix assertions were tautological or wrong.** `all(startswith("Pipe"))` over the pipe manifest cannot fail; `not any(startswith("Pipe"))` over core encoded a layer heuristic our own [`hub-layering.md`](docs/contribute/hub-layering.md) contradicts — `PipeOutput` is **runtime-layer** ("reads as Pipe machinery but is not"), so registering it in `CoreRegistryModels` would be correct and would have tripped the assertion. Both dropped.--Two further items, one from each reviewer:--- **Module-level docstring** violated `pipelex/kit/agent_rules/pytest_standards.md:80` ("not on top of the file and not on top of the class"). Rewritten as a comment block — same rationale preserved, correct placement. (Both agents cited the rule as `.claude/rules/pytest-standards.md`, which does not exist; the kit file is the real one.)-- **The matched triple disagreed on `pipe_signature`** — present in the design doc's `I`, absent from the closure test's `INTERPRETER_PACKAGES` and `hub-layering.md`'s `INTERPRETER`. Pre-dates M3 (verified at `95a1e9bf7`), but this commit is the first to *write the invariant down*, so leaving it would have been dishonest. Added to both shipped copies after confirming `pipelex/pipe_signature/` is a real top-level package that imports `interpreter_hub` directly (`signature_walk.py:11`) and is loaded by **zero** of the closure test's runtime entry points — so the predicate got stricter with no red. The prose must-not-name list at `hub-layering.md` gained `pipe_signature` **and** `interpreter_plugins`, which it had also been missing. All three copies verified equal by script.--⚠ One reviewer claim was **wrong and rejected**: the `over-engineering` agent asserted the three copies were "correctly in sync". They were not — verified directly. It had also, in an earlier message, attributed conclusions to two sub-agents before hearing from them, and retracted that itself.--Mutation checks on the rewritten module, each red on exactly the intended test: drop a pipe kind → factory-pairing test; delete a `register_classes` line → liveness test (still caught, which is what made the derived rewrite safe); duplicate a class name across manifests → collision test.--**Gap noticed, deliberately not closed here — decide it in M1.** The `hub-layering-convention` drift contract triggers on `hub_layering_guard.py` + the two hub modules and reviews `hub-layering.md`. The closure test's `INTERPRETER_PACKAGES` is **not** a trigger, and `hub-layering.md`'s `INTERPRETER` snippet is the thing that drifted from it — so no contract binds the matched triple, which is exactly why the `pipe_signature` disagreement survived unnoticed. Adding the closure test as a trigger (or a contract binding the three copies) is a drift-registry decision, and M1 touches all three files anyway. Raised now so it is not rediscovered the hard way.-------## M1 — make core's layer split physical--Hoists the eight interpreter-layer modules (plus four measured-zero leaf modules that move for cohesion) out of `core/` into two new packages, then collapses the guard declaration to a single entry. This is the big one — split into three commits.--### D-M1-4 — RULED 2026-07-27: rename, and treat it as a wire break--**Rename `PipelexInterpreterError` → `MthdsParserError`.** But the premise the original recommendation rested on was wrong. The plan said *"No external consumer imports `PipelexInterpreter`, so the class rename adds nothing to the sweep."* Measured — it is consumed in five repos, and four of them consume it **as a string, not an import**:--```-pipelex-temporal/pipelex_temporal/temporal_bundle_validator.py:26 from ... import PipelexInterpreter-mthds-starter-js/src/lib/errors.ts:176 case "PipelexInterpreterError":-pipelex-starter-js/src/lib/errors.ts:257 case "PipelexInterpreterError":-vscode-pipelex/.../cliValidationBackend.test.ts:99 error_type: 'PipelexInterpreterError'-playroom/src/app/api/graph/route.ts:119 message.includes("PipelexInterpreterError")-```--Those four TypeScript consumers branch on the class name as the `error_type` **wire value**. Renaming does not break their build — they silently stop matching and fall through to a generic error branch. This is the exact failure the guard's own docstring names: *a missed import is an ImportError, a missed string is not.*--- [x] Rename the class. `BundleElaboratorError` (its subclass) keeps its name.-- [x] Add the `mkdocs.yml` `redirect_maps` entry (`errors/pipelex-interpreter-error.md` → the new page) so the retired `type_uri` still resolves. Verified: the page filename and `type_uri` derive from the **class name**, not the module path (`docs/errors/pipelex-interpreter-error.md:18` carries `| Defined in | pipelex.core.interpreter.exceptions |` as a body row) — so the pure module moves are URL-stable and only this rename churns a URL.-- [x] Changelog: **wire-visible** break, not merely an import break. Name the `error_type` value change explicitly.-- [x] Carry all five repos into the [Phase 5](#phase-5--close-out) sweep table. The redirect fixes the human-facing docs link and does **nothing** for the four machine consumers — they need a coordinated string change.--### M1a — `pipelex/mthds_parsing/`--- [x] `git mv` into a new `pipelex/mthds_parsing/`: `core/interpreter/interpreter.py` → `parser.py`, `bundle_elaborator.py`, `helpers.py`, `validation_error_categorizer.py`, `core/bundles/pipe_sorter.py`, `pipelex_bundle_blueprint.py`.-- [x] **Create `pipelex/mthds_parsing/__init__.py` (empty).** Not optional: ruff runs `select = ["ALL"]` (`pyproject.toml:346`) and `INP001` is per-file-ignored **only** for `tests/**` (`:469`), so a source package without an `__init__.py` fails lint. M1a deletes two package initializers, so this is easy to miss.-- [x] **Add `"mthds_parsing"` to `INTERPRETER_PACKAGES` in THIS commit, not M1c**, and run the closure gate here. Between M1a and M1c the package would otherwise exist as an interpreter home that the predicate does not count — the merged exceptions module could enter a runtime closure with the test staying green. (The tracker previously deferred this to M1c.)-- [x] Merge `core/bundles/exceptions.py` + `core/interpreter/exceptions.py` into one `mthds_parsing/exceptions.py` (topical split only if a circular import forces it, per the error-class location convention).-- [x] Delete `core/bundles/` and `core/interpreter/` (including their empty `__init__.py`).-- [x] Rename the class `PipelexInterpreter` → `MthdsParser` across the tree (33 Python files, ~76 references incl. docs). Apply the D-M1-4 ruling to `PipelexInterpreterError`.-- [x] Rewrite importers. ⚠ **Do not work from a hand-written list** — the previous one was materially incomplete (26 importer files exist; it named ~11 and missed `builder/conventions.py`, `builder/operations/runner_code_ops.py`, `cli/bundle_target_resolution.py`, `language/mthds_schema_generator.py`, agent-CLI commands, …). Rewrite mechanically, then **assert zero surviving references to the old paths** — imports *and* string literals — as the completion check.-- [x] Move tests: `tests/unit/pipelex/core/{bundles,interpreter}/` → `tests/unit/pipelex/mthds_parsing/`.-- [x] **Re-path subject grants AND fix the embedded qualname.** `core/bundles` 6 + `core/interpreter` 15 hits — but `subject_grants.toml:2615` is `["pipelex/core/interpreter/interpreter.py::PipelexInterpreter.make_pipelex_bundle_blueprint"]`, which embeds the **renamed class**. Re-pathing alone leaves a stale grant that hard-fails `check-keyword-only`; the qualname must become `MthdsParser.make_pipelex_bundle_blueprint`. Then `make cko`.-- [x] `make gep` and inspect the `docs/errors/` diff (expect `Defined in` row churn; a filename/`type_uri` change only if D-M1-4 says rename).--### M1b — `pipelex/pipe_machinery/`--**D-M1-2 was REVERSED 2026-07-27** — see [Review findings](#review-findings). The original ruling classified modules by the measurement snippet, which counts **outbound** edges ("how many interpreter modules does X load?"). That answers "is X a leaf?", not "which layer owns X?". The layer question is **inbound: who needs this?** Under the inbound test, four more `core/pipes/` modules are interpreter-only and move with the rest:--| `core/pipes/` module | runtime-layer importers | verdict |-| --- | --- | --- |-| `pipe_output` | 4 | runtime — **stays** |-| `variable_multiplicity` | 5 | runtime — **stays** |-| `exceptions` | 1 | runtime — **stays** |-| `pipe_blueprint` | **0** | interpreter — **moves** |-| `validation` | **0** | interpreter — **moves** |-| `template_guard_lint` | **0** | interpreter — **moves** |-| `handle_pipe_errors` | **0** | interpreter — **moves** |--Every importer of `pipe_blueprint` is `pipe_operators/` (7), `pipe_controllers/` (4), `pipe_signature/` (2), `builder/` (4), `libraries/` (1), `pipeline/` (1), plus the four modules M1 already hoists. **Runtime genuinely does not know about pipes** — which is what the original rule of thumb said all along.--- [x] `git mv` into the package M3 created: `core/pipes/pipe_abstract.py`, `core/pipes/pipe_factory.py`, `core/pipes/rendering/` (both renderers + `__init__.py`), **plus `pipe_blueprint.py`** (D-M1-2 reversed).-- [x] Home the other three flagged modules. `validation.py` is imported by `pipe_blueprint` and `pipe_abstract` → `pipe_machinery/`. `template_guard_lint.py` is imported only by `pipe_operators/` + `pipe_controllers/` → `pipe_machinery/`. `handle_pipe_errors.py` is imported by `validation_error_categorizer` (going to `mthds_parsing/`) and `pipeline/validate_bundle.py` → **`mthds_parsing/`**. Verify each against the closure test after the move; the inbound test used *declared* runtime packages, and `pipeline/` / `pipe_run/` are undeclared straddlers.-- [x] Rewrite importers tree-wide (`pipe_abstract` is imported very widely — expect the largest single hunk of the track). Include the 15 string literals (ground rules).-- [x] Move tests. The previous inventory was incomplete; the actual set under `tests/unit/pipelex/core/pipes/` is `rendering/`, `test_pipe_abstract_namespace_strip.py`, `test_pipe_abstract_signature_surface.py`, `test_pipe_blueprint.py`, `test_pipe_blueprint_presence_markers.py`, `test_pipe_blueprint_signature_enums.py`, `test_validation.py` → **`pipe_machinery/`**; `test_handle_pipe_errors_suffix.py` → **`mthds_parsing/`** (it follows its module, not the package). Plus `tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py` → the integration mirror. Re-derive the list at move time rather than trusting this one.-- [x] Re-path subject grants (`core/pipes/pipe_abstract` 5 + `core/pipes/rendering` 15 hits, plus whatever the four newly-moved modules carry — re-measure), then `make cko`.-- [x] Confirm `core/pipes/` now holds exactly its runtime half: `inputs/`, `stuff_spec/`, `pipe_output.py`, `variable_multiplicity.py`, `exceptions.py`. **Do not** name the new package `pipelex/pipes/` — two `pipes` packages in adjacent layers would be actively confusing.--### M1c — collapse the declaration and the docs--- [x] Collapse `RUNTIME_LAYER_PACKAGES` in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`: the six `pipelex.core.*` entries become the single `"pipelex.core"`. Rewrite the long `#:` note above the tuple (~lines 97-105) — it currently justifies the package-by-package listing, which no longer exists.-- [x] **Rewrite `test_core_is_split_between_the_layers` wholesale** in `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`. (The tracker previously pointed at line 52; that line asserts `pipelex.toolsmith.thing` and is unrelated.) The real block carries **six** core assertions, all of which invert or go stale — including `assert not is_runtime_layer(module_qname="pipelex.core.qualified_ref")`, commented *"the split is deliberate, not an omission"*, which is precisely what M1c reverses. The test's name and docstring become false too. Replace with a `test_core_is_wholly_runtime_layer` asserting the positive, and draw negatives from `mthds_parsing/` and `pipe_machinery/` so they assert the new boundary rather than the absence of the old one.- ⚠ **Vacuous-green window.** `is_runtime_layer` is a pure string predicate over qnames — it never checks that a module exists. Between M1b and M1c, four of those assertions reference module paths that no longer exist **and keep passing**. Do the rewrite in the same commit as the collapse. (Standalone hardening deferred — see [Follow-ups](#follow-ups-from-the-review).)-- [x] Closure test (`test_runtime_layer_import_closure.py`): add `"mthds_parsing"` to `INTERPRETER_PACKAGES`; then **delete `INTERPRETER_CORE`, `INTERPRETER_CORE_EXCLUDED` and the `is_interpreter` branches that read them.** With D-M1-2 reversed and `pipe_blueprint` moving too, this is now correct **as stated** — nothing is left for them to name. (Under the *original* D-M1-2 it would have silently relaxed a live constraint: `hub-layering.md:220` says `pipe_blueprint` is the one entry not caught transitively, so it was the only name in the tuple doing real work. Reversing D-M1-2 is what makes the deletion honest.) Also update the module docstring's "two documented interpreter homes are deliberately absent" paragraph.-- [x] **Prove each new `INTERPRETER_PACKAGES` token is spelled right.** `DIRTY_ENTRY_POINT` only proves that *at least one* configured token matches — it imports `interpreter_hub`, whose closure contains several old interpreter packages, so a typo in `mthds_parsing`, `pipe_machinery` or `pipe_signature` leaves the suite green while that token guards nothing. The predicate lives inside a `textwrap.dedent` string, so nothing type-checks it. Add one leaf probe per new package (a case that must be flagged), or lift the predicate out of the embedded string and unit-test it directly.-- [x] **D-M1-6 — RULED: add `"pipe_signature"` to `INTERPRETER_PACKAGES`.** Verified 2026-07-27 against all five runtime entry points: **zero** `pipe_signature` modules loaded by any of them, so this is safe and surfaces no pre-existing leak. It is independent of the moves — pull it forward to Phase 0 or M3 if you want it out of M1c's diff.-- [x] **Verify the straddler did not become a failure.** `PipelexBundleBlueprintValidationErrorData` (moving into `mthds_parsing/exceptions.py`) is imported by `pipeline/` and `libraries/`. Measured 2026-07-27: **no runtime-layer entry point currently loads it** — `runtime_hub`, `plugins.builtins` and `content_generator` pull in only `pipelex.pipeline` + `pipeline.pipeline_models` — so the deleted exclusion should cost nothing. If the closure test *does* fail on it, do **not** re-add an exclusion: move the data class to a runtime-layer home instead, and record the decision here.-- [x] **Spec + conformance, in this same change.** `conformance/tests/pipelex_transport/test_data.py:45` pins `("pipelex.core.pipes.pipe_abstract", "PipeAbstract", "class")` in `ALLOWED_SURFACE` — an active, unskipped test — and `docs/specs/pipelex-transport-boundary.md:133` names the same path. Workspace CLAUDE.md requires both sides to change with the code, and `make check-spec-links` gates it. ⚠ `_hub`'s `make agent-test` **structurally cannot catch this** — different repo. Also check `docs/specs/pipelex-transport-boundary.md:164` (`pipelex.plugins.orchestrator_registry` — survives M2, it is a mechanism module) and `docs/specs/pipelex-mthds-protocol.md:47` (`PipelexBundleBlueprint` — class name unchanged, path only).-- [x] `docs/contribute/hub-layering.md`: (a) **keep the rule of thumb as written** — *"if it names a `Pipe`, it belongs to the interpreter layer"* (line 115) is correct, and was only slated for rewrite to accommodate the `pipe_blueprint` misclassification that D-M1-2's reversal removes; (b) delete the `core.pipes.pipe_output` carve-out paragraph (line 110) — the collapsed declaration now covers it; (c) **rewrite line 220's predicate paragraph** — it justifies naming core's Pipe-machinery modules one by one and singles out `pipe_blueprint`; both disappear (this target was missing from the tracker); (d) update the Known-inversions (line 242) and "Where core splits" (line 111) sections for the new package names; (e) update line 80's `runtime_hub` must-not-name list.-- [x] Update the classification snippet in `wip/refactoring/modularity-refactors.md` → Measurement (`I` gains `mthds_parsing`, `pipe_machinery`) so the design doc does not go stale.-- [x] `make drift-plan` → the `hub-layering-convention` contract triggers on `hub_layering_guard.py`; review the doc for real, `git add` the trigger files, then `make drift-ack CONTRACT=hub-layering-convention RATIONALE="…"`.-- [x] Changelog entry, **breaking**: the two new packages, the class rename, and the `type_uri` change if D-M1-4 says rename.--### Exit criteria--| | baseline | target | **actual** |-| --- | --- | --- | --- |-| `RUNTIME_LAYER_PACKAGES` entries naming `pipelex.core.*` | 6 | **1** (`pipelex.core`) | ✅ **1** |-| `core` modules loading > 0 interpreter modules | 9 (8 after M3) | **0** | ✅ **0** (4 after M1a, 0 after M1b) |-| `core/pipes/` modules with 0 runtime-layer importers (inbound test) | 4 | **0** | ✅ **0** — what remains scores 4 / 5 / 1 |-| doc carve-outs for `core.pipes.pipe_output` | 1 | 0 | ✅ **0** |-| inverted `core → pipe_*` import statements | 19 (after M3) | **0** | ✅ **0** (3 after M1a) |-| `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` entries | 7 / 2 | **deleted** | ✅ **deleted** — `EXCLUDED` in M1a, `CORE` in M1b |--### 🛑 CHECKPOINT M1 — HARD STOP--1. **Gates:** `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make gep` (diff must be reviewed, not just generated).-2. **Verify:** re-run the classification snippet with the extended set — every remaining `pipelex.core.*` module reports `0 0`. **Re-run the inbound test too** (see [Measurements](#measurements)) — every module left in `core/pipes/` must have ≥1 runtime-layer importer. `make chl` passes with the collapsed declaration *and* the transitive rule reports zero breaching runtime-layer modules. Closure test green including the dirty control.-3. **Cross-repo gate (cannot be run from `_hub`):** in the `conformance/` repo, update `ALLOWED_SURFACE` and `docs/specs/pipelex-transport-boundary.md`, then run `make check-spec-links`. This is a hard checkpoint item, not sweep work.-4. **Update this file** + [Cold-start brief](#cold-start-brief) + [Measurements](#measurements).-5. **Commit**, then **fan out reviews** with the commit range. M1 reviews: `correctness-and-imports` + `boundary-and-naming` + `over-engineering` + `test-and-docs-sync`.-6. **Stop.** Report verdicts and wait.--#### Checkpoint record — reached 2026-07-27, commits `0f0309b8f` · `c9c45c475` · `10080cf26`--**All gates green** at `10080cf26`: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check`, `chl`, `gep` (no churn — no error class moved in M1b/M1c), `tb`. Every exit-criterion actual is in the table above.--**Decisions taken during implementation** (each one the plan authorized in advance):--- **D-M1-8 — `PipelexBundleBlueprintValidationErrorData` moved to `pipelex.core.exceptions`, not into `mthds_parsing/`.** M1c's plan said to verify the straddler "did not become a failure" and, if it did, to move the data class to a runtime-layer home rather than re-add an exclusion. It did: the claim "no runtime-layer entry point currently loads it" was wrong — `pipelex.core.memory.working_memory_factory` reaches it, and the closure test's own docstring said so all along (`core.bundles.exceptions` was in `INTERPRETER_CORE_EXCLUDED` precisely because it lands in every runtime closure). Moved to `core/exceptions.py`, which already holds the two sibling structured error-data models it shares `PipeValidationErrorType` with. That is what let `INTERPRETER_CORE_EXCLUDED` be deleted outright in M1a instead of being carried forward.-- **`INTERPRETER_CORE` deleted in M1b, not M1c.** M1b is the commit that empties it; leaving a four-entry tuple whose comment says "not under a top-level package of its own" for one commit would have been the exact "passing under a false rationale" shape M3's review flagged.-- **Test moves were re-derived, and the tracker's inventory was again incomplete** — it missed `test_execution_data_coverage.py`, `test_pipe_validate_before_run.py`, `test_run_pipe_tracer_metadata.py` and `test_inputs_template_toml.py`. Derived instead from each module's actual subject (grep each test for the `core.pipes.*` module it imports).-- **`tests/unit/pipelex/core/test_data/` stays put.** It is a shared MTHDS corpus consumed from `tests/integration/pipelex/language/` as well as by the parser tests, so it is not a mirror of a source module. Noted rather than silently left.--**The one real bug the move introduced, and nothing static could have caught it.** `tests/integration/.../test_input_renderer_light_golden.py` derived its fixture paths from `Path(__file__).parents[4]`. Moving it one level shallower silently repointed that at the repo root, and it failed only in the full suite — no import rewrite, type checker or import-graph tool sees a parent count. Re-anchored on `tests/` **by name**; every other moved test was then swept for the same shape (none had it). Worth carrying into M2: a depth index is a module-location dependency that looks like a constant.--**Cross-repo gate (item 3) — done, and it reports more than M1 caused.** `conformance/tests/pipelex_transport/test_data.py` and `docs/specs/pipelex-transport-boundary.md` now pin `pipelex.pipe_machinery.pipe_abstract`; `make check-spec-links` passes. Running the transport arm against this branch (`CONFORMANCE_PIPELEX_PYTHON=_hub/.venv/bin/python`) then reports two failures, and the split matters:--- **7 provider-side symbols missing — all pre-existing**, none touched by M1: `pipelex.hub.*` (5, retired by the hub split) plus `pipelex.pipeline.job_metadata.JobMetadata` and `pipelex.graph.trace_context.TraceContext` (moved by the Phase 3 type moves). `ALLOWED_SURFACE` is stale w.r.t. two *earlier* tracks. This is release-gated sweep debt that predates M1 and should be folded into the same wave.-- **1 consumer-side hit — M1-caused and working as designed**: `pipelex-transport/pipelex_transport/primitives/pipe_classification.py` still imports `pipelex.core.pipes.pipe_abstract`. The deny-by-default AST scan is pointing at the Phase 5 sweep item. **Deliberately not fixed here** — `pipelex-transport` pins a *released* `pipelex`, so changing it now breaks it immediately; it lands with the wave.--⚠ **Both cross-repo edits are left UNCOMMITTED in their own repos** (`conformance/` on `dev`, workspace-root `docs/specs/`), one line each. Committing them to `dev` would break those repos against the released `pipelex` before the wave lands. Whoever runs the sweep must pick them up.--**Two follow-ups closed early, both mutation-checked.** T10 (guard against vacuously-green string-predicate tests) is **done**, in the form the plan preferred: `RUNTIME_LAYER_PACKAGES` entries and `INTERPRETER_PACKAGES` tokens must each resolve on disk. And the gap M3's checkpoint flagged as "no contract binds the matched triple" is now bound by a test rather than a drift contract — the closure predicate and `hub-layering.md`'s snippet must name the same set. ⚠ **The design doc's third copy is deliberately not asserted**, since `wip/` is archived at track end; it stays a manual concern for M2, which adds no interpreter package and so should not disturb it.--#### Review round — done 2026-07-28, fixes applied--Four reviews over `6d5b9418a..a23c1b70b`. **All four cleared the moves themselves**, each by measurement rather than reading: every module under the three packages imports cleanly, the only module-level cycle in `pipelex/` (`core.stuffs.stuff` ↔ `stuff_artefact`) is unchanged and untouched, `pipelex/core/**` holds zero imports of any interpreter package, and the collapse to one `pipelex.core` entry *widens* enforcement — `core.exceptions`, `core.registry_models`, `core.qualified_ref` and bare `core.pipes` were previously undeclared and unchecked. The D-M1-8 placement was tested skeptically and stands: 6 of 9 runtime entry points transitively load `pipeline.exceptions`, so filing the straddler with the parser would have broken the property for real.--**Every defect was documentation, fixture or test-quality drift — none in the moves.** All confirmed against the code before fixing.--- **The user-facing regression, and the one no gate could catch.** `_SUBSYSTEM_SECTIONS` in `pipelex/errors/error_pages_generator.py` never got an `mthds_parsing` row. `_subsystem_key` reads the module's *second segment*, so the rename silently reclassified both parser errors through `_FALLBACK_MACRO_SLUG` — the two errors a method author hits most moved from **Authoring & language** to **Platform & tooling**. Fixed with the missing row. ⚠ **The lesson is about the check, not the row:** `make gep` reporting "no diff" was read as evidence the rename propagated, and it is not — it proves committed matches generated, and the pages matched *because* they baked in the wrong fallback. The generator is deliberately built so a missing curation entry still renders rather than failing. **Read the generated diff, never just the exit code.**-- **A wire-visible brand defect the rename introduced.** `title()` auto-derives from the class name, so `MthdsParserError` published the RFC 7807 title `"Mthds parser"` — the standard's brand, mis-cased, on every error report. Fixed with `_declared_title = "MTHDS parser"`. The five error-report fixtures that paired the new `error_type` with the retired `title`/`type_uri` are corrected, and the identity triple is now **pinned by a test** (`test_mthds_parser_error_identity_is_pinned`) — nothing asserted it before, which is exactly how the fixtures came to carry a shape the class cannot produce.-- **An overclaim I wrote into the M1c rewrite.** "Every `pipelex.core.*` module loads zero interpreter modules" is false as stated: `core.pipes.pipe_output` loads `pipeline.pipeline_models`, and `runtime_hub` also loads `pipe_run.pipe_run_mode`. It holds only under the closure predicate's deliberate `pipeline`/`pipe_run` carve-out — which line 228 of the same page states plainly. The base commit had said the honest opposite at that spot. Qualified in all four places the property is stated. See [deferred follow-ups](wip/refactoring/deferred-placement-follow-ups.md) §3: the caveat now repeats in four places, which is itself the argument for moving those two leaves.-- **Eighteen assertions carrying three bits.** The two guard tests M1c rewrote were an *inventory*, not an invariant: with `pipelex.core` a single prefix entry, any string under it is True and any string under `pipe_machinery.`/`mthds_parsing.` is False, invented names included. This repeats the defect M3's own review round found and recorded as a lesson. Replaced with derived invariants: `pipelex.core` is declared with **no** `pipelex.core.*` sub-entry (re-splitting core fails), and `RUNTIME_LAYER_PACKAGES` ∩ `INTERPRETER_PACKAGES` = ∅ — which also binds two declarations maintained in separate modules and never previously compared.-- **The regex scraper was self-inflicted.** `INTERPRETER_PACKAGES` lived inside the `textwrap.dedent` string, which is what forced a regex to read it back and was the stated justification for the new tests. Hoisted to a real module-level constant handed to the subprocess **as argv** — no interpolation, no scraper, names now lint-visible. Mutation-checked that the argv path is load-bearing: emptying the set makes the negative control fail.-- **`parents[5]`, and why it was worse than a style point.** `test_hub_layering_guard.py` validated the declaration against `Path(__file__).resolve().parents[5] / "pipelex"` while the sibling test added in the *same commit* carries a comment condemning depth indices. Not merely fragile: `parents[6]` is the workspace root, which holds a sibling `pipelex/` checkout — so a module moved one level shallower would validate a **different repo** and pass. Re-anchored on `tests/` by name.-- **Stale prose, all fixed:** `runtime_hub.py`'s "one rule" docstring (still forbade two deleted packages, omitted the four current ones — and it is a declared trigger of the drift contract whose ack reviewed only the doc copy); `hub-layering.md` placing the renderers in `core/pipes/rendering/` in the present tense, plus the paragraph arguing for that regrouping; two adjacent paragraphs on the same premise reaching opposite conclusions; the closure test's own entry-point and `pipe_machinery` comments; `handle_pipe_errors.py` citing a now-sibling module; the blueprint-location enumeration in the kit rules source and `builder/CLAUDE.md`; `tests/CLAUDE.md` missing rows; the CHANGELOG naming a package deleted later in the same unreleased cycle.--**Deferred, not fixed** — placement and naming accuracy, no silent bug, recorded in [`wip/refactoring/deferred-placement-follow-ups.md`](wip/refactoring/deferred-placement-follow-ups.md): three modules in `mthds_parsing/` that are not parsing (`pipe_sorter`, the generic half of `helpers`, `handle_pipe_errors`); the parser fixture corpus still filed under `tests/unit/pipelex/core/`; and the `pipeline`/`pipe_run` leaf leak. `pipe_machinery/` was checked module by module and is accurately named throughout.--**Fixed in passing** (pre-existing, same class): `tests/CLAUDE.md` had no row for `pipelex/codegen/` or `pipelex/pipe_signature/` either.-------## M2 — separate the plugin mechanism from the vendor adapters--`pipelex/plugins/` is two things under one name: the mechanism (17 top-level modules) and the built-in vendor adapters (17 directories). Splitting them makes the one-way dependency visible: adapters → mechanism, engine → mechanism, mechanism → nothing.--### Work--- [x] **Create `pipelex/providers/__init__.py` (empty)** — same `INP001` reason as `mthds_parsing/` (ruff `select = ["ALL"]`, tests-only exemption). The commit fails lint without it.-- [x] `git mv` the 17 vendor directories to a new `pipelex/providers/`: `anthropic`, `azure_rest`, `bedrock`, `blackboxai`, `docling`, `fal`, `gateway`, `google`, `huggingface`, `linkup`, `mistral`, `openai`, `openrouter`, `portkey`, `pypdfium2`, `secrets`, `storage`. (D-M2-1: `providers/` over `backends/` — `backends/` would collide with `pipelex/cogt/model_backends/`, and the code's own vocabulary for the non-inference adapters is already "provider": `secrets_provider_registry`, `storage_provider_registry`.)-- [x] `pipelex/plugins/` keeps the mechanism only: `contract.py`, `registrar.py`, `discovery.py`, `exceptions.py`, the seven `*_registry.py`, `model_handle.py`, `sdk_client_registry.py`, `sdk_client_manager.py`, `backend_extras_factory.py`.-- [x] `builtins.py` follows the vendors → `pipelex/providers/builtins.py`, still exporting `RUNTIME_BUILTIN_PLUGINS` / `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES`. Re-point the downward import in `pipelex/interpreter_plugins/builtins.py`. Both stay parameters of `build_registrar` — unchanged.-- [x] Rewrite imports. **Watch the `secrets` / `storage` trap** (ground rules): `pipelex.plugins.secrets` is a vendor dir, `pipelex.plugins.secrets_provider_registry` is a mechanism module that must not move. Same for `storage`.-- [x] **Rewrite the 189 string-literal module references** (ground rules) — `mocker.patch("pipelex.plugins.<vendor>...")` targets, invisible to import rewrites and to pyright. They fail loudly at test time, so `make agent-test` is the gate, but budget them as real work: an import-only rewrite turns the suite red in bulk and reads as a catastrophic move rather than expected residue.-- [x] **Add `"pipelex.providers"` to `RUNTIME_LAYER_PACKAGES`, and add a guard test that proves it.** This is the one step where a mistake is invisible — dropping the vendors from the guard silently un-declares the largest runtime package.- ⚠ **The plan previously claimed "the transitive rule is what catches it." That is backwards.** Verified at `pipelex/cli/dev_cli/commands/hub_layering_guard.py:677`: the rule iterates `sorted(module for module in reaching if is_runtime_layer(module_qname=module))`. An **undeclared** package is excluded from the rule's domain, so omitting it makes the guard go *quieter*, not louder. **No existing gate catches this.** Add an explicit assertion to `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` that a representative `pipelex.providers.*` module `is_runtime_layer`.-- [x] Add `pipelex/providers/builtins.py` to the closure test's `RUNTIME_LAYER_ENTRY_POINTS` (replacing `pipelex.plugins.builtins`, which after the move no longer aggregates anything). Its presence there is load-bearing history: that module and three neighbours breached the boundary transitively while both gates stayed green.-- [x] Move tests: `tests/unit/pipelex/plugins/` and `tests/integration/pipelex/plugins/` — split so vendor tests land under a `providers/` mirror and mechanism tests stay under `plugins/`.-- [x] Re-path subject grants (160 hits under `plugins/` — the bulk are vendor workers), then `make cko`.-- [x] `make gep` — several vendor directories carry exceptions modules (`gateway`, `portkey`, `bedrock`, `google`, `mistral`, `openai`, …), so expect a wide `Defined in` diff. Filenames and `type_uri`s must be **unchanged** (no class renames in M2); if one changes, something got renamed by accident.-- [x] Docs sweep for `pipelex/plugins/<vendor>/` paths: `docs/under-the-hood/reasoning-controls.md` (a table of ~10 paths), `error-model.md` (3 refs to `pipelex/plugins/*/`), `inference-backend-plugins.md`, `secrets-provider-plugins.md`, `orchestrator-plugins.md`. **Do not touch the entry-point group name** `"pipelex.plugins"` — it is a group identifier, not a module path, and it is the third-party contract.-- [x] **Sweep architectural prose in *source*, not just `docs/`.** Two module docstrings describe the pre-M2 layout and go stale silently: `pipelex/plugins/contract.py:33-35` ("``pipelex.plugins`` for the runtime half, ``pipelex.interpreter_plugins`` for the interpreter half" — after M2 the runtime *adapters* are in `pipelex.providers`), and `pipelex/interpreter_plugins/builtins.py:3-8` (describes `pipelex.plugins` as the neighbouring runtime adapter package). Both are the kind of comment the repo's own diagram-maintenance rule says must move with the code.-- [x] `docs/contribute/hub-layering.md` → **Known inversions**: record the four `cogt → provider config` imports (`anthropic`, `google`, `mistral`, `openai` config classes reached from `cogt/config_cogt.py`) as a deliberate, documented exception. Rationale (D-M2-2): the main config model is statically typed end-to-end (`configs.py` ⇄ `pipelex.toml` structural sync); making vendor config sections plugin-contributed would trade that static typing for a dynamic registry.-- [x] **`make drift-ack CONTRACT=hub-layering-convention`.** M2 adds `pipelex.providers` to `RUNTIME_LAYER_PACKAGES`, a trigger file in `drift.toml:65-69`, so the contract opens and M2's checkpoint `make drift-check` fails without an ack. Review the doc for real — M2 adds a whole runtime-layer package, which the "Where core splits" and Known-inversions sections both describe.-- [x] Changelog entry, **breaking**: `pipelex.plugins.<vendor>` → `pipelex.providers.<vendor>`. Two things to state explicitly: (a) the *plugin entry-point contract is unaffected* — an external plugin imports `pipelex.plugins.contract` / `pipelex.plugins.registrar`, both of which stay put; (b) **no known external consumer imports the vendor paths** (measured 2026-07-27: zero hits across every sibling repo), so the break is in-tree only. Do not imply a consumer migration that nobody needs.--### Exit criteria--| | baseline | target | **actual** |-| --- | --- | --- | --- |-| mechanism modules importing a vendor | 1 (`builtins.py`, by design) | **0 in `plugins/`**, 1 in `providers/` | ✅ **0 / 1** — `providers/builtins.py` names all 17, nothing under `pipelex/plugins/` names any |-| vendor modules importing outside `providers/` + `plugins/` | 0 | 0 (unchanged) | ✅ **0** |-| guard test asserting `pipelex.providers.*` is runtime-layer | 0 | **1** | ✅ **1**, derived from disk and mutation-checked red |-| `cogt → <specific vendor>` statements | 7 | 7 (4 documented, 2 in F1, 1 self-resolving) | ✅ **7**, and they are the *only* three source files outside `providers/` naming a vendor |-| `RUNTIME_LAYER_PACKAGES` covers every vendor module | yes | yes | ✅ **17 / 17** |--⚠ **Measurement trap, cost ~10 min and it under-counted silently.** `pypdfium2` contains a digit, so a `[a-z_]*` character class in a grep pattern skips it — the first pass reported 16 of 17 vendor imports in `builtins.py` and would have reported a clean `cogt` count even if a `pypdfium2` import existed. Use `[a-z0-9_]+` for anything matching a vendor segment. The *rewrite* script was never at risk (it uses literal vendor names), only the measurements taken afterwards — which is the worse of the two, because a measurement is what tells you the rewrite was complete.--> **The "vendor imports nothing but the mechanism" metric was false by construction** and is restated above. The design doc deliberately preserves cross-vendor edges (`blackboxai` / `openrouter` / `portkey` → `openai`; `gateway` → `fal` / `google` / `openai` / `portkey`) because they stay inside the new package — e.g. `blackboxai/blackboxai_completions_factory.py:9` and `openrouter/openrouter_completions_factory.py:8` import `OpenAICompletionsFactory` at module level. A metric targeting zero could never be met. Measure "imports outside `providers/` **and** `plugins/`" instead.--### 🛑 CHECKPOINT M2 — HARD STOP--1. **Gates:** `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make gep` (review the diff).-2. **Verify:** transitive layering rule reports zero breaching runtime-layer modules; closure test reports zero interpreter modules for every runtime entry point *including the new `providers.builtins`*; the dirty control still fails.-3. **Update this file** + [Cold-start brief](#cold-start-brief) + [Measurements](#measurements).-4. **Commit**, then **fan out reviews**. M2 reviews: `correctness-and-imports` + `boundary-and-naming` + `over-engineering`.-5. **Stop.** Report verdicts and wait.--#### Checkpoint record — reached 2026-07-28--**All gates green**: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check` (two contracts acked), `chl`, `gep` (diff reviewed, see below), `tb`. Every exit-criterion actual is in the table above.--**Scale of the move:** 17 vendor packages + `builtins.py` out of `pipelex/plugins/`; **1364 substitutions across 136 files**, of which **191 were string literals** (the plan predicted 189 — the drift is two, both in test mock targets). The completion check was the one that makes "did I get them all?" answerable: grep the whole tree for the old paths and assert the only survivors are in the deliberately excluded files (`CHANGELOG.md`, `TODOS.md`, `wip/`, `docs/errors/` — history and generated pages, which must not be textually rewritten; the error pages are regenerated by `make gep` instead).--**The `secrets` / `storage` trap was real and was avoided by construction.** Every substitution anchors the vendor name on a `(?![A-Za-z0-9_])` lookahead, so `plugins.secrets` (vendor dir) rewrites while `plugins.secrets_provider_registry` (mechanism module) does not. Verified after the fact by asserting that no mechanism module is reachable at a `pipelex.providers.*` path, and that the `pipelex.plugins` **entry-point group name** — a group identifier, not a module path, and the third-party contract — is untouched.--**Decisions taken during implementation:**--- **D-M2-4 — M2 was built on top of M1 on this branch, not on a parallel branch off #1064.** The plan's topology had M2 independent and rebased after M1, with a mandatory drift re-ack because a rebase invalidates the digest. Building it stacked satisfies the prescribed landing order, eliminates the three-file conflict the plan warned about, and makes the ack recorded here final. See [Gating](#gating).-- **Test split derived per module, not from the plan's two-line instruction.** The vendor subdirectories were unambiguous, but the flat modules needed reading. `test_linkup_plugin_guard.py`, `test_secrets_plugin.py` and `test_storage_plugin.py` are *vendor* tests despite sitting at the `plugins/` root (they moved into the matching `providers/<vendor>/` mirrors); `test_transport_retry_wiring.py` and `test_plugin_pipelex_storage_images.py` are cross-vendor and moved to the `providers/` root; `test_inference_backend_coverage.py` reads as a vendor test by name but is a *mechanism* round-trip over `BUILTIN_PLUGINS` and stayed. On the integration side `conftest.py` moved with the four vendor tests, because all four of its consumers moved and the three modules that stayed use none of it.-- **`tests/CLAUDE.md` gained a `pipelex/providers/` row.** The source-to-test mapping is 1:1 by convention; a new source package with no row silently drops out of every targeted test run.--**The one user-facing defect, and it is the same shape M1 hit three weeks ago.** `_SUBSYSTEM_SECTIONS` in `pipelex/errors/error_pages_generator.py` had a `plugins` row and no `providers` row. `_subsystem_key` reads a module's **second dotted segment**, so every vendor error class would have silently reclassified out of *Inference & providers* into the `_FALLBACK_MACRO_SLUG` (*Platform & tooling*) — with `make gep` exiting 0 and producing an entirely plausible diff. This is M1's `mthds_parsing` regression repeating on the next module move, and it was caught **only** because M1's recorded lesson was to read the generated diff rather than trust the exit code. Fixed by splitting the row in two, which the content wanted anyway: **Provider adapters** (a vendor SDK rejected the call) and **Plugin system** (a plugin failed to load or claimed a taken slot). Verified by the negative: `docs/errors/platform-and-tooling.md` is byte-identical, so nothing fell through. No page was added or removed, so no `type_uri` changed.--**Two drift contracts opened, not one.** `hub-layering-convention` was predicted. `config-docs` was not — re-pathing the four vendor config imports touches `cogt/config_cogt.py`, a trigger. Reviewed for real and logged as **friction**: `docs/configuration/` cites no Python import path anywhere, so an import-only diff cannot affect it *by construction*. That is the second such opening on that contract from a pure refactor sweep, and the dogfood log now carries a concrete narrowing proposal (ignore diffs confined to import statements) backed by two data points.--#### Review round — done 2026-07-28, fixes applied--Three reviews over `7beda698f..dee323e28`. **All three cleared the move itself, by measurement rather than reading.** The `correctness-and-imports` pass found **no import defect at all**: it AST-walked every `.py` under `pipelex/` and `tests/`, resolved all 944 `pipelex.`-prefixed string constants against the live interpreter (which covers every `mocker.patch` target), imported all 111 modules under `pipelex.providers` in one process, and confirmed that importing the entire `pipelex.plugins` mechanism pulls in **zero** `providers` modules — so the one-way dependency is empirically true, not merely asserted. `boundary-and-naming` independently verified the same and confirmed the "omitting the entry makes the guard quieter, not louder" premise by monkeypatching the tuple and watching the guard report zero violations either way.--**Every defect was in the documentation of the boundary, or in the test that guards it. None in the move.**--- **The new guard test repeated a defect this track has now made three times.** `is_runtime_layer` matches by dotted prefix, so reading the vendor list off disk and looping over it carried exactly one bit — `is_runtime_layer("pipelex.providers.totally_invented.x")` is `True`, the assert fires on the first entry, and the remaining iterations can never execute. Two reviewers flagged it, and both correctly noted the test must **not** be deleted: it is the only thing in the suite that catches a dropped declaration, because the guard CLI itself stays green. The clincher is that `test_core_is_declared_as_one_whole_package`, which M1c added *to this same file*, has a docstring condemning precisely this shape. Replaced with a membership assertion over **both** halves of the split — which is strictly stronger than what it replaced (dropping `pipelex.plugins` now fails too, where the disk-scan version only caught `pipelex.providers`), carries two bits instead of one, and drops a real second failure mode the reviewers spotted: an adapter added without an `__init__.py` is importable as a namespace package but was silently skipped by the filter. Both mutations checked red.-- **A boundary claim my own commit contradicted two sections later.** "Where the built-in plugins split" asserted the one-way dependency as three clauses, and the third — *"the engine depends only on the mechanism"* — is false: importing `cogt.config_cogt` alone loads **8** `pipelex.providers.*` modules, which the Known-inversions bullet added in the *same commit* documents and justifies. One document, two opposite claims about the same word. This is the identical shape M1's review found ("two adjacent paragraphs on the same premise reaching opposite conclusions"), and it is the worst defect of the round: a layering page that states the boundary wrongly is more harmful than one that omits it. Clause dropped and scoped explicitly to the two packages, with a pointer to the inversions.-- **"One directory per vendor" is wrong twice over.** `providers/secrets/` registers the built-in `env` backend — no vendor exists — and `providers/storage/` registers local, in-memory, S3 and GCP behind a single directory; in both cases only the registration shim moved, the implementations are under `pipelex/tools/`. The package *name* survives this (all three reviewers agree `providers` is right, and it is exactly why `vendors/` would have been wrong), but the prose overreached. Corrected, and the exception is now stated rather than glossed.-- **Hardcoded counts, flagged independently by all three reviewers**, against an explicit workspace rule ("Never hardcode counts… they create diff churn, go stale silently, and add no value"). Four live locations pinned "seventeen" / "the seven capability registries". The irony was pointed out and is fair: the neighbouring test went out of its way to avoid becoming an inventory while the prose beside it hardcoded the number. Fixed. Left alone deliberately: the same words inside the recorded drift-ack rationales and the dogfood log, which are append-only records of a decision at a point in time — rewriting them would falsify the record.-- **Two unchecked F1 items named paths M2 had moved** (`plugins/{google,openai}/*_img_gen_factory.py`). Completed items' historical references are correct as written; it is specifically the open ones that must name the current tree, because F1 is the next work on this branch and this file is its handoff. Fixed.--**One reviewer claim was wrong and is rejected:** `correctness-and-imports` reported a fifth hardcoded count at `hub_layering_guard.py:114`. There is no numeral in that file — verified by grep. The other four locations it named were correct.--**Two method findings worth more than the defects.**--- **This shell's `grep` is a ugrep wrapper that honours `.gitignore`.** Run from the workspace root it silently skips every sibling repo; inside `_hub` it skips the stale `site/` tree. A naive `grep -r` therefore returns a **false clean** on exactly the sweep a rename refactor depends on. The whole-tree completion check was re-run with `/usr/bin/grep` and the verdict held — but it held by luck of using `git grep` for the load-bearing pass, not by design. **Use `/usr/bin/grep` or `git grep` for any completeness sweep.**-- **A brace-glob evades a per-vendor regex.** `plugins/{google,openai}/` is a real module reference that no substitution keyed on a single vendor name will match — it is the same class of miss as a string literal, one level further out. Worth adding to the ground rules before the release-wave sweep; the same shape exists in a `pipelex-api/wip/` note.--**Reported and not reproduced:** one reviewer saw the new guard test fail once in five full-suite runs, with `is_runtime_layer` returning `False` for a module the committed tuple covers — impossible against this tree, and the run carried the `bringing up nodes...`-twice signature that `docs/agents/debugging-hanging-pytest-runs.md` names as xdist worker crash-and-replace. Re-run 25 times under xdist after the rewrite: **zero failures**. The rewritten test no longer touches the filesystem, which removes one of the two moving parts. Recorded as an unreproduced observation rather than closed — if it recurs it needs root-causing, not tolerating.--**Not done here, deliberately:** the `wip/` docs that still describe the pre-M2 layout (`wip/plugins/*.md`, the design doc's own prose) were excluded from the rewrite along with `CHANGELOG.md` and `TODOS.md`, per M1's method. The design doc's classification snippet needs **no** change — M2 adds a runtime-layer package, not an interpreter one, so the matched triple is undisturbed.-------## Follow-up F1 — the two `cogt → vendor` img-gen factory imports behind a registry--Deliberately **not** inside the 127-file M2 move: this is a behavior change and would be invisible in that diff (D-M2-2).--**Re-scoped 2026-07-27 from three imports to two.** Two corrections:--1. **`backend_factory.py:53` (VertexAI) is dropped.** VertexAI support is being removed, so the edge self-resolves. Do not build auth-dispatch machinery for a vendor on its way out — it would outlive its reason. The import is already deferred (`# noqa: PLC0415`), so it costs nothing while it remains.-2. **No registry. There is no dispatch key.** The first review proposed an arg-builder slot on `inference_backend_registry`; the outside voice showed that cannot work, and it is verified:- - `ImgGenArgsFactory.make_args_for_model(cls, model_rules, *, img_gen_job, nb_images, model_id, model_name)` — **receives no `sdk`** (`img_gen_args_factory.py:54-62`).- - Dispatch is a `match` over **`AspectRatioTaxonomy`**, not over a provider (`img_gen_args_factory.py:367-396`): `GPT_IMAGE_LEGACY` / `GPT_IMAGE_2` → `OpenAIImgGenFactory.size_for_*`, `GEMINI_*` → `GoogleImgGenFactory.resolve_image_config`, `QWEN_IMAGE` → …- - The gateway worker is **one SDK that executes both** OpenAI and Google taxonomies (`gateway_img_gen_worker.py:78-84`), so an `(family, sdk)` key cannot select the right helper at all.--**Ruled: move the helpers, do not dispatch them.** Extract the OpenAI/Google taxonomy and geometry helpers into a **neutral mapping module under `cogt/img_gen/`**, then have both `ImgGenArgsFactory` and the provider workers import *inward*. These are taxonomy utilities keyed by a `cogt`-owned enum — they were never independently dispatched workers.--- [x] Extract the taxonomy/geometry helpers from `providers/google/google_img_gen_factory.py` and `providers/openai/openai_img_gen_factory.py` into a neutral `cogt/img_gen/` mapping module. (Both re-pathed by M2 — F1 is unstarted work, so its paths must name the current tree.) — **two** modules, not one (D-F1-1): `cogt/img_gen/img_gen_gemini_mapping.py` + `cogt/img_gen/img_gen_gpt_mapping.py`.-- [x] Re-point `img_gen_args_factory.py:37-38` (currently **module-level**, not deferred) and the provider workers to import inward from it. Net import-cost improvement: removes two eager vendor imports from a `cogt` module. — done; the inward importers are `providers/google/google_img_gen_worker.py` and `providers/gateway/gateway_factory.py`.-- [x] Tests covering each taxonomy branch, including the unmapped-taxonomy path. — the branch coverage already existed and moved with the module (`test_img_gen_gemini_mapping.py`, incl. the non-Gemini-taxonomy rejection; the GPT-Image branches are covered from the args-factory side). What was **missing** is the invariant F1 actually buys, added as `test_img_gen_mapping_neutrality.py` (D-F1-4).-- [x] Changelog entry.-- [x] Leave `backend_factory.py:53` alone; re-check after VertexAI removal lands. — untouched; it is now the *only* remaining `cogt → specific vendor` edge of this kind.--**Why this beats the registry**, recorded so it is not re-litigated: no hub wiring, no registrar menu entry, and therefore **no plugin-API version bump**. `plugins/contract.py:5-19` uses strict coarse API equality and explicitly versions registrar changes, so adding a menu capability would force a coordinated plugin wave — for two import sites. It also fixes the dependency *direction* rather than routing it through machinery, and it leaves `pipelex.plugins.contract` untouched, which is what M2's changelog promises.--### Exit criteria--| | baseline | target | **actual** |-| --- | --- | --- | --- |-| `cogt → specific vendor` import statements | 7 | **5** (4 config + 1 deferred VertexAI) | ✅ **5** |-| source files outside `providers/` naming a vendor module | 3 | **2** | ✅ **2** (`config_cogt.py`, `backend_factory.py`) |-| eager vendor imports in `cogt/img_gen/` | 2 | **0** | ✅ **0** |-| third-party imports in the mapping modules | 1 (`openai`) | **0** | ✅ **0**, and pinned by a test |-| tests pinning the neutrality of the new home | 0 | **1** | ✅ **1** module / 2 tests, both mutation-checked red |--### 🛑 CHECKPOINT F1 — HARD STOP--Gates as above (this one *does* change behavior, so `make agent-test` is the real gate, not a formality). Reviews: `correctness-and-boot` + `over-engineering`. Then stop.--#### Checkpoint record — reached 2026-07-28--**All gates green**: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check`, `chl`, `gep` (diff reviewed — empty, and *verified* empty rather than assumed: no error class moved, and `cogt` already had its `_SUBSYSTEM_SECTIONS` row, so the M1/M2 regression shape could not repeat here), `tb`.--**Scale:** 2 source modules + 1 test module moved, 127 substitutions across 11 files plus the durations file. Same rewrite method as M1/M2 (ordered longest-first substitutions over `git ls-files`, `CHANGELOG.md` / `TODOS.md` / `wip/` / `docs/errors/` excluded, then a whole-tree `git grep` completion check asserting the only survivors are in those excluded files). ⚠ `.test_durations` is **not** an exclusion — M1 and M2 both rewrote it, and it carries test node ids that a test move invalidates.--**One near-miss the completion sweep caught by construction:** `OpenAIImageURL` is a live local alias for the OpenAI SDK's `ImageURL` in four completions factories. A substitution keyed on `OpenAIImage` would have corrupted all four; the list keys on the full type names (`OpenAIImageLegacySizeType`, `OpenAIImageModerationType`, `OpenAIImageInputFidelityType`), so none matched. Verified after the fact — the four sites are untouched.--**Decisions taken during implementation** — see [Decisions](#decisions) for D-F1-1 … D-F1-4.--#### Review round — done 2026-07-28, fixes applied--`correctness-and-boot`: **no defects.** It reconstructed both pre-move files, applied only the documented renames, and diffed against the new ones — the **entire** functional delta is `moderation_literal`'s `omit` → `None`, everything else being docstrings. It then traced every consumer of that value and confirmed the branch is identical (`Omit` is not a `str`, so the old `isinstance` test and the new `is None` test agree on every input), verified all three `mocker.patch` targets followed the class, confirmed no orphan `.test_durations` entries, and recomputed the neutrality property independently — 43 modules in the mapping closure, zero `pipelex.providers`, zero `pipelex.config`, no deferred or dynamic import anywhere in it. It also confirmed boot is untouched: the moved modules are lookup tables, present in no manifest and no entry point.--⚠ **Its one unreproduced observation has a mundane explanation, and it is reassuring rather than worrying.** It saw the closure subprocess fail exactly once, reporting **10** `pipelex.providers` modules, and could not reproduce it in 8 further full-suite runs or 15 standalone ones. Ten is the exact count [Measurements](#post-f1-measured-2026-07-28) records for the deliberate mutation used to prove the guard discriminates — so the reviewer observed that mutation in flight, in a shared worktree, and what it actually witnessed is the guard firing correctly on a genuinely coupled tree. Its suggested hardening (`-I` plus explicit `cwd=`/`env=`) is **not applied**: cwd on `sys.path[0]` is what makes the subprocess measure the *working tree* rather than an installed copy, and the sibling `test_runtime_layer_import_closure.py` is built the same way. Recorded rather than silently dismissed — if it ever appears with no concurrent editing, that reasoning is what to re-examine.--`over-engineering`: **the move itself is clean and not over-engineered** — verified as a pure placement fix with no registry, no plugin slot, no dispatch layer and no shim, and the `omit` → `None` change *removes* machinery rather than adding it. The equivalence was confirmed independently rather than taken on trust (the old caller never put the sentinel in the dict either, and the worker reads the key's absence). Grants correctly re-pathed; `bc22ba934` verified a pure re-sort by identical line multiset.--**Every defect was in the new guard test, and the headline one is this track's own recurring shape — a check that cannot fail.**--- **`assert MAPPING_MODULE_PATHS` sat at the top of a test parametrized over that same list, so it was unreachable.** pytest never calls a body for an empty parameter set: it reports `SKIPPED [1] got empty parameter set` and exits 0. Verified directly with a throwaway repro against this venv rather than taken on the reviewer's word. The line therefore could not catch the one failure it named — a stale glob turning the check into a silent green skip — and **D-F1-4's written justification for the glob was false as a result**. The sibling assertion in the *non*-parametrized test is reachable and does the job for real, so the fix is a deletion, not an addition: the dead assert goes, the third copy of the same check inside `_CLOSURE_SCRIPT` goes with it (its only caller is already gated by the reachable one), and the surviving guard now carries a comment explaining why it cannot live in the parametrized sibling. Mutation-checked: with the glob pointed at a non-matching pattern the module reports **1 failed, 1 skipped** — loud, which is the whole point.-- **Kept the glob, against the reviewer's preferred fix.** Replacing it with a two-item literal would retire all three vacuity checks at once, which is true and tempting. But the glob is the only thing that covers a third taxonomy family on the day it lands, and this invariant is invisible to every other gate in the repo (D-F1-4) — a new mapping module silently outside the check is a worse failure than one reachable assertion is a cost. One reachable guard, one line of cost.-- **Duplicated closure machinery with `test_runtime_layer_import_closure.py`: judged, not drifted.** The reviewer is right that this branch's M1/M2 rounds were about killing near-duplicate guard mechanics, so it deserved a ruling rather than silence. Ruling: **keep them separate.** After the deletions above the shared surface is a ten-line script, a timeout constant and one `subprocess.run` — and the two guards must be able to diverge (the closure test's detector is parameterized by interpreter packages passed as argv and carries a dirty-control entry point; this one has a fixed prefix and no entry-point list). Extracting a helper would couple them to save less than it costs.-- **Stale grant rationale fixed** — `input_fidelity_literal` still read *"Derives the OpenAI fidelity literal"* after the de-vendoring rename D-F1-2 motivated. Re-recorded through `make sgr` so the registry stays machine-written and sorted.-- **Stale tense in this file fixed** — the re-sort was still described as pending future work inside the very range that landed it.--**An overclaim I caught while verifying one of the reviewer's "cleared" items, and it is the M2 shape again.** My own docstring, changelog entry and `hub-layering.md` bullet all said the GPT Image family is "served by three different SDKs (OpenAI, Azure REST, the Pipelex gateway)". The shipped decks prove **two** — `openai.toml` and `azure_openai.toml` are the only ones declaring a `gpt_image_*` taxonomy. The gateway *worker* is genuinely written for these models (it routes through the same args factory and carries the OpenAI `/images/generations` → `/images/edits` split), but its catalog is fetched remotely, so no shipped config settles it. The two proven adapters already defeat "file it in the OpenAI adapter", so the argument never needed the third. Reworded in all three places to what the config proves. ⚠ The reviewer had marked this claim *checked and accurate*; a reviewer confirming a claim is not the same as the claim being verifiable from the tree.--**One finding confirmed against the code and rejected:** the `"not supported by OpenAI image model '<name>'"` error strings. They name the *model the user chose*, which is an OpenAI model whichever SDK routes to it — Azure and the gateway serve OpenAI's models, they do not make them theirs. The module docstring's neutrality claim is about the *mapping*, not the model, so the two do not contradict. Rewriting them would churn several test `match=` patterns to make the messages less accurate.--**Fixed alongside, in its own commit** — `subject_grants.toml` had stopped being sorted by key, which its own documentation calls an invariant (`docs/contribute/keyword-only-arguments.md:37`: *"machine-written and sorted by key, so diffs stay stable and merge conflicts resolve trivially"*). Measured 11 out-of-order pairs; F1 contributed 2 of them and **M1 and M2 the rest** — a bulk path rewrite re-paths a grant key without moving its block, and `check-keyword-only` does not gate order, so the invariant broke silently and stayed broken across three commits. Kept out of F1's diff as branch debt rather than F1 debt: it is `bc22ba934`, a pure reordering (304 insertions against 304 deletions, with the key set, every `param` and every `rationale` asserted unchanged before writing).--#### Third review round — `/review`, done 2026-07-28--Run against `origin/refactor/Modularity-3` (the F1-only diff), after the two agent rounds above. **No correctness defect.** The move is complete and the consumer set closes: enumerating every pre-move reference to the two classes and their six type aliases at the base yields exactly the sites F1 touched, with no survivor anywhere in the tree outside `CHANGELOG.md` / `TODOS.md` / `wip/`. The `omit` → `None` equivalence re-verified independently (`Omit`/`omit` now appear nowhere in `pipelex/`; the only reader of the `moderation` key is `openai_img_gen_worker.py:78`, which pops it). The neutrality property re-measured in a fresh interpreter: **0** `pipelex.providers` modules and **0** vendor-SDK roots in the mapping closure. Gates re-run green: `cko`, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), `drift-check`, `tb`, full `agent-test`. Codex, given the same scoped diff adversarially, returned **no findings** and reproduced the closure measurement itself.--Five items, none critical. Three fixed mechanically, two ruled by Louis:--- **The corrected three-SDK claim survived in a fourth copy, and it was inside the very test that pins the property.** `test_img_gen_mapping_neutrality.py`'s header said *"GPT Image by the OpenAI, Azure REST and gateway workers"* — the exact wording `fd141d4ed` set out to retire from the docstring, the changelog and `hub-layering.md`. Same matched-set failure as `pipe_signature` in M3 and the four-not-two occurrences in M3's doc sweep: the sweep found the three copies someone had listed, not the copies that exist. Reworded to what the decks prove (re-verified: `openai.toml` and `azure_openai.toml` are still the only two declaring a `gpt_image*` taxonomy).-- **Two subject-grant rationales describe an operand that is not the granted param.** `ImgGenGeminiMapping.img_gen_taxonomy` and `.optional_img_gen_taxonomy` grant `param = "inference_model"` but read *"Operates on the aspect-ratio taxonomy"* — copied from the seven siblings that really do take `taxonomy`. Pre-existing (identical at the base), but this round's own fix list already re-recorded `input_fidelity_literal` for exactly this defect and stopped at one. Re-recorded both through `make sgr`; sort invariant re-asserted over all keys.-- **A comprehension variable shadowed the parameter interpolated two lines below it.** `img_gen_gpt_mapping.py:89` built its "supported aspect ratios" list with `for aspect_ratio in …` while `aspect_ratio` is the function's own parameter, used at line 91 in the error message. Correct only because comprehensions carry their own scope — and the sibling builder at line 120 already names it `supported_ratio`. Renamed to match. Pre-existing, moved unchanged.-- **`.test_durations` carried 112 orphan entries and `test_parser.py`'s 54 tests had none — M1 debt, fixed here in its own commit.** The ground rules call `.test_durations` a non-exclusion precisely because a test move invalidates its node ids, but M1's rewrite re-pathed *directories* and missed *basename renames*: `test_interpreter.py` → `test_parser.py` (52 entries), `test_interpreter_preliminary_text.py` → `test_parser_preliminary_text.py`, plus the renderer moves into `pipe_machinery/rendering/`, `test_job_metadata_request_id.py` into `system/`, and `test_hub_class_registry.py` → `test_class_registry_scoping.py`. Nothing gated it: the file is generated, pytest-split silently treats an unknown node id as average duration, so the only symptom was CI shard imbalance. Reconciled against a full unfiltered `--collect-only` (`-m ""` — the marker filter in `addopts` hides ~312 items and would have "orphaned" every `e2e` entry), matching each dead id to a live one by its `Class::test` tail: **125 remapped, 0 ambiguous, 0 dropped.** The two surviving dead ids are `pipe_img_gen` parametrizations keyed on the generated model-set fixture, so they are profile-dependent rather than orphaned, and were left alone. ⚠ **This is a third instance of the same shape** (`subject_grants.toml` order, the matched triple, now durations): a *generated or bookkeeping* file that no gate validates, broken by a bulk rewrite, invisible until someone measures it.-- **The test module that still named the vendor is renamed.** `test_img_gen_args_openai_sizes.py` / `TestImgGenArgsOpenAISizes` → `test_img_gen_args_gpt_sizes.py` / `TestImgGenArgsGptSizes`. It exercises `AspectRatioTaxonomy.GPT_IMAGE_2` / `GPT_IMAGE_LEGACY` and patches `pipelex.cogt.img_gen.img_gen_gpt_mapping.log`, so it was the last "OpenAI" that D-F1-2 should have taken. (`test_safety_openai_moderation_mapping` keeps its name — `SafetyCheckerTaxonomy.OPENAI_MODERATION` is a real enum member.) Its 13 durations entries were re-pathed in the same reconciliation.--**One gap recorded, deliberately not closed** — see [Follow-ups from the review](#follow-ups-from-the-review): the neutrality guard is weaker than its comment claims in two ways. The AST check reads only the mapping modules' *own* import statements and the closure check counts only `pipelex.providers`, so a vendor SDK reached **transitively** through another `pipelex.cogt` module passes both. Unexercised today — measured **zero** vendor-SDK imports anywhere in `pipelex/` outside `providers/`, which is the stronger invariant and is itself unguarded. And `_MAPPING_DIR.glob("img_gen_*_mapping.py")` is non-recursive and name-keyed, so *"a third taxonomy family is covered the day it lands"* holds only for a family landing in that exact directory under that exact suffix. Both are cheap to close and neither is worth the machinery F1 exists to avoid; recorded so the claim is not mistaken for a proof.-------## Phase 5 — close out--- [x] **One PR is open — [#1067](https://github.com/Pipelex/pipelex/pull/1067), based on `refactor/Hub-2` rather than `dev`.** [Gating](#gating) said no track may open against `dev` until #1064 lands, or the diff carries #1064's changes. Stacking on the base branch satisfies that without waiting: the diff is the modularity work only, and GitHub retargets the PR to `dev` automatically when #1064 merges. **Still verify the retarget happened** once #1064 lands — an auto-retarget is not a merge, and the base must read `dev` before this one goes in.-- [ ] Write the **cross-repo sweep handoff** into `wip/refactoring/` — the sweep is release-gated and shared with the hub split, the Phase 3 type moves, and the `interpreter_plugins` relocation. It must land as **one breaking wave**, not four. Known external hits:-- **Re-measured 2026-07-27 across every repo in the workspace.** The previous table was materially incomplete — it named one repo; there are eight. It also called `pipelex-temporal` "private and unchecked" when it is checked out at the workspace root and carries the most hits of any consumer.-- | repo | hits | what |- | --- | --- | --- |- | `pipelex-temporal` | **13** | `PipelexInterpreter` (class, 3 files) · `PipeAbstract` · `PipeFactory` · `PipelexInterpreterError` in a comment |- | `pipelex-api` | 5 | `PipelexBundleBlueprint` · `PipeAbstract` · `PipelexBundleBlueprintValidationErrorData` |- | `pipelex-transport` | 3 | `PipeAbstract` (`primitives/pipe_classification.py` + 2 tests) — **was missing from the table entirely** |- | `mthds-starter-js` | 2 | `"PipelexInterpreterError"` — **wire string**, `src/lib/errors.ts:176` + test |- | `pipelex-starter-js` | 2 | `"PipelexInterpreterError"` — **wire string**, `src/lib/errors.ts:257` + test |- | `conformance` | 1 | `ALLOWED_SURFACE` pin — **handled at CHECKPOINT M1, not here** |- | `vscode-pipelex` | 1 | `error_type: 'PipelexInterpreterError'` — **wire string** |- | `playroom` | 1 | `message.includes("PipelexInterpreterError")` — **wire string** |-- **The four wire-string consumers are the dangerous ones**: they branch on the error class name as an `error_type` value, so the rename does not break their build — they silently fall through to a generic error branch. No Python grep or type checker finds them.-- Verified clean for the M1 module set: `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows`, `pipelex-worker`, `pipelex-starter-python`, `pipelex-relay`, `sandbox`, `pipelex-daytona-sandbox` (it imports `pipelex.plugins.contract` / `registrar`, which do not move). **M2 and F1 contribute nothing to this sweep** — zero external consumers import `pipelex.plugins.<vendor>`, and zero import either img-gen mapping under any name (re-measured across every repo at F1 time; the only hit anywhere is the released `pipelex/` checkout itself). No kajson-registered class moves, so serialized payloads are untouched.--- [ ] **Fix the workspace repo table first.** `pipelex-transport` and `pipelex-daytona-sandbox` are real consumer repos missing from the workspace-root `CLAUDE.md` table — which is the table every cross-repo sweep is built from, and the reason `pipelex-transport` was missed here. Add both (and audit for others) before the sweep runs.-- [ ] Archive this tracker to `wip/refactoring/` when the track completes (repo convention — see how `wip/hub/hub-split-tracker.md` was handled).-- [ ] Update the memory entry `project_modularity_refactors.md`.-------## Review fan-out protocol--At every checkpoint, spawn the reviews **in parallel, in one message**, each as a **fresh sub-agent with no inherited context**. Hand each one *only* a pointer to the changes — never this plan, never the design doc, never the rationale, never your own conclusions. A reviewer that has read the justification cannot independently find the flaw in it.--Prompt template (fill the bracketed parts, change nothing else):--> Run the `/code-review` skill on the following changes in the repo at `/Users/lchoquel/repos/Pipelex/_hub`:-> `[git diff <base>..<sha>` — or the list of unstaged files]->-> Focus dimension: **[dimension]**.->-> We want clean, solid software — not over-engineering. Report concrete defects with file:line, and say plainly if you find none. Do not propose speculative features or abstractions.--Dimensions to draw from:--| dimension | what the reviewer is asked to hunt |-| --- | --- |-| `correctness-and-imports` | broken/circular imports, a moved symbol whose importers were missed, a rewrite that hit the wrong module (`plugins.secrets` vs `secrets_provider_registry`), test files left behind their source |-| `correctness-and-boot` | behavior change hiding in a mechanical move; boot-sequence registration correct and complete |-| `boundary-and-naming` | does the new package boundary actually hold, or did the move just relabel the problem? are the names right for what is inside them? |-| `over-engineering` | anything introduced that is not load-bearing: speculative abstraction, indirection with one caller, a guard entry that guards nothing, machinery kept alive after its reason expired |-| `test-and-docs-sync` | guard config / closure-test predicate / design-doc snippet in agreement; docs describing the old tree; a check that now passes vacuously |--**Reading the verdicts:** treat a finding as a real defect only after you confirm it against the code. Reviewers with no context will sometimes flag an intentional ruling from the [Decisions](#decisions) table as a bug — that is expected and is not a reason to reverse the ruling; note it and move on. Design tradeoffs that are not silent bugs get captured as deferred follow-ups in `wip/refactoring/`, not reflexively fixed.-------## Decisions--Inherited from the design doc (already ruled — do not re-litigate):--| id | ruling |-| --- | --- |-| **D-M1-1** | Pipe manifest → `pipelex/pipe_machinery/registry_models.py` as `PipeRegistryModels`; M3 creates the package, M1 fills it |-| **D-M1-3** | `core/interpreter/` + `core/bundles/` → `pipelex/mthds_parsing/`; `PipelexInterpreter` → `MthdsParser` |-| **D-M2-1** | Vendors → `pipelex/providers/`, flat, no capability nesting |--Ruled during the **2026-07-27 review**:--| id | ruling | why |-| --- | --- | --- |-| **D-M1-2** | ~~`pipe_blueprint.py` is runtime and stays in `core/`~~ → **REVERSED. It is interpreter-layer and moves**, along with `validation.py`, `template_guard_lint.py` and `handle_pipe_errors.py` | The measurement snippet counts **outbound** edges, which answers "is X a leaf?" not "which layer owns X?". The layer question is **inbound**: zero declared runtime-layer modules import any of these four. Runtime does not know about pipes |-| **D-M1-4** | **Rename** `PipelexInterpreterError` → `MthdsParserError`, add the `redirect_maps` entry, and carry **five** repos into the sweep | The premise "no external consumer imports `PipelexInterpreter`" was false; four TS repos consume it as an `error_type` **wire string**, which the redirect does not help |-| **D-M1-5** | **Delete** `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` and their `is_interpreter` branches | Correct *because* D-M1-2 was reversed. Under the original ruling this would have silently relaxed the one entry `hub-layering.md:220` calls load-bearing |-| **D-M1-6** | **Add** `"pipe_signature"` to `INTERPRETER_PACKAGES` | Verified against all five runtime entry points: zero `pipe_signature` modules loaded. Safe, no pre-existing leak, and independent of the moves |-| **D-M2-2** | The four `cogt` config imports: accepted + documented (unchanged). The factory imports: **two**, not three, fixed by a **neutral `cogt/img_gen/` mapping module** — **no registry** | VertexAI is being removed so its edge self-resolves. The registry cannot dispatch these: `make_args_for_model` takes no sdk, dispatch is by `AspectRatioTaxonomy`, and gateway is one SDK spanning both taxonomies. A registry slot would also force a plugin-API bump for two import sites |-| **D-M1-7** | **M1 stacks on M3** (PR → M3, retargeted to `dev` on merge). M2 lands after M1 and re-acks drift post-rebase | The plan asserted both "M3 → M1" and "each track branches from #1064 against `dev`"; M1 cannot be both. M1/M2 share three files, so they are not operationally parallel |-| **D-M2-3** | **M2 is not release-gated** and comes out of the sweep table | Measured: zero external consumers import `pipelex.plugins.<vendor>` |-| **D-M1-8** | **`PipelexBundleBlueprintValidationErrorData` moved to `pipelex.core.exceptions`**, not into `mthds_parsing/` with the parser that raises it | Ruled during M1a under the authority M1c's plan granted ("if the closure test *does* fail on it, move the data class to a runtime-layer home instead"). It does fail: `core.memory.working_memory_factory` reaches it, and the closure test's `INTERPRETER_CORE_EXCLUDED` existed for exactly that. `core/exceptions.py` already holds the two sibling structured error-data models keyed on the same `PipeValidationErrorType`. Moving the leaf is what let the exclusion be deleted outright rather than carried forward |-| **D-M2-4** | **M2 is stacked on M1 on one branch**, not a parallel branch off #1064 rebased afterwards | The plan's own [Gating](#gating) already prescribed the landing order M3 → M1 → M2 and warned that the three shared files make them non-parallel. Stacking satisfies the order, removes the conflict, and removes the mandatory post-rebase drift re-ack — the ack recorded at CHECKPOINT M2 is against the final tree rather than a tree that will move |-| **D-R-1** | **No third layer** between runtime and interpreter | A layer encodes a forbidden arrow; there is only one (`runtime_hub ↛ interpreter_hub`). The shared kernel a third layer would hold already exists as `core/`'s value model, which both layers use. The pipe vocabulary fails the entry test — only the interpreter needs it |-| **D-F1-1** | **Two mapping modules, not one.** `cogt/img_gen/img_gen_gemini_mapping.py` + `cogt/img_gen/img_gen_gpt_mapping.py` | The plan said "a neutral `cogt/img_gen/` mapping module", singular. The two taxonomy families share **zero** code, come to ~500 lines together, and cover disjoint `AspectRatioTaxonomy` members; the repo files one topic per module, and the existing tests were already split per family. Named on the package's own `img_gen_*` prefix convention, with classes `ImgGen<Family>Mapping` to match `ImgGenArgsFactory` / `ImgGenParamSupport` |-| **D-F1-2** | **Rename the classes and the vendor-suffixed methods**, rather than carrying `GoogleImgGenFactory` / `OpenAIImgGenFactory` into `cogt/` | Two things were wrong in the new home, and both are the defect this track keeps finding — a name that describes where the code used to live. (a) The **vendor** is not what the mapping is keyed by: dispatch is by model *family*, and the gateway resolves Gemini geometry through a Portkey SDK, so "Google" names a party that is not always involved. (b) "Factory" contradicts the repo's own convention (`make_from_*`); these are lookup tables and validators. Renames measured in-tree only: **zero** consumers in any sibling repo |-| **D-F1-3** | **`moderation_literal` returns `None` instead of the OpenAI `omit` sentinel** | Load-bearing for the move, not a drive-by simplification: `Omit`/`omit` come from `from openai import …`, so keeping the sentinel would have put a hard vendor-SDK import in the neutral layer — exactly what F1 exists to remove. Verified equivalent rather than assumed: the sole caller already collapsed the non-`str` case to "emit no key" (`img_gen_args_factory.make_args_from_safety_checker`), and `openai_img_gen_worker.py:78` only ever pops a `str`. The emitted API arguments are identical on every path |-| **D-F1-4** | **Add a neutrality test** (`tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py`) | Nothing in the repo can catch a regression here. `pipelex.cogt` and `pipelex.providers` are **both** runtime-layer, so the hub-layering guard and the import-closure test are blind to an edge between them *by construction* — the property F1 buys would otherwise be unguarded from the moment it landed, which is the shape of the M2 finding Codex #5 caught. Two complementary checks because the coupling has two routes back: an AST read of the modules' own imports (catches a fresh `from openai import omit`) and a subprocess closure measurement (catches a `pipelex.cogt.*` import that drags an adapter in behind it). The module list is globbed from disk so a third family is covered the day it lands. ⚠ **The first version guarded that glob in the wrong place** — see the [review round](#review-round--done-2026-07-28-fixes-applied-1) |-------## Measurements--Baseline, measured **2026-07-27** on `bc30149c7` (venv-synced, subprocess per module — see the design doc's snippet).--Core modules loading > 0 interpreter modules (`interp_mods`, `pulls interpreter_hub`):--| module | interp_mods | hub | moved by |-| --- | --- | --- | --- |-| `core.registry_models` | 97 | yes | M3 |-| `core.pipes.pipe_factory` | 51 | yes | M1b |-| `core.pipes.rendering.input_renderer` | 51 | yes | M1b |-| `core.pipes.rendering.output_renderer` | 51 | yes | M1b |-| `core.pipes.pipe_abstract` | 33 | no | M1b |-| `core.bundles.pipe_sorter` | 30 | no | M1a |-| `core.bundles.pipelex_bundle_blueprint` | 30 | no | M1a |-| `core.interpreter.bundle_elaborator` | 30 | no | M1a |-| `core.interpreter.interpreter` | 30 | no | M1a |--Measured **0** outbound and therefore worth restating: `core.pipes.pipe_blueprint` (**moves anyway — D-M1-2 reversed**, see the inbound test below), and the four leaf modules that move for cohesion — `core.bundles.exceptions`, `core.interpreter.exceptions`, `core.interpreter.helpers`, `core.interpreter.validation_error_categorizer`.--### The inbound test — added 2026-07-27, and it is the one that decides layer--The classification snippet above counts **outbound** edges. That tells you whether a module is a *leaf*, not which layer owns it. A module can import nothing and still be exclusively interpreter business. The layer question is **who needs this** — measured against the *declared* runtime-layer packages:--```bash-RUNTIME='pipelex/(cogt|plugins|reporting|system|tools|runtime_hub|core/(concepts|domains|memory|stuffs)|core/pipes/(inputs|stuff_spec))'-for m in pipe_blueprint pipe_output validation variable_multiplicity template_guard_lint handle_pipe_errors exceptions; do- n=$(grep -rln "core\.pipes\.$m\b" pipelex/ --include="*.py" | grep -cE "$RUNTIME")- printf "core.pipes.%-24s %s\n" "$m" "$n"-done-```--Result on `89ae4950b`: `pipe_output` 4 · `variable_multiplicity` 5 · `exceptions` 1 → **runtime, stay**. `pipe_blueprint` 0 · `validation` 0 · `template_guard_lint` 0 · `handle_pipe_errors` 0 → **interpreter, move**.--The control matters: `pipe_output` and `variable_multiplicity` score non-zero, so the test discriminates rather than flagging everything. ⚠ It measures against *declared* runtime packages; `pipeline/` and `pipe_run/` are undeclared straddlers, so re-verify any move against the closure test.--Other baselines: `cogt → specific vendor` = 7 statements (4 config, 2 img-gen factory, 1 inline `vertexai_factory`). Runtime entry-point closures (`runtime_hub`, `plugins.builtins`, `content_generator`) currently pull in only `pipelex.pipeline` + `pipeline.pipeline_models` from the straddler zone.--### Post-M3, measured 2026-07-27--Baseline above re-taken on `95a1e9bf7` before any edit: **identical** to the table — same nine modules, same counts. No drift since `bc30149c7`.--After M3, with `"pipe_machinery"` added to the snippet's `I` set:--| module | interp_mods | hub | moved by |-| --- | --- | --- | --- |-| ~~`core.registry_models`~~ | ~~97~~ → **0** | **0** | ✅ M3, done |-| `core.pipes.pipe_factory` | 51 | yes | M1b |-| `core.pipes.rendering.input_renderer` | 51 | yes | M1b |-| `core.pipes.rendering.output_renderer` | 51 | yes | M1b |-| `core.pipes.pipe_abstract` | 33 | no | M1b |-| `core.bundles.pipe_sorter` | 30 | no | M1a |-| `core.bundles.pipelex_bundle_blueprint` | 30 | no | M1a |-| `core.interpreter.bundle_elaborator` | 30 | no | M1a |-| `core.interpreter.interpreter` | 30 | no | M1a |--Nine → eight. Every other module's count is **unchanged**, which is the expected shape: `registry_models` had exactly one consumer and was on no other module's import path.--Inverted `core → pipe_*` import statements: **43 → 19** — `pipelex_bundle_blueprint` 12 · `bundle_elaborator` 4 · `output_renderer` 2 · `pipe_abstract` 1. All 19 belong to modules M1 hoists, so M1's target of **0** needs no further work in `core/` beyond the moves already planned.--### Post-M1, measured 2026-07-27 on `10080cf26`--Classification snippet with `I` = the nine interpreter packages: **zero** `pipelex.core.*` modules report a non-zero `interp_mods` or `hub`. The table is empty — M1's headline criterion, reached in two steps (M1a took it 8 → 4 by hoisting the parser, M1b took it 4 → 0 by hoisting the Pipe machinery).--Inverted `core → pipe_*` import statements: **43 → 19 (M3) → 3 (M1a) → 0**. The 3 that survived M1a were `pipe_abstract`'s one `pipe_signature.exceptions` import and `output_renderer`'s two deferred `pipe_controllers` imports under `TYPE_CHECKING` — both modules M1b moved, so no further work in `core/` was needed.--Inbound test, re-derived at move time rather than trusted: everything that moved scored **0** declared runtime-layer importers (`pipe_blueprint`, `validation`, `template_guard_lint`, `handle_pipe_errors`, `pipe_abstract`, `pipe_factory`, `rendering`); everything that stayed scored non-zero (`pipe_output` 4, `variable_multiplicity` 5, `exceptions` 1). The control still discriminates, which is what makes the verdict meaningful.--`core/pipes/` final contents: `inputs/`, `stuff_spec/`, `exceptions.py`, `pipe_output.py`, `variable_multiplicity.py` — exactly the runtime half the plan predicted.--### Post-M2, measured 2026-07-28--The move: **17** vendor packages + `builtins.py` from `pipelex/plugins/` to `pipelex/providers/`. **136** files rewritten, **1364** substitutions, of which **191** string literals (predicted 189) and **145** `subject_grants.toml` path keys (12 grants stay, all on mechanism modules).--| | before | after |-| --- | --- | --- |-| directories under `pipelex/plugins/` | 17 vendors + mechanism | **0 vendors** — mechanism modules only |-| `RUNTIME_LAYER_PACKAGES` entries | 7 | **8** (`pipelex.providers` added) |-| source files outside `providers/` naming a specific vendor | 3 | **3** (unchanged — the documented `cogt` edges) |-| `pipelex/plugins/` modules naming a vendor | 1 (`builtins.py`) | **0** |--`INTERPRETER_PACKAGES` is **unchanged** — M2 adds a runtime-layer package, so the matched triple (guard tuple / closure predicate / hub-layering snippet / design-doc snippet) is undisturbed, and the design doc needed no edit. Verified by script rather than assumed: the closure predicate and the doc snippet still name the same set.--### Post-F1, measured 2026-07-28--| | before | after |-| --- | --- | --- |-| `cogt → specific vendor` import statements | 7 | **5** — the four `config_cogt.py` config classes (documented, D-M2-2) + the deferred `VertexAIFactory` |-| source files outside `providers/` naming a vendor module | 3 | **2** (`cogt/config_cogt.py`, `cogt/model_backends/backend_factory.py`) |-| third-party packages imported by the img-gen mapping modules | 1 (`openai`) | **0** |-| `pipelex.providers.*` modules in the mapping modules' import closure | — | **0**, measured in a fresh interpreter |--⚠ The vendor-segment character class matters here too (the M2 trap): `[a-z0-9_]+`, not `[a-z_]*`. The measurement above is the whole verdict for F1 — the rewrite itself was keyed on literal module paths and was never at risk.--The mutation that proves the closure check discriminates: adding one `pipelex.providers.google.google_factory` import to a mapping module makes it report **10** provider modules, not one — `google_factory` reaches `pipelex.config`, which reaches `config_cogt`, which names the four vendor configs. The documented `cogt → config` inversion is therefore also the shortest path back to full vendor coupling, which is worth knowing before anyone calls it harmless.--*(Append post-phase re-measurements here as each checkpoint clears.)*-------## Review findings--`/plan-eng-review`, 2026-07-27, against `89ae4950b`. Eight issues, all ruled. Recorded so the reasoning survives the checkpoint.--| # | finding | ruling |-| --- | --- | --- |-| 1 | "No external consumer imports `PipelexInterpreter`" was false — 5 repos, and 4 consume it as an `error_type` **wire string** that renaming breaks silently | Rename; carry all 5 into the sweep (D-M1-4) |-| 2 | `conformance/` `ALLOWED_SURFACE` + `docs/specs/` pin `core.pipes.pipe_abstract`; unmentioned by the plan, and `_hub`'s suite cannot catch it | Hard item at CHECKPOINT M1, not sweep work |-| 3 | D-M1-2 classified by **outbound** imports; the inbound test says `pipe_blueprint` + 3 more are interpreter-only | D-M1-2 reversed; all four move; this makes D-M1-5's deletion honest and saves a doc rewrite |-| 4 | M2 has **zero** external blast radius; the "one wave" argument does not cover it | M2 de-gated from the sweep (D-M2-3) |-| 5 | The `hub-layering-convention` drift contract fires in all 3 tracks; only M1c had an ack | Ack steps added to M3 and M2 |-| 6 | The guard test needs a full rewrite, not a one-line fix — and 4 assertions go **vacuously green** between M1b and M1c | Rewrite wholesale in the collapse commit |-| 7 | 189 (M2) + 15 (M1) **string-literal** module references that no import rewrite or type checker sees | Added to ground rule 5, budgeted per track |-| 8 | F1's "dispatch through `inference_backend_registry`" does not typecheck — it is `MakeWorkerFn`-only | F1 re-scoped to 2 imports + a new registry slot (D-M2-2) |--Also settled: **no third layer** is needed (D-R-1).--### Outside voice — Codex, same day, 15 further findings--Run in-repo at `reasoning_effort=high`, told what the review above had already found. Verdict: *"not implementation-ready."* Eight claims were verified against the tree; all held. All 15 are folded in.--| # | finding | where it landed |-| --- | --- | --- |-| **5** | **The M2 guard claim was backwards.** The plan said omitting `"pipelex.providers"` is caught by the transitive rule. It cannot be — `hub_layering_guard.py:677` filters through `is_runtime_layer`, so an **undeclared** package is excluded from the rule's domain. The plan named its riskiest step and pointed at a safety net that does not exist | M2 — explicit guard test |-| **14/15** | F1 had no workable dispatch key (`make_args_for_model` takes no sdk; dispatch is by taxonomy; gateway is one SDK spanning both) and implied an unplanned plugin-API bump | **F1 rewritten** — neutral mapping module, no registry |-| **3** | PR topology was self-contradictory (M3→M1 *and* each track based on #1064) | Gating — M1 stacks on M3 |-| **1** | `mthds_parsing` unguarded between M1a and M1c | Predicate updated in **M1a** |-| **2** | `mthds_parsing/` and `providers/` had no `__init__.py` step; ruff `INP001` fails the commit | Both tracks |-| **4** | M1 and M2 are architecturally but **not operationally** independent; a rebase invalidates the drift ack | Gating — landing order + re-ack |-| **6** | `DIRTY_ENTRY_POINT` proves *a* token matches, not that each new one is spelled right | M1c — leaf probe per package |-| **7** | The M3 regression test was too weak — one pipe + one stuff misses a dropped list or model | M3 — full-set + disjointness |-| **8** | `subject_grants.toml:2615` embeds `PipelexInterpreter.make_pipelex_bundle_blueprint`; re-pathing alone leaves it stale | M1a |-| **9/10** | Hand-written importer and test-move inventories were materially incomplete (26 importer files, not ~11) | M1a / M1b — assert-zero-old-paths |-| **11** | The design doc still contradicted this tracker | Superseded banner added to the design doc |-| **12** | M2's "vendor imports nothing but mechanism = 0" is false by construction — cross-vendor edges are deliberately kept | Metric restated |-| **13** | Stale architectural prose in *source* (`contract.py:33-35`, `interpreter_plugins/builtins.py:3-8`) | M2 sweep |--Clean on two axes it checked independently: pydantic/kajson (the discriminated union keys on the stable `type` field and no registered concrete pipe class moves) and entry-point metadata / relative imports.--## Follow-ups from the review--Not in this wave. Captured with their evidence so they are not re-derived.--> **Assessed and written up as an implementation handoff: [`wip/refactoring/review-follow-ups.md`](wip/refactoring/review-follow-ups.md).** Each of the three open items below was re-verified against the tree on 2026-07-28 at `7ddb77f87` and carries a stable id there — **FU-1**, **FU-2**, **FU-3** — plus a concrete recommendation, reproduction commands and sizing. Cite the ids. The bullets below remain the record of *what was noticed*; the handoff is the record of *what to do*. Target branch: `refactor/Hub-2`, after #1067 merges into it.--- [ ] **FU-1 — Decouple `error_type` from the Python class name.** Give each `PipelexError` an explicit stable wire identifier instead of deriving `error_type` and the docs `type_uri` from the class name. Every error-class rename is currently a silent break for any consumer switching on the string, and nothing in the repo flags it. Evidence: `mthds-starter-js/src/lib/errors.ts:176`, `pipelex-starter-js/src/lib/errors.ts:257`, `vscode-pipelex/.../cliValidationBackend.test.ts:99`, `playroom/src/app/api/graph/route.ts:119` — **all four re-confirmed live 2026-07-28, still branching on the retired `PipelexInterpreterError`**. Would also remove the need for the `redirect_maps` workaround. Independent of all three tracks; touches the error model and the agent-CLI JSON envelope, so it needs a matching spec/conformance change. → The assessment **splits this in two**: a golden identity snapshot closes the "nothing flags it" half cheaply and with no spec change, and is what should land before the sweep; the `_declared_error_type` refactor is deferred, since the no-backward-compat rule means it cannot save the four consumers anyway. Note `title` / `type_uri` already have the `_declared_*` hatch — `error_type`, the only one machines branch on, is the one that lacks it. See [FU-1](wip/refactoring/review-follow-ups.md#fu-1--nothing-flags-an-error-class-rename-and-it-is-a-wire-break).-- [ ] **FU-2 — Close the two holes in the img-gen neutrality guard, or downgrade its comment to what it proves.** Raised by the [third F1 review round](#third-review-round--review-done-2026-07-28); recorded rather than fixed because both are cheap and neither is worth machinery on a track whose whole argument was "placement, not indirection". (a) **Transitive vendor SDKs are unguarded.** `_import_roots` reads only the mapping modules' own import statements and `_CLOSURE_SCRIPT` counts only `pipelex.providers`, so an `openai` import reached through some other `pipelex.cogt` module passes both checks. ~~Measured clean today — **zero** vendor-SDK imports anywhere in `pipelex/` outside `providers/` — and *that* is the stronger invariant, unguarded and worth a repo-wide test of its own rather than a denylist bolted onto this one.~~ (b) **The glob under-claims its own coverage.** `_MAPPING_DIR.glob("img_gen_*_mapping.py")` is non-recursive and suffix-keyed, so "a third taxonomy family is covered the day it lands" holds only for a family landing in that exact directory under that exact name. Either bind the convention with a test or soften the comment.-- ⚠ **Correction, 2026-07-28 — the struck sentence is false, and it was the stated justification for a test that would be red on day one.** Struck rather than silently rewritten, because the defect is instructive: five modules outside `providers/` do import a vendor SDK — `tools/pdf/pypdfium2_renderer.py` (module-level), `tools/storage/s3_storage_provider.py`, `tools/storage/gcp_storage_provider.py`, `tracing/dynamodb_event_log.py`, `reporting/reporting_manager.py`. All legitimate: they are *infrastructure* SDKs (pypdfium2, boto3/botocore, google.cloud), which is exactly the shim-vs-implementation split M2's own review recorded for `providers/storage/`. The invariant that **is** true and worth pinning is narrower — `pipelex/cogt/**` imports zero vendor SDKs, and `cogt → pipelex.providers` is exactly the documented five statements. [FU-2](wip/refactoring/review-follow-ups.md#fu-2--the-img-gen-neutrality-guard-is-weaker-than-its-comment-and-its-recorded-remedy-is-wrong) carries the scan that produced this and the corrected remedy. **This is the fourth time on this branch that a check's justification, rather than the check, was the defect** — and the first where the bad justification was written into a *deferred* item, where nothing would have re-tested it before someone acted on it.-- [ ] **FU-3 — Gate the bookkeeping files a bulk rewrite silently breaks.** ⚠ Re-measured 2026-07-28: **both artifacts are clean today** (`subject_grants.toml` 0 out-of-order pairs; `.test_durations` 0 dead file paths, 2 node-id orphans that are the known profile-dependent `pipe_img_gen` parametrizations) — so this is about the *missing gate*, not a live defect. [FU-3](wip/refactoring/review-follow-ups.md#fu-3--the-bookkeeping-files-a-bulk-rewrite-breaks-are-still-ungated) recommends doing the sort check inside the existing `keyword_only_guard.py` and gating durations on the **file path** rather than the node id — a path check is unambiguous, needs no collection run, and needs no tolerance policy for the two benign orphans. Three instances on this branch, each found by hand well after the fact: `subject_grants.toml` losing its sort (fixed in `bc22ba934`), the matched triple disagreeing on `pipe_signature` (fixed in M3), and `.test_durations` carrying 112 orphan node ids across three commits (fixed in the third F1 round). All three share a shape — a generated or bookkeeping artifact that no gate validates, invalidated by a bulk path rewrite, invisible until someone measures it. A cheap `make check` addition covers two of them: assert `subject_grants.toml` keys are sorted, and assert every `.test_durations` node id resolves against a full unfiltered collection. ⚠ The collection must run with `-m ""` — the marker filter in `addopts` hides ~312 items, so a naive check would report every `e2e` entry as an orphan.-- [x] **Guard against vacuously-green string-predicate tests.** ✅ **Done in M1c** — see T10. Assert that every module qname referenced as a string literal in the guard and closure tests resolves to a real module. `is_runtime_layer` never checks existence, so a moved module silently converts assertions into tests of nonexistent paths — the M1b→M1c window is the worked example. Best done **after M1**, when the guard config is in its final shape.--## Cold-start brief--**Read this first in a new session.** Keep it true at every checkpoint.--- **Where:** worktree `_hub/`, based on `refactor/Hub-2` (PR #1064). **One branch**: `refactor/Modularity-3`, pushed at `6e74c6f26`, carrying M3 + M1 + M2 + F1. F1 was developed on `refactor/Modularity-4` and merged in through PR #1065 — the separate-PR topology [Gating](#gating) prescribed for it, honoured and now closed; that branch is deleted. The track's own PR is **[#1067](https://github.com/Pipelex/pipelex/pull/1067), against `refactor/Hub-2`**. Related memory: `project_modularity_refactors.md`, `project_hub_split_refactor.md`.-- **What:** three refactors continuing the hub split — M3 (split the boot manifest, seed `pipe_machinery/`), M1 (hoist core's interpreter half into `mthds_parsing/` + `pipe_machinery/`, collapse the guard declaration), M2 (split `plugins/` into mechanism + `providers/`), then follow-up F1 (the two img-gen factory imports, fixed by moving the mappings inward — **no registry**, see D-M2-2).-- **Why now:** **M3 and M1** break external imports, and the repo already owes a release-gated cross-repo sweep for the hub split — landing them first means consumers absorb one breaking wave instead of several. **M2 and F1 do not** (measured zero external consumers for both) and can land on their own schedule.-- **State:** **M3, M1, M2 and F1 all done and committed on one branch — sitting at CHECKPOINT F1.** M1 is three commits: `0f0309b8f` (M1a, parser → `mthds_parsing/`), `c9c45c475` (M1b, Pipe machinery → `pipe_machinery/`), `10080cf26` (M1c, declaration collapse + guards + docs), plus `7beda698f` for the review fixes. M2 is one commit on top (D-M2-4 — stacked, not parallel) plus `fa6f4fae9` for its review fixes, then F1. All gates green at every checkpoint, all exit criteria met. **Every track's review round is done and its fixes committed** — the moves cleared every time, every defect was docs/fixture/test-quality drift, and three placement items are deferred to `wip/refactoring/deferred-placement-follow-ups.md`. **F1 has had three rounds** (`correctness-and-boot`, `over-engineering`, then `/review` against the F1-only diff): no correctness defect in any of them, and the third round's fixes are the last of it. Only Phase 5 remains.-- **Blocking:** PR #1064 must merge before #1067 can retarget to `dev` and go in. **No open decisions.**-- **⚠ Two cross-repo edits are uncommitted in sibling repos** — `conformance/tests/pipelex_transport/test_data.py` and workspace-root `docs/specs/pipelex-transport-boundary.md`, one line each, repointing `PipeAbstract` to `pipelex.pipe_machinery`. They are release-gated with the rest of the sweep and must not be lost.-- **What M3 actually changed:** no module moved paths and no class was renamed — only the six pipe lists moved from `CoreRegistryModels` to `pipelex.pipe_machinery.registry_models.PipeRegistryModels`. M3 contributes **nothing** to the cross-repo sweep. **M1 is where the sweep debt is incurred**, and it is bigger than the module moves: `PipelexInterpreterError` → `MthdsParserError` is the `error_type` **wire string** four TypeScript consumers branch on, and the docs redirect does nothing for them.-- **What M2 confirmed, and the one thing it adds:** every M1 lesson below fired again. The test inventory in the plan was incomplete a third time (six flat modules needed per-module classification, and one — `test_inference_backend_coverage.py` — reads as a vendor test by name while being a mechanism test by subject). The generated-output lesson paid off directly: `_SUBSYSTEM_SECTIONS` was missing a `providers` row, the identical defect M1 hit with `mthds_parsing`, and `make gep` exits 0 either way. **The new one: a grep character class is a measurement bug.** `pypdfium2` has a digit, so `[a-z_]*` silently skips it — the rewrite was safe (literal vendor names) but the *verification* under-counted, which is worse, because the verification is what licenses "done". Use `[a-z0-9_]+`.-- **What M1 learned that M2 will hit again:**- 1. **Test inventories written in advance are wrong.** Both of M1's were materially incomplete. Derive the move list from each test's actual subject, at move time.- 2. **A `Path(__file__).parents[N]` in a moved test is a silent bug** — nothing static sees a parent count, and it fails only under the full suite. Sweep for it after every test move.- 3. **Doc enumerations are where `hub-layering.md` rots** — and the ones that go stale are rarely in the paragraph your diff touches. M1c found two (`The layer rule`, the must-not-name list) well away from the change. Grep for a *sibling* package name, not for the thing you moved.- 4. **Moving the leaf beats excluding it.** M1a's straddler decision is the general lesson: an exclusion records a placement problem, a move removes it. `pipeline` / `pipe_run` are the two left.- 5. `make cleanderived` deletes a gitignored generated test fixture that only the test targets rebuild, so pyright fails on unrelated errors until you regenerate it (command in [Phase 0](#phase-0--baseline)).-- **The four things that will bite you:** (1) re-path `subject_grants.toml` *before* `make agent-check`, or `fix-keyword-only` silently rewrites your subjects — note that a whole-tree textual rewrite re-paths them for free, including qualnames embedded in the key, which is how M1a's `PipelexInterpreter.make_pipelex_bundle_blueprint` fixed itself; (2) `pipelex.plugins.secrets` is a vendor dir but `pipelex.plugins.secrets_provider_registry` is a mechanism module — no prefix `sed`; (3) the guard tuple, the closure-test predicate, the hub-layering snippet and the design-doc snippet are a matched set — **the first three are now mechanically bound by tests** (M1c), the design doc's is not; (4) **string literals are module references too** — 189 in M2, invisible to every import tool.-- **What the rewrite method looked like, since M2 is the same shape at larger scale:** one Python script over `git ls-files`, an ordered longest-first substitution list (dotted paths, then filesystem paths, then test paths, then the class rename), excluding `CHANGELOG.md` / `TODOS.md` / `wip/` / `docs/errors/` — history and generated pages must not be rewritten. Then `grep` the whole tree for the old paths and assert the only survivors are in those excluded files. That completion check is what makes "did I get them all?" answerable.-- **The measurement trap that already caught this plan once:** the classification snippet counts *outbound* imports. It tells you whether a module is a leaf, **not** which layer owns it. Use the [inbound test](#the-inbound-test--added-2026-07-27-and-it-is-the-one-that-decides-layer) for layer decisions.-- **What F1 adds, and it generalizes past this track:** a placement fix *inside one layer* has no gate. Both `pipelex.cogt` and `pipelex.providers` are runtime-layer, so the hub guard and the closure test cannot see an edge between them by construction — every `cogt → vendor` inversion on this page is invisible to both. Whenever you fix one, the invariant you just bought is unguarded from that moment on unless you write the test yourself (D-F1-4). The same is true of the four `config_cogt` edges that stay, which is why they are documented rather than merely tolerated.-------## Implementation Tasks--Synthesized from the review's findings. Each derives from a specific finding above.--- [x] **T1 (P1, human: ~3h / CC: ~20min)** — M3 — Add the regression test pinning pipe + stuff classes into the class registry after boot- - Surfaced by: Test review — M3 splits `register_classes`; nothing asserts registry contents; failure is silent at boot- - Files: ~~`tests/unit/pipelex/test_hub_lifecycle.py`~~ → **new `tests/unit/pipelex/test_registry_models_split.py`** (one TestClass per module is a repo rule), `pipelex/pipelex.py`- - Verify: `make tb`, then drop one `register_classes` line and confirm the test goes red — ✅ done, and the stronger mutation too (drop one model from one list)-- [x] **T2 (P1, human: ~1d / CC: ~40min)** — M1b — Hoist `pipe_blueprint`, `validation`, `template_guard_lint`, `handle_pipe_errors` out of `core/`- - Surfaced by: Issue 3 — D-M1-2 classified by outbound imports; inbound test shows 0 runtime-layer importers- - Files: `pipelex/core/pipes/`, `pipelex/pipe_machinery/`, `pipelex/mthds_parsing/`- - Verify: inbound test reports ≥1 runtime importer for every module left in `core/pipes/`; `make chl`; closure test-- [x] **T3 (P1, human: ~2h / CC: ~15min)** — M1c — Update `conformance` ALLOWED_SURFACE + `docs/specs/pipelex-transport-boundary.md`- - Surfaced by: Issue 2 — active unskipped test pins `pipelex.core.pipes.pipe_abstract`; `_hub`'s suite cannot catch it- - Files: `conformance/tests/pipelex_transport/test_data.py`, `docs/specs/pipelex-transport-boundary.md`- - Verify: `make check-spec-links` in `conformance/`-- [ ] **T4 (P1, human: ~4h / CC: ~30min)** — Phase 5 — Expand the sweep table to 8 repos incl. the 4 `error_type` wire-string consumers- - Surfaced by: Issue 1 — the table named one repo; there are eight, and four consume a wire string- - Files: `TODOS.md`, workspace-root `CLAUDE.md` (✅ done)- - Verify: re-run the cross-repo grep; every hit appears in the table-- [x] **T5 (P2, human: ~2h / CC: ~15min)** — M1c — Rewrite `test_core_is_split_between_the_layers` wholesale- - Surfaced by: Issue 6 — six assertions invert or go stale; four go vacuously green between M1b and M1c- - Files: `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`- - Verify: `.venv/bin/pytest tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`-- [x] **T6 (P2, human: ~1h / CC: ~10min)** — M3 + M2 — Add `drift-ack` steps for `hub-layering-convention`- - Surfaced by: Issue 5 — `drift.toml:65-69` triggers on the guard; all three tracks touch it, only M1c acked- - Files: `TODOS.md`, `drift.toml`- - Verify: `make drift-check` green at each checkpoint — ✅ M3 half done: the contract opened exactly as predicted (only after `git add`; the digest reads the index), was reviewed for real, acked, and logged in `wip/drift-contracts/dogfood-log.md` (mandatory per ack). M2's ack landed at CHECKPOINT M2 — and M2 opened a *second* contract the plan did not predict, `config-docs`, because re-pathing the four vendor config imports touches `config_cogt.py`. Both reviewed for real, both acked, both logged.-- [x] **T7 (P2, human: ~1d / CC: ~30min)** — M2 — Rewrite the 189 string-literal module references- - Surfaced by: Issue 7 — invisible to import rewrites and pyright; 189 in M2, 15 in M1- - Files: `tests/unit/pipelex/plugins/`, `pipelex/plugins/`- - Verify: `make agent-test`; zero surviving `pipelex.plugins.<vendor>` literals-- [x] **T8 (P2, human: ~1d / CC: ~30min)** — F1 — Extract the taxonomy/geometry helpers into a neutral `cogt/img_gen/` mapping module; both sides import inward- - Surfaced by: Issue 8 + Codex #14/#15 — `make_args_for_model` takes no sdk, dispatch is by `AspectRatioTaxonomy`, gateway is one SDK spanning both; a registry slot would force a plugin-API bump- - Files: `pipelex/cogt/img_gen/img_gen_args_factory.py`, `pipelex/providers/{google,openai}/*_img_gen_factory.py`- - Verify: a test per taxonomy branch incl. the unmapped-taxonomy path; `pipelex.plugins.contract` untouched-- [x] **T11 (P1, human: ~2h / CC: ~15min)** — M2 — Add a guard test asserting `pipelex.providers.*` is runtime-layer- - Surfaced by: Codex #5 — the transitive rule filters through `is_runtime_layer`, so an omitted declaration is excluded from the check, not caught by it. No existing gate covers this- - Files: `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`- - Verify: drop `"pipelex.providers"` from the tuple and confirm the test goes red-- [x] **T12 (P2, human: ~2h / CC: ~15min)** — M1a — Fix the embedded qualname in `subject_grants.toml:2615` alongside the re-path- - Surfaced by: Codex #8 — the key carries `PipelexInterpreter.make_pipelex_bundle_blueprint`; re-pathing alone leaves it stale and hard-fails `check-keyword-only`- - Files: `subject_grants.toml`- - Verify: `make cko`-- [x] **T13 (P2, human: ~1h / CC: ~10min)** — ~~M1a~~ + ~~M2~~ — Create the two missing `__init__.py` files — ✅ both done (`pipelex/mthds_parsing/__init__.py`, `pipelex/providers/__init__.py`)- - Surfaced by: Codex #2 — ruff `select = ["ALL"]`, `INP001` exempt only for `tests/**`; both commits fail lint as written- - Files: `pipelex/mthds_parsing/__init__.py`, `pipelex/providers/__init__.py`- - Verify: `make agent-check`-- [ ] **T9 (P3, human: ~3d / CC: ~1 session)** — follow-up — Decouple `error_type` from the Python class name-- [x] **T10 (P3, human: ~4h / CC: ~25min)** — follow-up — Guard against vacuously-green string-predicate tests — ✅ **done in M1c**, both halves: `RUNTIME_LAYER_PACKAGES` entries and `INTERPRETER_PACKAGES` tokens must each resolve on disk, mutation-checked red-------## GSTACK REVIEW REPORT--| Review | Trigger | Why | Runs | Status | Findings |-|--------|---------|-----|------|--------|----------|-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |-| Codex Review | `/codex review` | Independent 2nd opinion | 1 | ISSUES FOUND → absorbed | 15 findings, all folded |-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR | 8 issues, 1 critical gap (closed) |-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | — |-| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |--- **CODEX:** ran in-repo at high reasoning effort; verdict *"not implementation-ready"*, 15 findings. Eight verified against the tree, all held. All folded in. Two reversed prior rulings: **F1 drops the registry** for a neutral `cogt/img_gen/` mapping module (no dispatch key exists), and **M1 stacks on M3** (the topology was self-contradictory). The sharpest catch: the plan claimed the transitive rule catches an omitted `RUNTIME_LAYER_PACKAGES` entry — it is the opposite, an undeclared package is excluded from the rule's domain (`hub_layering_guard.py:677`).-- **CROSS-MODEL:** 23 findings total, no overlap — the two passes were complementary rather than confirming. The eng review found *classification and blast-radius* errors (outbound-vs-inbound layer test, wire strings, missing consumer repos); Codex found *build-order and gate-efficacy* errors (lint failures, unguarded windows, a safety net that does not exist). Both agreed independently that F1's registry framing was wrong; only Codex found why.-- **VERDICT:** ENG CLEARED — ready to implement. Scope accepted as-is (three tracks + F1, three stacked PRs); 23 findings folded; 1 critical test gap closed by the regression rule.--NO UNRESOLVED DECISIONSdiff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.mdindex 5731e9a16..8ef18de26 100644--- a/docs/contribute/hub-layering.md+++ b/docs/contribute/hub-layering.md@@ -122,7 +122,18 @@ The dividing line is worth stating as a rule of thumb: **if it names a `Pipe`, i### Injected providers, not ambient lookups-The data-model half used to reach for `get_concept_library()` / `get_native_concept()` / `get_required_concept()` — ambient lookups into a loaded method, which is exactly what made `core/` inseparable from the interpreter. It now takes what it needs as a parameter, through one read-side contract: `ConceptProviderAbstract` (`pipelex/core/concepts/concept_provider_abstract.py`) — resolve a ref, a code, or a native code into a `Concept`, and answer compatibility questions.+The data-model half used to reach for `get_concept_library()` / `get_native_concept()` / `get_required_concept()` — ambient lookups into a loaded method, which is exactly what made `core/` inseparable from the interpreter. It now takes what it needs as a parameter, through one read-side contract: `ConceptProviderAbstract` (`pipelex/core/concepts/concept_provider_abstract.py`) — resolve a ref, a code, or a native code into a `Concept`, answer compatibility questions about two of them, and resolve a concept's declared `structure_class_name` into the class itself.++**Class resolution is part of that contract, and it took a second pass to get there.** The hub split moved *concept* resolution onto the provider but left *class* resolution ambient one level down, inside `Concept` itself: the model reached `get_class_registry()` to answer "what is my structure class?" and to run the structural half of a compatibility check. A `Concept` is a subclass of the MTHDS-protocol wire model `ConceptAbstract` — pure serializable data — so that coupled a standard-owned wire model to a Pipelex process-global. `ConceptProviderAbstract.get_structure_class` decouples them: a `Concept` carries the class *name* as a plain protocol string, and turning a name into a type is the provider's business, never the model's.++Be precise about what that buys, because it is easy to overstate. The read is still **ambient** — `ConceptLibrary.get_structure_class` calls `get_class_registry()`, which selects a registry from the current async context rather than from the provider instance (a `ConceptLibrary` holds none; the per-library `ClassRegistry` lives on `Library`). What changed is that the whole tree now has *one* implementation of that read, behind one seam, instead of it happening inside a wire model. Scoping it to the provider's own library is consequently a one-place change — see `wip/inputs/provider-scoped-class-resolution.md` for why nothing needs it yet.++Two shapes fall out of that, and they are the ones to copy:++- **Compatibility is two tiers, composed by the thing that owns resolution.** `Concept.are_compatible_by_declaration` is pure over the model's fields (plus an injected `concept_resolver`): dynamic short-circuits, ref equality, declared-class-name equality, `refines` chains. `ConceptLibrary.is_compatible` asks that first and only resolves classes when it is inconclusive. A name that should have resolved and didn't now raises `ConceptStructureClassNotFoundError` instead of answering `False` — "unknown" and "incompatible" are different answers, and conflating them was a latent wrong-verdict bug.+- **Rendering takes the resolved class, not the name.** `Concept.render_concept_representation` receives a `structure_class`; `StuffSpec.render_stuff_spec` takes the `concept_provider`, resolves once, and passes the class down. Interpreter-layer callers (`output_renderer`, `input_renderer`, `pipe_io_contracts`, `builder/runner_code`) supply `get_concept_library()`.++The **write side** stays ambient on purpose: `concept_factory` and `structure_generation/generator.py` generate structure classes and register them at library-load time, which is genuinely the registry's business. That those two are the only modules under `pipelex/core/concepts/` touching the registry is pinned as a golden set by `tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py` — nothing else can see it, since both the accessor and its users are runtime-layer.It is **read-side only**. Managing a library — adding, removing, listing, setup/teardown — stays in the interpreter layer: `ConceptLibraryAbstract` *extends* it, keeping its management half in `libraries/`. Splitting read from write is what lets a core module state its dependency honestly ("I need something that can resolve concepts") without inheriting a library lifecycle it has no business touching.@@ -130,7 +141,9 @@ It is **read-side only**. Managing a library — adding, removing, listing, setuThe injection point is the interpreter layer. `pipe_factory`, `input_renderer` and `output_renderer` — already interpreter-bound, so nothing is lost — resolve the concept library themselves and pass it down; `pipeline/execution_seams.py` does the same for `WorkingMemoryFactory`. That is the one-way arrow the whole design rests on, applied inside `core/`: **the half that knows about a loaded method resolves the collaborator and hands it downward.**-When you add a core data-model function that needs a concept, add a `concept_provider` parameter. Do not add a hub import — the guard will reject it, and the closure test will tell you which entry point you broke.+When you add a core data-model function that needs a concept — or a concept's structure class — add a `concept_provider` parameter. Do not add a hub import, and do not reach for `get_class_registry()`: the guard will reject the first, and the second is the coupling this section exists to describe.++One module outside `core/` cannot import either hub at module level, and the constraint is a **static-analysis** cycle rather than a runtime one — worth knowing before you restate it. `pipe_machinery/pipe_abstract.py` reads `class_registry_access` directly to decorate graph-registry entries with a JSON Schema. It is *not* in `runtime_hub`'s runtime closure (`plugins.orchestrator_registry` and `pipe_run.pipe_job` reach it through `TYPE_CHECKING`-only edges, and a clean-interpreter probe shows all three absent) — but pyright's `reportImportCycles` counts those edges, so either hub import is a hard type-check failure, reported at `interpreter_hub.py` where no line-level ignore can reach it. Deferring the import does not dodge it. The below-both-hubs accessor is what that case is for; its docstring records the measurement.## Where the built-in plugins splitdiff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.pyindex a907b0245..05652b094 100644--- a/pipelex/builder/runner_code.py+++ b/pipelex/builder/runner_code.py@@ -21,6 +21,7 @@ from pipelex.core.concepts.concept_representation_generator import (from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecsfrom pipelex.core.pipes.variable_multiplicity import VariableMultiplicity+from pipelex.interpreter_hub import get_concept_libraryfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.runtime_hub import get_class_registry@@ -115,7 +116,7 @@ def _collect_imports_for_inputs(inputs: InputStuffSpecs, *, class_name_overridesfor input_req in inputs.root.values():concept = input_req.concept- structure_class = concept.get_structure_class()+ structure_class = get_concept_library().get_structure_class(concept=concept)# Get imports from the representation generator (includes nested custom classes)generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON, class_name_overrides=class_name_overrides)@@ -227,6 +228,7 @@ def generate_runner_code(for var_name, input_req in pipe.inputs.root.items():is_multiple = _is_multiple(input_req.multiplicity)result, _ = input_req.concept.render_concept_representation(+ structure_class=get_concept_library().get_structure_class(concept=input_req.concept),output_format=ConceptRepresentationFormat.PYTHON,is_multiple=is_multiple,class_name_overrides=overrides,diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex 0960c339e..5774e72d6 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -27,6 +27,7 @@ from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.stuff_viewer import render_stuff_viewerfrom pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir+from pipelex.libraries.concept.concept_library import ConceptLibraryfrom pipelex.mthds_parsing.exceptions import MthdsParserErrorfrom pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError@@ -341,9 +342,14 @@ async def _execute_run(# ConceptValueError (a ValueError) and CsvError would otherwise escape execute_run's generic# `except PipelexError` and read as "Failed to execute pipeline" (or as a raw traceback).try:- # get_structure_class() can raise ConceptValueError if the output concept has no registered- # structure class; keep it inside the guard so that, too, is framed as a save-csv failure.- csv_row_model = csv_main_stuff.concept.get_structure_class()+ # An empty library, not the loaded method's: `runner.execute` tore the run library down on+ # its way out, so by here there is no current library to ask. `ConceptLibrary.make_empty()`+ # resolves against the process class registry, which still holds the generated structure+ # classes — the same place this lookup has always landed — while keeping the one typed+ # "name -> StuffContent subclass, or ConceptStructureClassNotFoundError" implementation.+ # That error is a ConceptValueError, so an unresolvable class is framed as a save-csv+ # failure by the guard below rather than escaping as a pipeline failure.+ csv_row_model = ConceptLibrary.make_empty().get_structure_class(concept=csv_main_stuff.concept)# Validate the row flatness BEFORE touching the filesystem, so a non-flat output leaves no# directory behind (the suffix was already validated up front).flat_field_names(csv_row_model)diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.pyindex 88d37f579..ab3933c21 100644--- a/pipelex/core/concepts/concept.py+++ b/pipelex/core/concepts/concept.py@@ -3,8 +3,6 @@ from typing import Any, Callablefrom mthds.protocol.concept import ConceptAbstractfrom pydantic import field_validator-from pipelex import log-from pipelex.base_exceptions import PipelexUnexpectedErrorfrom pipelex.core.concepts.concept_representation_generator import (ConceptRepresentationFormat,ConceptRepresentationGenerator,@@ -16,11 +14,8 @@ from pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.domains.exceptions import DomainCodeErrorfrom pipelex.core.domains.validation import validate_domain_codefrom pipelex.core.qualified_ref import QualifiedRef-from pipelex.core.stuffs.image_field_search import search_for_nested_image_fieldsfrom pipelex.core.stuffs.stuff_content import StuffContent-from pipelex.system.registries.class_registry_access import get_class_registryfrom pipelex.tools.misc.string_utils import pascal_case_to_sentence-from pipelex.tools.typing.class_utils import are_classes_equivalent, has_compatible_fieldclass Concept(ConceptAbstract):@@ -82,15 +77,41 @@ class Concept(ConceptAbstract):def is_native_concept(cls, concept: "Concept") -> bool:return NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=concept.concept_ref)+ @property+ def declares_a_structure_class(self) -> bool:+ """Whether `structure_class_name` names a class that can be resolved at all.++ True for every concept but `native.Anything`, whose content class deliberately does not+ exist — so the name derived mechanically from its code never resolves, and asking a provider+ for it is a category error rather than a missing registration.+ """+ if not SpecialDomain.is_native(domain_code=self.domain_code):+ return True+ return not NativeConceptCode.is_structureless_concept(self.code)+@classmethod- def are_concept_compatible(+ def are_compatible_by_declaration(cls,*,concept_1: "Concept",concept_2: "Concept",- strict: bool = False,concept_resolver: Callable[[str], "Concept | None"] | None = None,) -> bool:+ """Whether the two concepts' *declarations* establish that `concept_1` satisfies `concept_2`.++ This is the string tier of compatibility: dynamic short-circuits, ref equality, declared+ structure-class-name equality, and `refines` chains — the last resolved through+ `concept_resolver` when a refinement crosses a package boundary (`dep->domain.Code`).++ The two verdicts are asymmetric, deliberately. `True` means "established by the+ declarations". `False` means "*not established at this tier*" — NOT "incompatible": two+ concepts whose declarations say nothing about each other may still be compatible through+ their structure classes. Composing the two tiers is `ConceptLibrary.is_compatible`'s job,+ because resolving a `structure_class_name` into a class is a library's business, not a+ wire model's.++ Pure over the model's own fields (plus the injected resolver): no registry, no ambient state.+ """if NativeConceptCode.is_dynamic_concept(concept_code=concept_1.code):return Trueif NativeConceptCode.is_dynamic_concept(concept_code=concept_2.code):@@ -127,65 +148,12 @@ class Concept(ConceptAbstract):if refines_1 == refines_2:return True- # Check class-based compatibility- # This now works even when one or both concepts have refines, since we generate- # structure classes that inherit from the refined concept's class- concept_1_class = get_class_registry().get_class(name=concept_1.structure_class_name)- concept_2_class = get_class_registry().get_class(name=concept_2.structure_class_name)-- if concept_1_class is None or concept_2_class is None:- return False-- # Check if classes are structurally equivalent (same fields, types)- if are_classes_equivalent(concept_1_class, class_2=concept_2_class):- return True-- if strict:- # In strict mode, only structural equivalence is accepted- return False-- # Check if concept_1 is a subclass of concept_2- # This handles inheritance from refined concepts (e.g., RefusalEmail inherits from TextContent)- try:- if issubclass(concept_1_class, concept_2_class):- return True- except TypeError:- pass-- # Check if concept_1 has compatible fields with concept_2- return has_compatible_field(concept_1_class, target_type=concept_2_class)-- @classmethod- def is_valid_structure_class(cls, structure_class_name: str) -> bool:- if get_class_registry().has_subclass(name=structure_class_name, base_class=StuffContent):- return True- if get_class_registry().has_class(name=structure_class_name):- log.warning(f"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent")return False- def get_structure_class(self) -> type[StuffContent]:- """Get the structure class for this concept.-- Returns:- The StuffContent subclass, or None if not found- """- structure_class = get_class_registry().get_class(name=self.structure_class_name)- if structure_class is None:- msg = f"Concept class '{self.structure_class_name}' not found"- raise ConceptValueError(msg)- return structure_class-- def search_for_nested_image_fields_in_structure_class(self) -> list[str]:- """Recursively search for image fields in a structure class."""- structure_class = get_class_registry().get_required_subclass(name=self.structure_class_name, base_class=StuffContent)- if not issubclass(structure_class, StuffContent):- msg = f"Concept class '{self.structure_class_name}' is not a subclass of StuffContent"- raise PipelexUnexpectedError(msg)- return search_for_nested_image_fields(content_class=structure_class)-def render_concept_representation(self,*,+ structure_class: type[StuffContent],output_format: ConceptRepresentationFormat,is_multiple: bool = False,class_name_overrides: dict[str, str] | None = None,@@ -193,6 +161,9 @@ class Concept(ConceptAbstract):"""Render a representation for this concept.Args:+ structure_class: This concept's already-resolved structure class. Passed in rather than+ looked up: turning `structure_class_name` into a type is a registry read, and the+ caller's provider is the only thing that knows *which* registry to read.output_format: The format to generate (JSON, PYTHON, or SCHEMA)is_multiple: If True, wrap content in a list/array schemaclass_name_overrides: Optional runtime-class-name -> rendered-name mapping applied to@@ -206,11 +177,11 @@ class Concept(ConceptAbstract):"""match output_format:case ConceptRepresentationFormat.SCHEMA:- return self._render_schema_representation(is_multiple=is_multiple)+ return self._render_schema_representation(structure_class=structure_class, is_multiple=is_multiple)case ConceptRepresentationFormat.JSON | ConceptRepresentationFormat.PYTHON:generator = ConceptRepresentationGenerator(output_format, class_name_overrides=class_name_overrides)# For inputs, we only want required fields (not optional ones)- result = generator.generate_representation(self.concept_ref, structure_class=self.get_structure_class(), include_optional=False)+ result = generator.generate_representation(self.concept_ref, structure_class=structure_class, include_optional=False)# If multiple and JSON format, wrap content in a list# For Python format, the caller handles wrapping since content is a string@@ -219,17 +190,17 @@ class Concept(ConceptAbstract):return result, generator.imports_needed- def _render_schema_representation(self, *, is_multiple: bool = False) -> tuple[dict[str, Any], set[str]]:+ def _render_schema_representation(self, *, structure_class: type[StuffContent], is_multiple: bool = False) -> tuple[dict[str, Any], set[str]]:"""Render JSON Schema for this concept.Args:+ structure_class: This concept's already-resolved structure class.is_multiple: If True, wrap the schema in an array typeReturns:Tuple of (representation dict with JSON Schema content, empty set)The dict has "concept" and "content" keys where content is the JSON Schema."""- structure_class = self.get_structure_class()json_schema = structure_class.model_json_schema()if is_multiple:diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.pyindex c2f6994d9..9b25fd096 100644--- a/pipelex/core/concepts/concept_factory.py+++ b/pipelex/core/concepts/concept_factory.py@@ -3,6 +3,7 @@ from typing import NamedTuple, castfrom pydantic import BaseModel+from pipelex import logfrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.exceptions import (@@ -17,10 +18,27 @@ from pipelex.core.concepts.structure_generation.generator import StructureGenerafrom pipelex.core.concepts.validation import validate_concept_ref_or_codefrom pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.qualified_ref import QualifiedRef+from pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.system.registries.class_registry_access import get_class_registry+def _is_valid_structure_class(*, structure_class_name: str) -> bool:+ """Whether a class name is already registered as a usable `StuffContent` subclass.++ Materialization-time only, which is why it lives here rather than on `Concept`: the factory is+ deciding whether to *reuse* an existing class or generate one, and that question is about the+ registry the generated classes land in — not about a concept, which at this point does not exist+ yet. A name registered as something other than a `StuffContent` subclass is a near-miss worth a+ warning, since the author almost certainly meant it to be one.+ """+ if get_class_registry().has_subclass(name=structure_class_name, base_class=StuffContent):+ return True+ if get_class_registry().has_class(name=structure_class_name):+ log.warning(f"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent")+ return False++class StructureNameAndRefine(NamedTuple):structure_class_name: strrefine_string: str | None@@ -302,7 +320,7 @@ class ConceptFactory:if not isinstance(structure_class_name, str):msg = f"Expected structure to be a string, got {type(structure_class_name)}"raise ConceptFactoryError(msg)- if not Concept.is_valid_structure_class(structure_class_name=structure_class_name):+ if not _is_valid_structure_class(structure_class_name=structure_class_name):msg = (f"Structure class '{structure_class_name}' set for concept '{concept_code}' in domain '{domain_code}' ""is not a registered subclass of StuffContent, or was not found in the library."@@ -368,9 +386,9 @@ class ConceptFactory:# Check if a valid structure class already exists — first by bare concept_code# (for pre-existing Python classes registered under their own name), then by# qualified name (for previously generated dynamic classes)- if Concept.is_valid_structure_class(structure_class_name=concept_code):+ if _is_valid_structure_class(structure_class_name=concept_code):return StructureNameAndRefine(structure_class_name=concept_code, refine_string=None)- if Concept.is_valid_structure_class(structure_class_name=qualified_class_name):+ if _is_valid_structure_class(structure_class_name=qualified_class_name):return StructureNameAndRefine(structure_class_name=qualified_class_name, refine_string=None)# Because native concepts have structure class names diffrent than other (with "Content")diff --git a/pipelex/core/concepts/concept_provider_abstract.py b/pipelex/core/concepts/concept_provider_abstract.pyindex 64dc5eaf3..798f5f0a7 100644--- a/pipelex/core/concepts/concept_provider_abstract.py+++ b/pipelex/core/concepts/concept_provider_abstract.py@@ -15,6 +15,7 @@ from abc import ABC, abstractmethodfrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.stuffs.stuff_content import StuffContentclass ConceptProviderAbstract(ABC):@@ -35,3 +36,14 @@ class ConceptProviderAbstract(ABC):@abstractmethoddef is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:"""Whether `tested_concept` satisfies `wanted_concept` (refinement only when `strict`)."""++ @abstractmethod+ def get_structure_class(self, *, concept: Concept) -> type[StuffContent]:+ """Resolve a concept's declared `structure_class_name` into the class itself.++ A `Concept` carries the class *name* as a plain protocol string; turning that name into a+ type is a lookup against whichever class registry the provider is backed by, which is+ precisely the knowledge a wire model must not hold. Raises+ `ConceptStructureClassNotFoundError` when the name resolves to nothing, or to something that+ is not a `StuffContent` subclass.+ """diff --git a/pipelex/core/concepts/exceptions.py b/pipelex/core/concepts/exceptions.pyindex f51108378..626d124bc 100644--- a/pipelex/core/concepts/exceptions.py+++ b/pipelex/core/concepts/exceptions.py@@ -9,6 +9,15 @@ class ConceptValueError(ValueError):pass+class ConceptStructureClassNotFoundError(ConceptValueError):+ """A concept's declared `structure_class_name` does not resolve to a usable `StuffContent` class.++ Raised instead of answering a question the library cannot actually answer — "are these two+ compatible?", "what is this concept's class?". A `ConceptValueError` subclass so the guards that+ already convert that error at their own boundary keep working unchanged.+ """++class ConceptFactoryError(PipelexError):passdiff --git a/pipelex/core/concepts/native/concept_native.py b/pipelex/core/concepts/native/concept_native.pyindex 2d0967e12..a60d8637b 100644--- a/pipelex/core/concepts/native/concept_native.py+++ b/pipelex/core/concepts/native/concept_native.py@@ -171,6 +171,41 @@ class NativeConceptCode(StrEnum):):return False+ @classmethod+ def is_structureless_concept(cls, concept_code: str) -> bool:+ """Whether a native code deliberately declares no structure class.++ `Anything` is the untyped vehicle: `structure_class` is `None` for it, so the+ `AnythingContent` name that `structure_class_name` derives mechanically has no class behind+ it and never will. Callers that resolve a structure class must not ask for this one's — its+ absence is a property of the concept, not a missing registration.+ """+ try:+ enum_value = NativeConceptCode(concept_code)+ except ValueError:+ return False++ match enum_value:+ case NativeConceptCode.ANYTHING:+ return True+ case (+ NativeConceptCode.DYNAMIC+ | NativeConceptCode.TEXT+ | NativeConceptCode.IMAGE+ | NativeConceptCode.DOCUMENT+ | NativeConceptCode.HTML+ | NativeConceptCode.TEXT_AND_IMAGES+ | NativeConceptCode.NUMBER+ | NativeConceptCode.YES_NO+ | NativeConceptCode.DATE+ | NativeConceptCode.TIME+ | NativeConceptCode.PAGE+ | NativeConceptCode.JSON+ | NativeConceptCode.SEARCH_RESULT+ | NativeConceptCode.COMPOSITE+ ):+ return False+@classmethoddef is_dynamic_concept(cls, concept_code: str) -> bool:try:diff --git a/pipelex/core/memory/input_shaper.py b/pipelex/core/memory/input_shaper.pyindex e3305fe37..1fa39dd08 100644--- a/pipelex/core/memory/input_shaper.py+++ b/pipelex/core/memory/input_shaper.py@@ -27,7 +27,6 @@ from pipelex.base_exceptions import PipelexUnexpectedErrorfrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstractfrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat-from pipelex.core.concepts.exceptions import ConceptValueErrorfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.exceptions import (ExplicitConceptIncompatibleError,@@ -176,7 +175,7 @@ class InputShaper:raise NullInputError.make(variable_name=variable_name,declared_concept_ref=declared_concept.concept_ref,- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)# (D5) Bare value: dispatch on the declared concept's nature.@@ -238,14 +237,9 @@ class InputShaper:# A user (non-native) concept whose structure is StructuredContent dispatches its dict# top-down. Everything else — the out-of-matrix natives (Html/JSON/Page/TextAndImages/- # SearchResult/Composite/Anything) and any concept whose class is unregistered — falls back- # to bottom-up building.+ # SearchResult/Composite/Anything) — falls back to bottom-up building.if not Concept.is_native_concept(concept=concept):- try:- structure_class = concept.get_structure_class()- except ConceptValueError:- return InputKind.DYNAMIC- if issubclass(structure_class, StructuredContent):+ if issubclass(concept_provider.get_structure_class(concept=concept), StructuredContent):return InputKind.STRUCTUREDreturn InputKind.DYNAMIC@@ -281,7 +275,9 @@ class InputShaper:# string or the exact {"url": <tabular path>} wrapper — read row-wise into the declared# concept, tried BEFORE element-wise shaping so the bare string is not misread as one item.if is_list and input_kind.is_structured:- csv_list_content = cls._try_shape_csv(value, stuff_spec=stuff_spec, variable_name=variable_name, inputs_base_dir=inputs_base_dir)+ csv_list_content = cls._try_shape_csv(+ value, concept_provider=concept_provider, stuff_spec=stuff_spec, variable_name=variable_name, inputs_base_dir=inputs_base_dir+ )if csv_list_content is not None:if fixed_count is not None and len(csv_list_content.items) != fixed_count:raise MultiplicityCountMismatchError.make(@@ -289,7 +285,7 @@ class InputShaper:declared_concept_ref=stuff_spec.concept.concept_ref,expected_count=fixed_count,provided_count=len(csv_list_content.items),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)return csv_list_content@@ -311,7 +307,7 @@ class InputShaper:variable_name=variable_name,declared_concept_ref=stuff_spec.concept.concept_ref,provided_description=cls._describe_value(value),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)return cls._build_item_content(value,@@ -328,6 +324,7 @@ class InputShaper:cls,value: Any,*,+ concept_provider: ConceptProviderAbstract,stuff_spec: StuffSpec,variable_name: str,inputs_base_dir: Path | None,@@ -352,7 +349,7 @@ class InputShaper:else:return Noneurl = cls._resolve_local_path(url, inputs_base_dir=inputs_base_dir)- return StuffFactory.try_make_csv_list_content(stuff_spec.concept, content={"url": url}, name=variable_name)+ return StuffFactory.try_make_csv_list_content(stuff_spec.concept, concept_provider=concept_provider, content={"url": url}, name=variable_name)@classmethoddef _resolve_local_path(cls, url: str, *, inputs_base_dir: Path | None) -> str:@@ -386,7 +383,7 @@ class InputShaper:declared_concept_ref=stuff_spec.concept.concept_ref,expected_count=fixed_count,provided_count=len(item_values),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)items = [cls._build_item_content(@@ -433,41 +430,61 @@ class InputShaper:variable_name=variable_name,declared_concept_ref=concept.concept_ref,provided_concept_ref=built.concept.concept_ref,- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)return built.contentmatch input_kind:case InputKind.TEXT:if not isinstance(value, str):- raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a string (text)", value=value)- return cls._make_content(concept, value={"text": value}, stuff_spec=stuff_spec, variable_name=variable_name)+ raise cls._wrong_kind(+ concept_provider=concept_provider,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ expected_kind="a string (text)",+ value=value,+ )+ return cls._make_content(+ concept, concept_provider=concept_provider, value={"text": value}, stuff_spec=stuff_spec, variable_name=variable_name+ )case InputKind.NUMBER:# bool is a subclass of int — exclude it explicitly so a boolean never becomes a number.if isinstance(value, bool) or not isinstance(value, (int, float)):- raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a number", value=value)- return cls._make_content(concept, value={"number": value}, stuff_spec=stuff_spec, variable_name=variable_name)+ raise cls._wrong_kind(+ concept_provider=concept_provider, stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a number", value=value+ )+ return cls._make_content(+ concept, concept_provider=concept_provider, value={"number": value}, stuff_spec=stuff_spec, variable_name=variable_name+ )case InputKind.YES_NO:if not isinstance(value, bool):- raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a boolean (true/false)", value=value)- return cls._make_content(concept, value=value, stuff_spec=stuff_spec, variable_name=variable_name)+ raise cls._wrong_kind(+ concept_provider=concept_provider,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ expected_kind="a boolean (true/false)",+ value=value,+ )+ return cls._make_content(concept, concept_provider=concept_provider, value=value, stuff_spec=stuff_spec, variable_name=variable_name)case InputKind.DATE:if not isinstance(value, (datetime.date, str)):raise cls._wrong_kind(+ concept_provider=concept_provider,stuff_spec=stuff_spec,variable_name=variable_name,expected_kind="an ISO date/datetime string or a date object",value=value,)- return cls._make_content(concept, value=value, stuff_spec=stuff_spec, variable_name=variable_name)+ return cls._make_content(concept, concept_provider=concept_provider, value=value, stuff_spec=stuff_spec, variable_name=variable_name)case InputKind.TIME:if not isinstance(value, (datetime.time, str)):raise cls._wrong_kind(+ concept_provider=concept_provider,stuff_spec=stuff_spec,variable_name=variable_name,expected_kind="an ISO time-of-day string or a time object",value=value,)- return cls._make_content(concept, value=value, stuff_spec=stuff_spec, variable_name=variable_name)+ return cls._make_content(concept, concept_provider=concept_provider, value=value, stuff_spec=stuff_spec, variable_name=variable_name)case InputKind.IMAGE | InputKind.DOCUMENT:canonical: dict[str, Any]if isinstance(value, str):@@ -478,18 +495,31 @@ class InputShaper:canonical = cast("dict[str, Any]", value)else:raise cls._wrong_kind(+ concept_provider=concept_provider,stuff_spec=stuff_spec,variable_name=variable_name,expected_kind='a URL/path string or a {"url": ...} object',value=value,)- return cls._make_content(concept, value=canonical, stuff_spec=stuff_spec, variable_name=variable_name)+ return cls._make_content(+ concept, concept_provider=concept_provider, value=canonical, stuff_spec=stuff_spec, variable_name=variable_name+ )case InputKind.STRUCTURED:if not isinstance(value, dict):raise cls._wrong_kind(- stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="an object (structured value)", value=value+ concept_provider=concept_provider,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ expected_kind="an object (structured value)",+ value=value,)- return cls._make_content(concept, value=cast("dict[str, Any]", value), stuff_spec=stuff_spec, variable_name=variable_name)+ return cls._make_content(+ concept,+ concept_provider=concept_provider,+ value=cast("dict[str, Any]", value),+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ )case InputKind.DYNAMIC:# Unreachable: DYNAMIC short-circuits in `_shape_one` before multiplicity peeling.# Kept so the match over InputKind stays exhaustive.@@ -501,6 +531,7 @@ class InputShaper:cls,concept: Concept,*,+ concept_provider: ConceptProviderAbstract,value: dict[str, Any] | str | bool | datetime.date | datetime.time,stuff_spec: StuffSpec,variable_name: str,@@ -513,7 +544,7 @@ class InputShaper:variable_name=variable_name,declared_concept_ref=concept.concept_ref,reason=str(exc),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),) from exc@classmethod@@ -545,16 +576,18 @@ class InputShaper:variable_name=variable_name,declared_concept_ref=declared_concept.concept_ref,provided_concept_ref=stuff.concept.concept_ref,- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)if NativeConceptCode.is_dynamic_concept(concept_code=declared_concept.code):# Match the bare-value Dynamic path: the signature cannot guide list-vs-single shape here.return stuff- cls._reconcile_explicit_multiplicity(stuff, stuff_spec=stuff_spec, variable_name=variable_name)+ cls._reconcile_explicit_multiplicity(stuff, concept_provider=concept_provider, stuff_spec=stuff_spec, variable_name=variable_name)return stuff@classmethod- def _reconcile_explicit_multiplicity(cls, stuff: Stuff, *, stuff_spec: StuffSpec, variable_name: str) -> None:+ def _reconcile_explicit_multiplicity(+ cls, stuff: Stuff, *, concept_provider: ConceptProviderAbstract, stuff_spec: StuffSpec, variable_name: str+ ) -> None:"""Enforce the unambiguous D2 shape rules on an explicit form (D6 governs only its concept).An explicit form whose built content is a ``ListContent`` must not fill a singular slot, and must@@ -575,7 +608,7 @@ class InputShaper:variable_name=variable_name,declared_concept_ref=stuff_spec.concept.concept_ref,provided_description=f"a list of {len(list_content.items)} item(s)",- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)if fixed_count is not None and len(list_content.items) != fixed_count:raise MultiplicityCountMismatchError.make(@@ -583,7 +616,7 @@ class InputShaper:declared_concept_ref=stuff_spec.concept.concept_ref,expected_count=fixed_count,provided_count=len(list_content.items),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)@classmethod@@ -600,19 +633,22 @@ class InputShaper:return isinstance(value, dict) and set(cast("dict[Any, Any]", value).keys()) == {"concept", "content"}@classmethod- def _wrong_kind(cls, *, stuff_spec: StuffSpec, variable_name: str, expected_kind: str, value: Any) -> WrongScalarKindError:+ def _wrong_kind(+ cls, *, concept_provider: ConceptProviderAbstract, stuff_spec: StuffSpec, variable_name: str, expected_kind: str, value: Any+ ) -> WrongScalarKindError:return WrongScalarKindError.make(variable_name=variable_name,declared_concept_ref=stuff_spec.concept.concept_ref,expected_kind=expected_kind,provided_description=cls._describe_value(value),- expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),)@classmethod- def _render_expected_shape(cls, *, stuff_spec: StuffSpec) -> str:+ def _render_expected_shape(cls, *, concept_provider: ConceptProviderAbstract, stuff_spec: StuffSpec) -> str:"""Render the expected input shape from the signature, reused verbatim in D4 error hints."""- return json.dumps(stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON), ensure_ascii=False)+ rendered = stuff_spec.render_stuff_spec(concept_provider=concept_provider, output_format=ConceptRepresentationFormat.JSON)+ return json.dumps(rendered, ensure_ascii=False)@classmethoddef _describe_value(cls, value: Any) -> str:diff --git a/pipelex/core/pipes/inputs/input_stuff_specs.py b/pipelex/core/pipes/inputs/input_stuff_specs.pyindex a155c85b7..c68e10075 100644--- a/pipelex/core/pipes/inputs/input_stuff_specs.py+++ b/pipelex/core/pipes/inputs/input_stuff_specs.py@@ -6,6 +6,7 @@ from pydantic import Field, RootModel, field_validatorfrom pipelex import logfrom pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstractfrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundErrorfrom pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec@@ -176,24 +177,28 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):lines = [f"{prefix}- {var_name}: {stuff_spec.to_bundle_representation()}" for var_name, stuff_spec in self.root.items()]return "\n" + "\n".join(lines)- def build_inputs_template(self) -> dict[str, Any]:+ def build_inputs_template(self, *, concept_provider: ConceptProviderAbstract) -> dict[str, Any]:"""Build the inputs template dict: variable name -> example stuff representation.+ Args:+ concept_provider: Resolves each declared concept's structure class.+Returns:Dictionary mapping each input variable to its generated example value"""template: dict[str, Any] = {}for var_name, stuff_spec in self.root.items():- template[var_name] = stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON)+ template[var_name] = stuff_spec.render_stuff_spec(concept_provider=concept_provider, output_format=ConceptRepresentationFormat.JSON)return template- def render_inputs(self, *, indent: int = 2) -> str:+ def render_inputs(self, *, concept_provider: ConceptProviderAbstract, indent: int = 2) -> str:"""Render a JSON representation for all stuff specs as a formatted string.Args:+ concept_provider: Resolves each declared concept's structure class.indent: Number of spaces for indentation (default: 2)Returns:Formatted JSON string with all inputs"""- return json.dumps(self.build_inputs_template(), indent=indent, ensure_ascii=False)+ return json.dumps(self.build_inputs_template(concept_provider=concept_provider), indent=indent, ensure_ascii=False)diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec.py b/pipelex/core/pipes/stuff_spec/stuff_spec.pyindex 5de710254..efd361116 100644--- a/pipelex/core/pipes/stuff_spec/stuff_spec.py+++ b/pipelex/core/pipes/stuff_spec/stuff_spec.py@@ -3,6 +3,7 @@ from typing import Anyfrom pydantic import BaseModelfrom pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstractfrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.pipes.variable_multiplicity import PresenceMarker, VariableMultiplicity, format_concept_with_multiplicity@@ -38,10 +39,13 @@ class StuffSpec(BaseModel):presence=self.presence,)- def render_stuff_spec(self, *, output_format: ConceptRepresentationFormat) -> dict[str, Any]:+ def render_stuff_spec(self, *, concept_provider: ConceptProviderAbstract, output_format: ConceptRepresentationFormat) -> dict[str, Any]:"""Render a representation of this stuff spec.Args:+ concept_provider: Resolves this spec's concept into its structure class. This is the one+ place in the whole render chain that resolves a class, so a caller states which+ library it means instead of every renderer reaching for one.output_format: The format to generate (JSON or PYTHON)Returns:@@ -49,6 +53,7 @@ class StuffSpec(BaseModel):wrapped in a list if multiplicity indicates multiple items."""json_value, _ = self.concept.render_concept_representation(+ structure_class=concept_provider.get_structure_class(concept=self.concept),output_format=output_format,is_multiple=self.is_multiple(),)diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.pyindex faca2848d..d3ced1755 100644--- a/pipelex/core/stuffs/stuff_factory.py+++ b/pipelex/core/stuffs/stuff_factory.py@@ -139,12 +139,13 @@ class StuffFactory:cls,concept: Concept,*,+ concept_provider: ConceptProviderAbstract,content: dict[str, Any],name: str | None,code: str | None,) -> Stuff | None:"""Wrap :meth:`try_make_csv_list_content` into a ``Stuff`` (Case 2.5 envelope path)."""- list_content = cls.try_make_csv_list_content(concept, content=content, name=name)+ list_content = cls.try_make_csv_list_content(concept, concept_provider=concept_provider, content=content, name=name)if list_content is None:return Nonereturn cls.make_stuff(concept=concept, content=list_content, name=name, code=code)@@ -154,6 +155,7 @@ class StuffFactory:cls,concept: Concept,*,+ concept_provider: ConceptProviderAbstract,content: dict[str, Any],name: str | None,) -> ListContent[StuffContent] | None:@@ -234,7 +236,7 @@ class StuffFactory:raise CsvError(msg)try:- row_model = concept.get_structure_class()+ row_model = concept_provider.get_structure_class(concept=concept)except ConceptValueError as exc:# Keep the codec's typed-error boundary intact: an unregistered structure class is a# caller-fixable input problem, not a raw ValueError that escapes into core/runner.@@ -592,7 +594,7 @@ class StuffFactory:if isinstance(content, dict):content_dict = cast("dict[str, Any]", content)# CSV input: a {"url": "...csv"} under a structured row concept loads as ListContent[row-concept].- csv_stuff = cls._try_make_csv_list_stuff(concept=concept, content=content_dict, name=name, code=code)+ csv_stuff = cls._try_make_csv_list_stuff(concept=concept, concept_provider=concept_provider, content=content_dict, name=name, code=code)if csv_stuff is not None:return csv_stuffdiff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.pyindex fad45a0d4..ea78c49df 100644--- a/pipelex/libraries/concept/concept_library.py+++ b/pipelex/libraries/concept/concept_library.py@@ -1,17 +1,21 @@-from typing import Any, Callable, Self+from typing import Any, Callable, Self, cast+from kajson.exceptions import ClassRegistryInheritanceError, ClassRegistryNotFoundErrorfrom pydantic import Field, RootModel, model_validatorfrom typing_extensions import overridefrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_factory import ConceptFactory-from pipelex.core.concepts.exceptions import ConceptLibraryConceptNotFoundError, ConceptStringError+from pipelex.core.concepts.exceptions import ConceptLibraryConceptNotFoundError, ConceptStringError, ConceptStructureClassNotFoundErrorfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.concepts.validation import is_concept_ref_valid, validate_concept_ref_or_codefrom pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.qualified_ref import QualifiedRef+from pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.libraries.concept.concept_library_abstract import ConceptLibraryAbstractfrom pipelex.libraries.concept.exceptions import ConceptLibraryError+from pipelex.runtime_hub import get_class_registry+from pipelex.tools.typing.class_utils import are_structure_classes_compatibleConceptLibraryRoot = dict[str, Concept]@@ -96,13 +100,44 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):@overridedef is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:- return Concept.are_concept_compatible(+ """Compose the two compatibility tiers, in the one place that owns resolution.++ The declaration tier decides on its own whenever it can — and when it does, no class is ever+ looked up, so concepts whose structure classes were never materialized still get an answer.+ Only when the declarations are inconclusive does the class tier run, and that needs both+ classes: a name that does not resolve makes the question unanswerable, so it raises rather+ than returning the `False` that would read as "incompatible".+ """+ if Concept.are_compatible_by_declaration(concept_1=tested_concept,concept_2=wanted_concept,- strict=strict,concept_resolver=self._concept_resolver,+ ):+ return True++ if not (tested_concept.declares_a_structure_class and wanted_concept.declares_a_structure_class):+ # `native.Anything` has no structure class, so there is no structural comparison left to+ # make: the declaration tier's silence is the whole answer.+ return False++ return are_structure_classes_compatible(+ class_1=self.get_structure_class(concept=tested_concept),+ class_2=self.get_structure_class(concept=wanted_concept),+ strict=strict,)+ @override+ def get_structure_class(self, *, concept: Concept) -> type[StuffContent]:+ try:+ structure_class = get_class_registry().get_required_subclass(name=concept.structure_class_name, base_class=StuffContent)+ except (ClassRegistryNotFoundError, ClassRegistryInheritanceError) as exc:+ msg = (+ f"Concept '{concept.concept_ref}' declares structure class '{concept.structure_class_name}', "+ f"which is not a registered subclass of StuffContent: {exc}"+ )+ raise ConceptStructureClassNotFoundError(msg) from exc+ return cast("type[StuffContent]", structure_class)+def get_optional_concept(self, concept_ref: str) -> Concept | None:return self.root.get(concept_ref)diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.pyindex 96e91db3d..cfb9274ba 100644--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py@@ -21,7 +21,7 @@ from pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.graph.graph_tracer_manager import GraphTracerManagerfrom pipelex.graph.graphspec import IOSpec-from pipelex.interpreter_hub import get_optional_pipe, get_required_pipe+from pipelex.interpreter_hub import get_concept_library, get_optional_pipe, get_required_pipefrom pipelex.libraries.pipe.exceptions import PipeNotFoundErrorfrom pipelex.pipe_controllers.absence_taint import (ForceConsumptionInfo,@@ -165,7 +165,7 @@ class PipeParallel(PipeController):runtime combine failure into an author-time error surfaced by `/validate`."""try:- structure_class = self.output.concept.get_structure_class()+ structure_class = get_concept_library().get_structure_class(concept=self.output.concept)except ConceptValueError as exc:# A plain ValueError would escape the /validate sweep and abort the whole bundle;# convert it so this pipe alone is reported as failed.@@ -383,7 +383,7 @@ class PipeParallel(PipeController):# A list-producing branch combines as a ListContent, not as the item class.continuetry:- branch_structure_class = branch_pipe.output.concept.get_structure_class()+ branch_structure_class = get_concept_library().get_structure_class(concept=branch_pipe.output.concept)except ConceptValueError as exc:# Same conversion as the output lookup above: keep the failure per-pipe.msg = (@@ -456,7 +456,7 @@ class PipeParallel(PipeController):pipe_outputs = await asyncio.gather(*tasks)- structure_class = self.output.concept.get_structure_class()+ structure_class = get_concept_library().get_structure_class(concept=self.output.concept)seen_output_names: set[str] = set()output_stuffs: dict[str, Stuff] = {}output_stuff_contents: dict[str, StuffContent] = {}diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.pyindex e12949d60..f63ade5b1 100644--- a/pipelex/pipe_machinery/pipe_abstract.py+++ b/pipelex/pipe_machinery/pipe_abstract.py@@ -31,6 +31,7 @@ from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableErrorfrom pipelex.pipeline.pipeline_factory import PipelineFactoryfrom pipelex.system.job_metadata import JobMetadata, OtelContextfrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.system.registries.class_registry_access import get_class_registryfrom pipelex.system.telemetry.otel_constants import (LangfuseSpanAttr,OTelConstants,@@ -174,8 +175,17 @@ class PipeAbstract(ABC, BaseModel):source = library_crate.source_map.get(concept.concept_ref)if source:concept_dict["source"] = source+ # Reads the active class registry directly rather than asking a concept provider. Importing+ # either hub here is a pyright `reportImportCycles` failure via runtime_hub ->+ # orchestrator_registry -> pipe_job -> here; those edges are TYPE_CHECKING-only, so there is no+ # runtime cycle, but pyright counts them and reports at `interpreter_hub.py`, out of reach of a+ # line-level ignore. Deferring the import does not help either. `class_registry_access` sits+ # below both hubs for exactly this. The lenient `get_class` (no StuffContent bound) is+ # deliberate: the schema is optional decoration on a graph-registry entry, so an unresolvable+ # class yields `None` rather than failing the run.+ structure_class = get_class_registry().get_class(name=concept.structure_class_name)try:- concept_dict["json_schema"] = concept.get_structure_class().model_json_schema()+ concept_dict["json_schema"] = structure_class.model_json_schema() if structure_class is not None else Noneexcept (TypeError, ValueError):concept_dict["json_schema"] = Nonereturn concept_dictdiff --git a/pipelex/pipe_machinery/rendering/input_renderer.py b/pipelex/pipe_machinery/rendering/input_renderer.pyindex 0c13f1edb..74eec9f12 100644--- a/pipelex/pipe_machinery/rendering/input_renderer.py+++ b/pipelex/pipe_machinery/rendering/input_renderer.py@@ -41,7 +41,7 @@ def build_inputs_template(the_pipe: PipeAbstract, *, explicit: bool = False) ->msg = f"No inputs required for pipe '{the_pipe.code}'."raise NoInputsRequiredError(msg)- envelope_template = the_pipe.inputs.build_inputs_template()+ envelope_template = the_pipe.inputs.build_inputs_template(concept_provider=get_concept_library())if explicit:return envelope_templatereturn _delighten_template(envelope_template, input_specs=the_pipe.inputs)diff --git a/pipelex/pipe_machinery/rendering/output_renderer.py b/pipelex/pipe_machinery/rendering/output_renderer.pyindex 02429eea6..f8a5dcea4 100644--- a/pipelex/pipe_machinery/rendering/output_renderer.py+++ b/pipelex/pipe_machinery/rendering/output_renderer.py@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING, Any, castfrom pipelex.base_exceptions import PipelexErrorfrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.concepts.native.concept_native import NativeConceptCode-from pipelex.interpreter_hub import get_required_pipe+from pipelex.interpreter_hub import get_concept_library, get_required_pipefrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipe_machinery.pipe_blueprint import PipeType@@ -46,11 +46,15 @@ def _collect_possible_outputs(return []possible_outputs: list[dict[str, Any]] = []+ # Resolved once, and OUTSIDE the try below: a failure to reach the loaded method's library+ # is a lifecycle fault, not "this concept's structure cannot be rendered", and the except+ # there would quietly turn it into the placeholder.+ concept_provider = get_concept_library()# pipe_dependencies() is a set — sort so the user-facing output_option_N numbering is deterministicfor mapped_pipe_code in sorted(mapped_pipe_codes):mapped_pipe = get_required_pipe(pipe_code=mapped_pipe_code)try:- output_dict = mapped_pipe.output.render_stuff_spec(output_format=output_format)+ output_dict = mapped_pipe.output.render_stuff_spec(concept_provider=concept_provider, output_format=output_format)content = output_dict.get("content", output_dict)possible_outputs.append({@@ -87,9 +91,11 @@ def _collect_possible_outputs(if last_pipe.output.concept.code == NativeConceptCode.ANYTHING:return _collect_possible_outputs(last_pipe, output_format=output_format)- # Otherwise render the last pipe's output+ # Otherwise render the last pipe's output. The library lookup sits outside the try for+ # the same reason as the condition branch above.+ concept_provider = get_concept_library()try:- output_dict = last_pipe.output.render_stuff_spec(output_format=output_format)+ output_dict = last_pipe.output.render_stuff_spec(concept_provider=concept_provider, output_format=output_format)content = output_dict.get("content", output_dict)return [{@@ -184,7 +190,7 @@ def _render_json_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:return json.dumps(result, indent=indent, ensure_ascii=False)# Normal output rendering - returns dict with "concept" and "content"- output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.JSON)+ output_dict = the_pipe.output.render_stuff_spec(concept_provider=get_concept_library(), output_format=ConceptRepresentationFormat.JSON)return json.dumps(output_dict, indent=indent, ensure_ascii=False)@@ -225,7 +231,7 @@ def _render_python_output(the_pipe: PipeAbstract) -> str:return "\n".join(lines)# Normal output rendering- output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.PYTHON)+ output_dict = the_pipe.output.render_stuff_spec(concept_provider=get_concept_library(), output_format=ConceptRepresentationFormat.PYTHON)concept_ref = output_dict.get("concept", "")content = output_dict.get("content", "")@@ -269,5 +275,5 @@ def _render_schema_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:return json.dumps(result, indent=indent, ensure_ascii=False)# Normal output rendering - get JSON Schema directly- output_dict = the_pipe.output.render_stuff_spec(output_format=ConceptRepresentationFormat.SCHEMA)+ output_dict = the_pipe.output.render_stuff_spec(concept_provider=get_concept_library(), output_format=ConceptRepresentationFormat.SCHEMA)return json.dumps(output_dict, indent=indent, ensure_ascii=False)diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.pyindex 9836c7c05..a4a4f990e 100644--- a/pipelex/pipe_operators/llm/pipe_llm.py+++ b/pipelex/pipe_operators/llm/pipe_llm.py@@ -12,7 +12,6 @@ from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting, LLMSettingCfrom pipelex.cogt.model_backends.model_type import ModelTypefrom pipelex.cogt.models.model_deck_check import check_llm_choice_with_deckfrom pipelex.config import get_config-from pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.domains.domain import SpecialDomain@@ -243,7 +242,11 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):rendered_llm_prompt: LLMPrompt | None = Noneif (- Concept.are_concept_compatible(concept_1=output_stuff_spec.concept, concept_2=get_native_concept(NativeConceptCode.TEXT), strict=True)+ get_concept_library().is_compatible(+ tested_concept=output_stuff_spec.concept,+ wanted_concept=get_native_concept(NativeConceptCode.TEXT),+ strict=True,+ )and not is_multiple_output):llm_prompt_1_for_text = await self.llm_prompt_spec.make_llm_prompt(@@ -331,8 +334,10 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):if is_multiple_output:execution_data_dict["structuring_path"] = "object_list"else:- output_is_text = Concept.are_concept_compatible(- concept_1=output_stuff_spec.concept, concept_2=get_native_concept(NativeConceptCode.TEXT), strict=True+ output_is_text = get_concept_library().is_compatible(+ tested_concept=output_stuff_spec.concept,+ wanted_concept=get_native_concept(NativeConceptCode.TEXT),+ strict=True,)execution_data_dict["structuring_path"] = "text" if output_is_text else "object_direct"diff --git a/pipelex/pipe_operators/llm/template_document_analyzer.py b/pipelex/pipe_operators/llm/template_document_analyzer.pyindex bb0ae74d2..50ad8d4b1 100644--- a/pipelex/pipe_operators/llm/template_document_analyzer.py+++ b/pipelex/pipe_operators/llm/template_document_analyzer.py@@ -10,7 +10,7 @@ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity-from pipelex.interpreter_hub import get_native_concept, get_required_concept+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_conceptfrom pipelex.pipe_operators.llm.document_reference import DocumentReference, DocumentReferenceKindfrom pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_variable_referencesfrom pipelex.tools.jinja2.template_category import TemplateCategory@@ -148,9 +148,9 @@ class TemplateDocumentAnalyzer:# For simple variable references (no dots after root)if var_path == root_var:# Check if it's directly a DocumentContent- is_document = Concept.are_concept_compatible(- concept_1=root_concept,- concept_2=native_document_concept,+ is_document = get_concept_library().is_compatible(+ tested_concept=root_concept,+ wanted_concept=native_document_concept,strict=True,)if is_document:diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.pyindex 34cbaf086..43a75cb2c 100644--- a/pipelex/pipe_operators/search/pipe_search.py+++ b/pipelex/pipe_operators/search/pipe_search.py@@ -14,6 +14,7 @@ from pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecsfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.core.stuffs.stuff_factory import StuffFactory+from pipelex.interpreter_hub import get_concept_libraryfrom pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guardsfrom pipelex.pipe_operators.pipe_operator import PipeOperatorfrom pipelex.pipe_run.pipe_run_params import PipeRunParams@@ -140,7 +141,7 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):if not self.is_structured_output:content = await content_generator.make_search_sourced_answer(search_assignment=search_assignment)else:- output_structure_class = self.output.concept.get_structure_class()+ output_structure_class = get_concept_library().get_structure_class(concept=self.output.concept)content = await content_generator.make_search_structured(output_structure_class=output_structure_class,search_assignment=search_assignment,diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.pyindex 6ede53331..b92da98bd 100644--- a/pipelex/pipe_operators/shared/template_image_analyzer.py+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py@@ -10,7 +10,8 @@ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity-from pipelex.interpreter_hub import get_native_concept, get_required_concept+from pipelex.core.stuffs.image_field_search import search_for_nested_image_fields+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_conceptfrom pipelex.pipe_operators.shared.exceptions import UnusedInputError, WithImagesFilterErrorfrom pipelex.pipe_operators.shared.image_reference import ImageReference, ImageReferenceKindfrom pipelex.tools.jinja2.jinja2_models import Jinja2FilterName@@ -215,23 +216,23 @@ class TemplateImageAnalyzer:# For simple variable references (no dots after root)if var_path == root_var:# Check if it's directly an ImageContent- is_image = Concept.are_concept_compatible(- concept_1=root_concept,- concept_2=native_image_concept,+ is_image = get_concept_library().is_compatible(+ tested_concept=root_concept,+ wanted_concept=native_image_concept,strict=True,)if is_image:return (True, False, False, None)# Check if it has nested images (loose compatibility)- has_nested = Concept.are_concept_compatible(- concept_1=root_concept,- concept_2=native_image_concept,+ has_nested = get_concept_library().is_compatible(+ tested_concept=root_concept,+ wanted_concept=native_image_concept,strict=False,)nested_paths: list[str] | None = Noneif has_nested:- nested_paths = root_concept.search_for_nested_image_fields_in_structure_class()+ nested_paths = search_for_nested_image_fields(content_class=get_concept_library().get_structure_class(concept=root_concept))if not nested_paths:has_nested = False@@ -240,7 +241,7 @@ class TemplateImageAnalyzer:# For dotted paths (e.g., "doc.cover"), we need to traverse the structure# This is more complex - for now we'll check if the path ends with an image field# by examining the nested image paths of the root concept- nested_paths = root_concept.search_for_nested_image_fields_in_structure_class()+ nested_paths = search_for_nested_image_fields(content_class=get_concept_library().get_structure_class(concept=root_concept))# Check if the relative path (after root) matches any nested image pathrelative_path = var_path[len(root_var) + 1 :] if var_path.startswith(f"{root_var}.") else Nonediff --git a/pipelex/pipeline/pipe_io_contracts.py b/pipelex/pipeline/pipe_io_contracts.pyindex e860c7f3b..5cceeded0 100644--- a/pipelex/pipeline/pipe_io_contracts.py+++ b/pipelex/pipeline/pipe_io_contracts.py@@ -7,13 +7,16 @@ declared inputs and the concept/multiplicity of its output — keyed by the name`pipe_ref` (`domain.code`), the one identity convention shared by every validate artifact(`validated_pipes`, `pending_signatures`).-The JSON-Schema rendering resolves each concept's structure class through the GLOBAL-class registry. Bundle-defined structure classes are registered there during library-load and are NOT unregistered at teardown (the registry has no unregister mechanism) —-so a call after teardown does not fail loudly: it silently renders against whatever-classes the registry last held, which may be stale or belong to a different bundle.-Callers must therefore invoke the builder against loaded pipes INSIDE the validation-library's window, before teardown. (Registry teardown hygiene is tracked in the+Callers must invoke the builder against loaded pipes INSIDE the validation library's+window, before teardown — the builder now says so itself rather than degrading. It asks+the interpreter hub for the loaded method's concept library up front, so a post-teardown+call raises instead of quietly rendering against whatever the class registry last held.++That silent-stale reading used to be the hazard this note warned about: bundle-defined+structure classes are registered in the process-global registry during library load and+are never unregistered (the registry has no unregister mechanism), so the classes outlive+the library that defined them. They still do — what changed is that this builder no longer+reaches them behind the library's back. (Registry teardown hygiene is tracked in theworkspace-root `wip/library-lifecycle-hygiene.md`.)"""@@ -24,6 +27,7 @@ from pydantic import BaseModel, Field, PydanticUndefinedAnnotation, PydanticUserfrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.concepts.exceptions import ConceptValueError+from pipelex.interpreter_hub import get_concept_libraryfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipeline.exceptions import PipeIOContractError@@ -72,9 +76,9 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCoWorks on any loaded `PipeAbstract` — including `PipeSignature` placeholders, whosedeclared contract is exactly what a top-down build needs to see. Must run while the- validation library is still loaded: bundle-defined structure classes resolve through- the global class registry and a post-teardown call silently uses stale classes- instead of failing (see the module docstring).+ validation library is still loaded: the concept library is resolved from the current+ library up front, so a post-teardown call raises rather than rendering against stale+ classes (see the module docstring).Args:pipes: The loaded pipes to project (typically `ValidateBundleResult.pipes`).@@ -93,6 +97,7 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCo# occurrence. Deliberately NOT a module-level cache — bundle-defined structure classes# vary per loaded library, so a cross-call cache would serve stale schemas.schema_memo: dict[tuple[str, bool], dict[str, Any]] = {}+ concept_provider = get_concept_library()io_contracts: dict[str, PipeIOContract] = {}for pipe in pipes:pipe_inputs: dict[str, PipeInputContract] = {}@@ -104,7 +109,9 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCo# Indexing (not .get with a default) is deliberate: a render-shape drift# must surface as the structured error below, never ship a silently# empty schema on the wire.- json_schema = stuff_spec.render_stuff_spec(output_format=ConceptRepresentationFormat.SCHEMA)["content"]+ json_schema = stuff_spec.render_stuff_spec(concept_provider=concept_provider, output_format=ConceptRepresentationFormat.SCHEMA)[+ "content"+ ]except (ConceptValueError, KeyError, PydanticUserError, PydanticUndefinedAnnotation) as exc:msg = (f"Failed to render the JSON Schema for input '{var_name}' of pipe "diff --git a/pipelex/system/registries/class_registry_access.py b/pipelex/system/registries/class_registry_access.pyindex 652b43e98..55af305bc 100644--- a/pipelex/system/registries/class_registry_access.py+++ b/pipelex/system/registries/class_registry_access.py@@ -1,12 +1,46 @@"""Process-global access to the active class registry, with an optional library-scoping resolver.This module deliberately sits *below* both hubs and imports nothing from ``pipelex``, so any layer-can import it directly. That is not stylistic: ``pipelex.core.concepts.concept`` needs the active-class registry and is itself inside ``runtime_hub``'s import closure-(``runtime_hub`` -> ``cogt.llm.llm_worker_abstract`` -> ``system.telemetry.otel_factory`` ->-``core.pipes.pipe_output`` -> ``core.stuffs.stuff`` -> ``core.concepts.concept``), so it cannot-import ``runtime_hub`` at module level without forming a cycle. Hosting the accessor here is what-lets those modules use a plain top-level import instead of a lazy ``importlib`` shim.+can import it directly. That is not stylistic: a module that needs the active class registry may be+one ``runtime_hub`` cannot be imported *from*, and hosting the accessor here is what lets it use a+plain top-level import instead of a lazy ``importlib`` shim.++Exactly one module needs that today, and the constraint is a **static-analysis** cycle rather than a+runtime one — measure before restating it. ``pipe_machinery.pipe_abstract`` decorates graph-registry+entries with a concept's JSON Schema. It is *not* in ``runtime_hub``'s runtime import closure (a+clean-interpreter probe after ``import pipelex.runtime_hub`` shows it, ``pipe_run.pipe_job`` and+``plugins.orchestrator_registry`` all absent — those edges are ``TYPE_CHECKING``-only). But pyright's+``reportImportCycles`` counts ``TYPE_CHECKING`` edges, so importing **either** hub there is a hard+type-check failure via ``runtime_hub`` -> ``plugins.orchestrator_registry`` -> ``pipe_run.pipe_job``+-> ``pipe_machinery.pipe_abstract``, and a deferred import does not dodge it — the error is reported+at ``interpreter_hub.py``, where no line-level ignore can reach.++``core.concepts.concept_factory`` and ``core.concepts.structure_generation.generator`` — the+**materialization write side**, which generates structure classes and registers them at library-load+time — also import from here, but by convention rather than necessity: both are outside+``runtime_hub``'s closure and pyright accepts the public accessor in either. Historically the binding+case was ``core.concepts.concept`` itself, which *is* in the closure (``runtime_hub`` ->+``cogt.llm.llm_worker_abstract`` -> ``system.telemetry.otel_factory`` -> ``core.pipes.pipe_output``+-> ``core.stuffs.stuff`` -> ``core.concepts.concept``) and no longer reads any registry at all.++The concept **read** side belongs behind the provider seam, not here: resolving a concept's declared+``structure_class_name`` into a class goes through a ``ConceptProviderAbstract`` implementation+(``ConceptLibrary.get_structure_class``), which is the only place that applies the ``StuffContent``+bound and raises ``ConceptStructureClassNotFoundError``. ``pipe_abstract`` above is the one sanctioned+exception, and it deliberately uses the *lenient* ``get_class`` — no bound, ``None`` rather than a+raise — because the schema it produces is optional decoration on a graph-registry entry. ``Concept``+itself reads no registry at all, pinned by+``tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py``.++Note what that seam does **not** yet buy. `ConceptLibrary.get_structure_class` calls+``get_class_registry()``, so the class is resolved against whichever registry the *current async+context* selects, not against one the provider carries — a `ConceptLibrary` holds no registry of its+own (the per-library `ClassRegistry` lives on `Library`). Today the two cannot disagree: the+interpreter hub resolves both the current library and the scoped registry from the same+``_library_id`` ContextVar, and the one place that installs a per-library registry sets it and the+ContextVar on the same library in adjacent statements. Scoping resolution to the provider's own+library is therefore a one-place change if it is ever needed; see+``wip/inputs/provider-scoped-class-resolution.md`` for the trip-wires that would make it needed.``pipelex.runtime_hub.get_class_registry`` is the public accessor and delegates here; prefer iteverywhere except inside this module's own import closure.diff --git a/pipelex/tools/typing/class_utils.py b/pipelex/tools/typing/class_utils.pyindex 136081abc..2b3dc948a 100644--- a/pipelex/tools/typing/class_utils.py+++ b/pipelex/tools/typing/class_utils.py@@ -119,6 +119,33 @@ def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:return True+def are_structure_classes_compatible(*, class_1: type[Any], class_2: type[Any], strict: bool) -> bool:+ """Whether `class_1` can stand in for `class_2`, structurally.++ Structural equivalence always suffices. Beyond that, `strict` decides how much slack is allowed:+ strict mode accepts equivalence only, while loose mode also accepts a subclass relationship+ (a refined concept's generated class inherits from the refined one's) and a class that merely+ *carries* a compatible value in one of its fields — the "nested" case a template needs when it+ pulls an image out of a document.++ Pure over the two classes: it takes resolved types, never names, and reads no registry.+ """+ if are_classes_equivalent(class_1, class_2=class_2):+ return True++ if strict:+ return False++ try:+ if issubclass(class_1, class_2):+ return True+ except TypeError:+ # Not both classes (e.g. a typing construct slipped through) — fall through to field checks.+ pass++ return has_compatible_field(class_1, target_type=class_2)++def has_compatible_field(model_cls: type[Any], *, target_type: type[Any]) -> bool:"""Check if model_cls has a field whose (possibly wrapped) type matches/subclasses target_type or is structurally equivalent."""if not hasattr(model_cls, "model_fields"):diff --git a/subject_grants.toml b/subject_grants.tomlindex ecab41556..993083c9f 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -2372,10 +2372,6 @@ rationale = "Verb-object: compute the cost of one usage record; the single obvioparam = "concept"rationale = "Predicate on the concept; single operand."-["pipelex/core/concepts/concept.py::Concept.is_valid_structure_class"]-param = "structure_class_name"-rationale = "Predicate on the class name; single operand."-["pipelex/core/concepts/concept.py::Concept.sentence_from_concept"]param = "concept"rationale = "Derivation from the concept; single operand."@@ -2508,6 +2504,10 @@ rationale = "Predicate on the ref-or-code; single operand."param = "class_name"rationale = "Predicate on the class name; single operand."+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_structureless_concept"]+param = "concept_code"+rationale = "Predicate on the concept code; single operand — same shape as its is_dynamic_concept sibling."+["pipelex/core/concepts/native/concept_native.py::NativeConceptCode.is_text_concept"]param = "concept_code"rationale = "Predicate on the concept code; single operand."diff --git a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.pyindex b482b4ec7..9d82d4dc5 100644--- a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py+++ b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py@@ -3,8 +3,7 @@from collections.abc import Callablefrom pathlib import Path-from pipelex.core.concepts.concept import Concept-from pipelex.interpreter_hub import get_library_manager+from pipelex.interpreter_hub import get_concept_library, get_library_managerclass TestRefinesCustomConcept:@@ -45,8 +44,8 @@ class TestRefinesCustomConcept:vip_customer_concept = library.concept_library.get_required_concept("refines_custom_test.VIPCustomer")# Get the structure classes- customer_class = customer_concept.get_structure_class()- vip_customer_class = vip_customer_concept.get_structure_class()+ customer_class = get_concept_library().get_structure_class(concept=customer_concept)+ vip_customer_class = get_concept_library().get_structure_class(concept=vip_customer_concept)# Verify VIPCustomer is a subclass of Customer's structure classassert issubclass(vip_customer_class, customer_class)@@ -71,8 +70,8 @@ class TestRefinesCustomConcept:vip_customer_concept = library.concept_library.get_required_concept("refines_custom_test.VIPCustomer")# Get the structure classes- customer_class = customer_concept.get_structure_class()- vip_customer_class = vip_customer_concept.get_structure_class()+ customer_class = get_concept_library().get_structure_class(concept=customer_concept)+ vip_customer_class = get_concept_library().get_structure_class(concept=vip_customer_concept)# Create a VIPCustomer instance with Customer fieldsvip_customer_instance = vip_customer_class(@@ -88,7 +87,7 @@ class TestRefinesCustomConcept:assert vip_customer_instance.email == "[email protected]" # type: ignore[attr-defined]def test_concepts_are_compatible(self, load_test_library: Callable[[list[Path]], None]):- """Test that Concept.are_concept_compatible returns True for refined concept."""+ """Test that the library reports a refined concept as compatible with what it refines."""test_dir = Path(__file__).parentload_test_library([test_dir])@@ -100,4 +99,4 @@ class TestRefinesCustomConcept:vip_customer_concept = library.concept_library.get_required_concept("refines_custom_test.VIPCustomer")# VIPCustomer should be compatible with Customer (it refines Customer)- assert Concept.are_concept_compatible(concept_1=vip_customer_concept, concept_2=customer_concept)+ assert library.concept_library.is_compatible(tested_concept=vip_customer_concept, wanted_concept=customer_concept)diff --git a/tests/integration/pipelex/csv/test_csv_roundtrip.py b/tests/integration/pipelex/csv/test_csv_roundtrip.pyindex 4c23b7ff7..4c16474c4 100644--- a/tests/integration/pipelex/csv/test_csv_roundtrip.py+++ b/tests/integration/pipelex/csv/test_csv_roundtrip.py@@ -75,7 +75,7 @@ class TestCsvRoundtrip:def test_list_content_writes_to_csv(self, tmp_path: Path, load_test_library: Callable[[list[Path]], None]) -> None:load_test_library([BUNDLE_DIR])summary_concept = get_library_manager().get_current_library().concept_library.get_required_concept("csv_demo.PersonSummary")- summary_class = summary_concept.get_structure_class()+ summary_class = get_concept_library().get_structure_class(concept=summary_concept)items = [summary_class.model_validate({"name": "Ada Lovelace", "country": "United Kingdom", "summary": "A visionary mathematician."}),diff --git a/tests/integration/pipelex/libraries/test_concept_to_concept_references.py b/tests/integration/pipelex/libraries/test_concept_to_concept_references.pyindex 3786bf23b..9502e5c45 100644--- a/tests/integration/pipelex/libraries/test_concept_to_concept_references.py+++ b/tests/integration/pipelex/libraries/test_concept_to_concept_references.py@@ -6,7 +6,7 @@ from pathlib import Pathimport pytest-from pipelex.interpreter_hub import get_library_manager+from pipelex.interpreter_hub import get_concept_library, get_library_managerclass TestConceptToConceptReferences:@@ -51,7 +51,7 @@ total = { type = "number", description = "Invoice total" }assert invoice_concept is not None# Verify the Invoice structure class has a customer field typed to Customer- invoice_class = invoice_concept.get_structure_class()+ invoice_class = get_concept_library().get_structure_class(concept=invoice_concept)assert invoice_class is not None# The customer field should reference the Customer class@@ -97,7 +97,7 @@ total = { type = "number", description = "Invoice total" }assert invoice_concept is not None# Verify the Invoice structure class has an items field that's a list- invoice_class = invoice_concept.get_structure_class()+ invoice_class = get_concept_library().get_structure_class(concept=invoice_concept)items_field = invoice_class.model_fields.get("items")assert items_field is not Nonediff --git a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.pyindex b52ca4202..0f7ca09b2 100644--- a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py+++ b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py@@ -21,10 +21,14 @@ class TestPipeLLMBlueprintConversion:self, test_name: str, pipe_spec: PipeLLMSpec, expected_blueprint: PipeLLMBlueprint, load_empty_library: Callable[[], str]):load_empty_library()- item_concept = ConceptFactory.make(concept_code="Item", domain_code="test_domain", description="Item", structure_class_name="Item")- data_concept = ConceptFactory.make(concept_code="Data", domain_code="test_domain", description="Data", structure_class_name="Data")- analysis_concept = ConceptFactory.make(- concept_code="Analysis", domain_code="test_domain", description="Analysis", structure_class_name="Analysis"+ # Built from blueprints, not `ConceptFactory.make`: the blueprint path materializes and+ # registers each structure class, so the library reaches a state the loader could actually+ # produce. Naming a structure class that no registry holds is not a state a real library+ # can be in, and compatibility questions about it have no answer.+ item_concept = ConceptFactory.make_from_blueprint(concept_code="Item", domain_code="test_domain", blueprint_or_string_description="Item")+ data_concept = ConceptFactory.make_from_blueprint(concept_code="Data", domain_code="test_domain", blueprint_or_string_description="Data")+ analysis_concept = ConceptFactory.make_from_blueprint(+ concept_code="Analysis", domain_code="test_domain", blueprint_or_string_description="Analysis")concept_library = get_concept_library()concept_library.add_new_concept(concept=item_concept)diff --git a/tests/unit/pipelex/builder/test_runner_generator.py b/tests/unit/pipelex/builder/test_runner_generator.pyindex 98993b852..539add142 100644--- a/tests/unit/pipelex/builder/test_runner_generator.py+++ b/tests/unit/pipelex/builder/test_runner_generator.py@@ -13,6 +13,7 @@ from pipelex.core.concepts.concept_representation_generator import ConceptRepresfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecsfrom pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec+from pipelex.libraries.concept.concept_library import ConceptLibraryif TYPE_CHECKING:from pytest_mock import MockerFixture, MockType@@ -24,7 +25,9 @@ class TestConceptGenerateInputRepresentationJson:def test_native_text_json(self) -> None:"""Test JSON representation for native Text concept."""concept = ConceptFactory.make_native_concept(NativeConceptCode.TEXT)- result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)+ result, _ = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.JSON+ )assert result["concept"] == "native.Text"assert "content" in resultassert "text" in result["content"]@@ -32,7 +35,9 @@ class TestConceptGenerateInputRepresentationJson:def test_native_image_json(self) -> None:"""Test JSON representation for native Image concept."""concept = ConceptFactory.make_native_concept(NativeConceptCode.IMAGE)- result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)+ result, _ = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.JSON+ )assert result["concept"] == "native.Image"assert "content" in resultassert "url" in result["content"]@@ -40,7 +45,9 @@ class TestConceptGenerateInputRepresentationJson:def test_native_number_json(self) -> None:"""Test JSON representation for native Number concept."""concept = ConceptFactory.make_native_concept(NativeConceptCode.NUMBER)- result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)+ result, _ = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.JSON+ )assert result["concept"] == "native.Number"assert "content" in resultassert "number" in result["content"]@@ -48,7 +55,11 @@ class TestConceptGenerateInputRepresentationJson:def test_native_document_json_with_multiplicity(self) -> None:"""Test JSON representation for Document with multiplicity - content should be a list."""concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)- result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON, is_multiple=True)+ result, _ = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept),+ output_format=ConceptRepresentationFormat.JSON,+ is_multiple=True,+ )assert result["concept"] == "native.Document"assert "content" in result# Content should be a list@@ -64,7 +75,9 @@ class TestConceptGenerateInputRepresentationPython:def test_native_text_python(self) -> None:"""Test Python representation for native Text concept."""concept = ConceptFactory.make_native_concept(NativeConceptCode.TEXT)- result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)+ result, imports = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.PYTHON+ )assert result["concept"] == "native.Text"assert "TextContent" in result["content"]assert "TextContent" in imports@@ -72,7 +85,9 @@ class TestConceptGenerateInputRepresentationPython:def test_native_image_python(self) -> None:"""Test Python representation for native Image concept."""concept = ConceptFactory.make_native_concept(NativeConceptCode.IMAGE)- result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)+ result, imports = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.PYTHON+ )assert result["concept"] == "native.Image"assert "ImageContent" in result["content"]assert "ImageContent" in imports@@ -86,7 +101,9 @@ class TestConceptGenerateInputRepresentationPython:structure_class_name="TextContent",refines="native.Text",)- result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)+ result, imports = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept), output_format=ConceptRepresentationFormat.PYTHON+ )assert result["concept"] == "test_domain.Question"assert "TextContent" in result["content"]assert "TextContent" in imports@@ -94,7 +111,11 @@ class TestConceptGenerateInputRepresentationPython:def test_native_document_python_with_multiplicity(self) -> None:"""Test Python representation for Document with multiplicity - for Python format, wrapping is handled by caller."""concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)- result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON, is_multiple=True)+ result, imports = concept.render_concept_representation(+ structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept),+ output_format=ConceptRepresentationFormat.PYTHON,+ is_multiple=True,+ )# For Python format, is_multiple doesn't wrap content (caller handles it)assert result["concept"] == "native.Document"assert "DocumentContent" in result["content"]@@ -107,14 +128,14 @@ class TestInputStuffSpecsRenderInputsRepresentation:def test_empty_inputs(self) -> None:"""Test JSON generation with no inputs."""inputs = InputStuffSpecs(root={})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert result == {}def test_single_input(self) -> None:"""Test JSON generation with a single input."""concept = ConceptFactory.make_native_concept(NativeConceptCode.TEXT)inputs = InputStuffSpecs(root={"message": StuffSpec(concept=concept)})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert "message" in resultassert result["message"]["concept"] == "native.Text"@@ -128,7 +149,7 @@ class TestInputStuffSpecsRenderInputsRepresentation:"image_input": StuffSpec(concept=image_concept),})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert "text_input" in resultassert "image_input" in resultassert result["text_input"]["concept"] == "native.Text"@@ -142,7 +163,7 @@ class TestInputStuffSpecsRenderWithMultiplicity:"""Test that single item (no multiplicity) has content as dict, not list."""concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)inputs = InputStuffSpecs(root={"document": StuffSpec(concept=concept, multiplicity=None)})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert "document" in result# concept should be presentassert result["document"]["concept"] == "native.Document"@@ -155,7 +176,7 @@ class TestInputStuffSpecsRenderWithMultiplicity:"""Test that multiplicity=True wraps content in list."""concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)inputs = InputStuffSpecs(root={"documents": StuffSpec(concept=concept, multiplicity=True)})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert "documents" in result# concept should be at the top levelassert result["documents"]["concept"] == "native.Document"@@ -169,7 +190,7 @@ class TestInputStuffSpecsRenderWithMultiplicity:"""Test that multiplicity=N (int > 1) wraps content in list."""concept = ConceptFactory.make_native_concept(NativeConceptCode.IMAGE)inputs = InputStuffSpecs(root={"images": StuffSpec(concept=concept, multiplicity=3)})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))assert "images" in result# concept should be at the top levelassert result["images"]["concept"] == "native.Image"@@ -188,7 +209,7 @@ class TestInputStuffSpecsRenderWithMultiplicity:"multiple_documents": StuffSpec(concept=document_concept, multiplicity=True),})- result = json.loads(inputs.render_inputs())+ result = json.loads(inputs.render_inputs(concept_provider=ConceptLibrary.make_empty()))# single_document content should be a dictassert isinstance(result["single_document"]["content"], dict)# multiple_documents content should be a list@@ -198,6 +219,16 @@ class TestInputStuffSpecsRenderWithMultiplicity:class TestGenerateRunnerCode:"""Test generate_runner_code function."""+ @pytest.fixture(autouse=True)+ def stub_concept_library(self, mocker: MockerFixture) -> None:+ """The generator resolves structure classes through the loaded method's library.++ These tests drive it with mock pipes rather than a loaded method, so an empty+ `ConceptLibrary` stands in: it holds no concepts but resolves any class the process+ registry already has, which is all the code generation needs.+ """+ mocker.patch("pipelex.builder.runner_code.get_concept_library", return_value=ConceptLibrary.make_empty())+@pytest.fixturedef mock_pipe_single_output(self, mocker: MockerFixture) -> MockType:"""Create a mock pipe with a single output."""diff --git a/tests/unit/pipelex/cli/test_run_core_execution.py b/tests/unit/pipelex/cli/test_run_core_execution.pyindex ba5c6be36..bff27f461 100644--- a/tests/unit/pipelex/cli/test_run_core_execution.py+++ b/tests/unit/pipelex/cli/test_run_core_execution.py@@ -75,6 +75,15 @@ class TestRunCoreExecution:mocker.patch("pipelex.cli.commands.run._run_core.render_cost_report_for_output")return runner_class_mock+ def _mock_structure_class(self, mocker: MockerFixture, *, resolves_to: Any = None, raises: Exception | None = None) -> None:+ """Stand in for the concept library that resolves the CSV row class."""+ concept_library_mock = mocker.MagicMock()+ if raises is not None:+ concept_library_mock.get_structure_class.side_effect = raises+ else:+ concept_library_mock.get_structure_class.return_value = resolves_to+ mocker.patch("pipelex.cli.commands.run._run_core.ConceptLibrary.make_empty", return_value=concept_library_mock)+def _make_pipe_output(self,mocker: MockerFixture,@@ -410,9 +419,9 @@ class TestRunCoreExecution:"""A flat list output is written through the CSV codec to the literal path."""main_stuff = mocker.MagicMock()main_stuff.content = ListContent(items=[TextContent(text="row one")])- main_stuff.concept.get_structure_class.return_value = TextContentpipe_output = self._make_pipe_output(mocker, main_stuff=main_stuff)self._mock_runner(mocker, pipe_output)+ self._mock_structure_class(mocker, resolves_to=TextContent)mocker.patch("pipelex.cli.commands.run._run_core.flat_field_names", return_value=["text"])csv_codec_mock = mocker.patch("pipelex.cli.commands.run._run_core.csv_from_list_content")csv_target = tmp_path / "reports" / "out.csv"@@ -429,9 +438,9 @@ class TestRunCoreExecution:"""A missing structure class on the output concept is a --save-csv failure."""main_stuff = mocker.MagicMock()main_stuff.content = ListContent(items=[TextContent(text="row one")])- main_stuff.concept.get_structure_class.side_effect = ConceptValueError("no structure class")pipe_output = self._make_pipe_output(mocker, main_stuff=main_stuff)self._mock_runner(mocker, pipe_output)+ self._mock_structure_class(mocker, raises=ConceptValueError("no structure class"))with pytest.raises(typer.Exit) as exc_info:_run_async(_call_execute_run(save_csv=str(tmp_path / "out.csv")))diff --git a/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.py b/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.pyindex 6098c4baf..4523f0bdd 100644--- a/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.py+++ b/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.py@@ -1,8 +1,8 @@-from pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.stuffs.date_content import DateContent+from pipelex.libraries.concept.concept_library import ConceptLibraryclass TestDateRefinement:@@ -16,8 +16,9 @@ class TestDateRefinement:blueprint_or_string_description=ConceptBlueprint(description="The date payment is due", refines="Date"),)- structure_class = concept.get_structure_class()+ library = ConceptLibrary.make_empty()+ structure_class = library.get_structure_class(concept=concept)assert issubclass(structure_class, DateContent)native_date = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE)- assert Concept.are_concept_compatible(concept_1=concept, concept_2=native_date, strict=True)+ assert library.is_compatible(tested_concept=concept, wanted_concept=native_date, strict=True)diff --git a/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py b/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.pyindex 1e61feca2..c16df60c1 100644--- a/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py+++ b/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py@@ -1,8 +1,8 @@-from pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.stuffs.yes_no_content import YesNoContent+from pipelex.libraries.concept.concept_library import ConceptLibraryclass TestYesNoRefinement:@@ -16,8 +16,9 @@ class TestYesNoRefinement:blueprint_or_string_description=ConceptBlueprint(description="Whether the item is urgent", refines="YesNo"),)- structure_class = concept.get_structure_class()+ library = ConceptLibrary.make_empty()+ structure_class = library.get_structure_class(concept=concept)assert issubclass(structure_class, YesNoContent)native_yes_no = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO)- assert Concept.are_concept_compatible(concept_1=concept, concept_2=native_yes_no, strict=True)+ assert library.is_compatible(tested_concept=concept, wanted_concept=native_yes_no, strict=True)diff --git a/tests/unit/pipelex/core/concepts/test_concept.py b/tests/unit/pipelex/core/concepts/test_concept.pyindex e78fc1884..e97c4f0ec 100644--- a/tests/unit/pipelex/core/concepts/test_concept.py+++ b/tests/unit/pipelex/core/concepts/test_concept.py@@ -1,39 +1,14 @@import pytest-from kajson.kajson_manager import KajsonManager-from pydantic import Field, ValidationError+from pydantic import ValidationErrorfrom pipelex.core.concepts.concept import Conceptfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.concept_factory import ConceptFactory-from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldTypefrom pipelex.core.concepts.exceptions import ConceptStringErrorfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.concepts.native.exceptions import NativeConceptDefinitionErrorfrom pipelex.core.concepts.validation import validate_concept_reffrom pipelex.core.domains.domain import SpecialDomain-from pipelex.core.stuffs.structured_content import StructuredContent---# Custom StuffContent class with nested ImageContent-like field for testing-class NestedImageInfo(StructuredContent):- """A nested structure that contains image-like data (same structure as ImageContent)."""-- url: str- public_url: str | None = None- source_prompt: str | None = None- source_negative_prompt: str | None = None- caption: str | None = None- mime_type: str | None = None- width: int | None = Field(default=None, gt=0)- height: int | None = Field(default=None, gt=0)- filename: str | None = None---class DocumentWithNestedImage(StructuredContent):- """A content class that has a nested field containing image info."""-- title: str- metadata: NestedImageInfoclass TestConcept:@@ -270,144 +245,3 @@ class TestConcept:description="Test concept",structure_class_name="TextContent",)-- def test_are_concept_compatible(self):- concept1 = ConceptFactory.make_from_blueprint(- concept_code="Code1",- domain_code="domain1",- blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", refines=NativeConceptCode.TEXT),- )- concept2 = ConceptFactory.make_from_blueprint(- concept_code="Code2",- domain_code="domain1",- blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", refines=NativeConceptCode.TEXT),- )- concept3 = ConceptFactory.make_from_blueprint(- concept_code="Code3",- domain_code="domain2",- blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", structure="TextContent"),- )- concept4 = ConceptFactory.make_from_blueprint(- concept_code="Code4",- domain_code="domain1",- blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", structure="ImageContent"),- )-- concept_5 = ConceptFactory.make_native_concept(- native_concept_code=NativeConceptCode.PAGE,- )-- concept_6 = ConceptFactory.make_native_concept(- native_concept_code=NativeConceptCode.IMAGE,- )-- concept_7 = ConceptFactory.make_from_blueprint(- concept_code="VisualDescription",- domain_code="images",- blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum"),- )-- assert Concept.are_concept_compatible(concept_1=concept_7, concept_2=concept_6, strict=True) is False- assert Concept.are_concept_compatible(concept_1=concept_7, concept_2=concept_6, strict=False) is False-- # Test same code and domain- assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept2) is True-- # Test different code and domain- assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept3) is True-- # Test same structure class name- assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept4) is False-- # Test same refines- assert Concept.are_concept_compatible(concept_1=concept_5, concept_2=concept_6, strict=False) is True- assert Concept.are_concept_compatible(concept_1=concept_5, concept_2=concept_6, strict=True) is False-- def test_concept_refining_text_is_strictly_compatible(self):- """Test that a concept created with .make() that refines native.Text is strictly compatible with Text."""- # Create a concept that refines native.Text using ConceptFactory.make()- concept_not_native_text = ConceptFactory.make(- domain_code="test_domain",- concept_code="MyConceptNotNativeText",- description="Test concept for unit tests",- structure_class_name="TextContent",- refines="native.Text",- )-- # Get the native Text concept- text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)-- # A concept that refines Text should be strictly compatible with Text- assert Concept.are_concept_compatible(concept_1=concept_not_native_text, concept_2=text_concept, strict=True) is True- assert Concept.are_concept_compatible(concept_1=concept_not_native_text, concept_2=text_concept, strict=False) is True-- def test_concept_with_same_structure_as_text_content(self):- """Test: create a concept with a structure EXACTLY like TextContent (text: str) and compare with native Text."""- # Create a concept with a structure blueprint that has exactly the same field as TextContent: text: str- custom_text_like_concept = ConceptFactory.make_from_blueprint(- concept_code="MyTextLikeConcept",- domain_code="test_structure_equiv",- blueprint_or_string_description=ConceptBlueprint(- description="A concept with the exact same structure as TextContent",- structure={- "text": ConceptStructureBlueprint(- type=ConceptStructureBlueprintFieldType.TEXT,- description="The text content",- required=True,- ),- },- ),- )-- # Get the native Text concept- native_text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)-- # They have different structure_class_names but the same JSON structure- assert custom_text_like_concept.structure_class_name != native_text_concept.structure_class_name-- # Concepts with the same JSON structure should be compatible- assert Concept.are_concept_compatible(concept_1=custom_text_like_concept, concept_2=native_text_concept, strict=True) is True- assert Concept.are_concept_compatible(concept_1=custom_text_like_concept, concept_2=native_text_concept, strict=False) is True-- def test_nested_image_content_strict_false_nonstrict_true(self):- """Test: strict=True returns False, strict=False returns True for nested compatible field."""- # Register our custom classes with the class registry- KajsonManager.get_class_registry().register_class(NestedImageInfo)- KajsonManager.get_class_registry().register_class(DocumentWithNestedImage)-- # Create a concept using our custom DocumentWithNestedImage class- concept_with_nested_image = ConceptFactory.make(- domain_code="test_nested",- concept_code="DocumentWithImage",- description="A document containing nested image info",- structure_class_name="DocumentWithNestedImage",- )-- # Create a concept using the NestedImageInfo class (same structure as ImageContent)- concept_image_like = ConceptFactory.make(- domain_code="test_nested",- concept_code="ImageInfo",- description="Image-like info",- structure_class_name="NestedImageInfo",- )-- # Get the native Image concept (uses ImageContent)- native_image_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.IMAGE)-- # --- Test with NestedImageInfo (custom class with same structure as ImageContent) ---- # strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to NestedImageInfo- assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=concept_image_like, strict=True) is False- # strict=False should be True: DocumentWithNestedImage has a field (metadata) that is NestedImageInfo- assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=concept_image_like, strict=False) is True-- # --- Test NestedImageInfo vs native Image (ImageContent) ---- # NestedImageInfo has the same structure as ImageContent, so should be strictly compatible- assert Concept.are_concept_compatible(concept_1=concept_image_like, concept_2=native_image_concept, strict=True) is True- assert Concept.are_concept_compatible(concept_1=concept_image_like, concept_2=native_image_concept, strict=False) is True-- # --- Test DocumentWithNestedImage vs native Image (ImageContent) ---- # strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to ImageContent- assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=native_image_concept, strict=True) is False- # strict=False should be True: DocumentWithNestedImage has a nested field (metadata: NestedImageInfo)- # that is STRUCTURALLY EQUIVALENT to ImageContent- assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=native_image_concept, strict=False) is Truediff --git a/tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py b/tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.pydeleted file mode 100644index 80656ac3e..000000000--- a/tests/unit/pipelex/core/concepts/test_concept_cross_package_refines.py+++ /dev/null@@ -1,141 +0,0 @@-from pipelex.core.concepts.concept import Concept---def _make_concept(code: str, domain_code: str, refines: str | None = None) -> Concept:- """Create a minimal Concept for testing."""- return Concept(- code=code,- domain_code=domain_code,- description="Test concept",- structure_class_name="TextContent",- refines=refines,- )---class TestConceptCrossPackageRefines:- """Tests for cross-package refinement compatibility in Concept.are_concept_compatible()."""-- def test_refines_cross_package_with_resolver_compatible(self):- """Concept refining cross-package concept is compatible when resolver resolves to target."""- refining = _make_concept(code="RefinedScore", domain_code="my_domain", refines="scoring_dep->scoring.WeightedScore")- target = _make_concept(code="WeightedScore", domain_code="scoring")-- def resolver(concept_ref: str) -> Concept | None:- if concept_ref == "scoring_dep->scoring.WeightedScore":- return target- return None-- assert Concept.are_concept_compatible(concept_1=refining, concept_2=target, concept_resolver=resolver) is True-- def test_refines_cross_package_without_resolver_not_compatible(self):- """Cross-package refines without a resolver is not compatible via refines check."""- refining = _make_concept(code="RefinedScore", domain_code="my_domain", refines="scoring_dep->scoring.WeightedScore")- target = _make_concept(code="WeightedScore", domain_code="scoring")-- # Without resolver, the cross-package refines string won't match the target concept_ref- # They might still be compatible via structure_class_name (both TextContent)- # but the refines-based check specifically won't match- result = Concept.are_concept_compatible(concept_1=refining, concept_2=target)- # Compatible due to same structure_class_name, not due to refines resolution- assert result is True-- def test_refines_cross_package_different_structure_without_resolver(self):- """Cross-package refines with different structures, without resolver."""- refining = Concept(- code="RefinedScore",- domain_code="my_domain",- description="Refined",- structure_class_name="RefinedScoreContent",- refines="scoring_dep->scoring.WeightedScore",- )- target = Concept(- code="WeightedScore",- domain_code="scoring",- description="Target",- structure_class_name="WeightedScoreContent",- )-- # Without resolver, and different structure_class_name, not compatible via refines- result = Concept.are_concept_compatible(concept_1=refining, concept_2=target)- assert result is False-- def test_refines_cross_package_different_structure_with_resolver(self):- """Cross-package refines with different structures, but resolver resolves correctly."""- refining = Concept(- code="RefinedScore",- domain_code="my_domain",- description="Refined",- structure_class_name="RefinedScoreContent",- refines="scoring_dep->scoring.WeightedScore",- )- target = Concept(- code="WeightedScore",- domain_code="scoring",- description="Target",- structure_class_name="WeightedScoreContent",- )-- def resolver(concept_ref: str) -> Concept | None:- if concept_ref == "scoring_dep->scoring.WeightedScore":- return target- return None-- result = Concept.are_concept_compatible(concept_1=refining, concept_2=target, concept_resolver=resolver)- assert result is True-- def test_both_refine_same_cross_package_concept_siblings(self):- """Two concepts that both refine the same cross-package concept are siblings."""- base = _make_concept(code="BaseScore", domain_code="scoring")-- sibling_a = Concept(- code="ScoreA",- domain_code="my_domain",- description="Sibling A",- structure_class_name="ScoreAContent",- refines="scoring_dep->scoring.BaseScore",- )- sibling_b = Concept(- code="ScoreB",- domain_code="my_domain",- description="Sibling B",- structure_class_name="ScoreBContent",- refines="scoring_dep->scoring.BaseScore",- )-- def resolver(concept_ref: str) -> Concept | None:- if concept_ref == "scoring_dep->scoring.BaseScore":- return base- return None-- result = Concept.are_concept_compatible(concept_1=sibling_a, concept_2=sibling_b, concept_resolver=resolver)- assert result is True-- def test_resolver_returns_none_not_compatible(self):- """When resolver returns None for a cross-package refines, not compatible via refines."""- refining = Concept(- code="RefinedScore",- domain_code="my_domain",- description="Refined",- structure_class_name="RefinedScoreContent",- refines="unknown_dep->scoring.Missing",- )- target = Concept(- code="WeightedScore",- domain_code="scoring",- description="Target",- structure_class_name="WeightedScoreContent",- )-- def resolver(_concept_ref: str) -> Concept | None:- return None-- result = Concept.are_concept_compatible(concept_1=refining, concept_2=target, concept_resolver=resolver)- assert result is False-- def test_local_refines_unaffected(self):- """Local (non-cross-package) refines still works without resolver."""- base = _make_concept(code="BaseScore", domain_code="scoring")- refining = _make_concept(code="DetailedScore", domain_code="scoring", refines="scoring.BaseScore")-- result = Concept.are_concept_compatible(concept_1=refining, concept_2=base)- assert result is Truediff --git a/tests/unit/pipelex/core/concepts/test_concept_declaration_compatibility.py b/tests/unit/pipelex/core/concepts/test_concept_declaration_compatibility.pynew file mode 100644index 000000000..d237fd30b--- /dev/null+++ b/tests/unit/pipelex/core/concepts/test_concept_declaration_compatibility.py@@ -0,0 +1,137 @@+"""The declaration tier of concept compatibility, exercised with no class registry at all.++`Concept.are_compatible_by_declaration` answers compatibility from the model's own fields — refs,+`structure_class_name` strings, `refines` chains, and the injected `concept_resolver` — and never+reaches for a class. That is what makes these rows expressible as plain constructor calls with+structure class names that no registry has ever heard of: if any row needed a class, it would fail+here rather than quietly resolve one from ambient process state.++`True` means "compatibility is established by the declarations"; `False` means "not established at+this tier" — never "incompatible". The class tier (`are_structure_classes_compatible`) and the+composition of the two (`ConceptLibrary.is_compatible`) are tested separately.+"""++from __future__ import annotations++import inspect++from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.native.concept_native import NativeConceptCode+++def _make_concept(*, code: str, domain_code: str, structure_class_name: str, refines: str | None = None) -> Concept:+ return Concept(+ code=code,+ domain_code=domain_code,+ description="Test concept",+ structure_class_name=structure_class_name,+ refines=refines,+ )+++class TestConceptDeclarationCompatibility:+ def test_dynamic_concept_is_compatible_with_anything(self):+ """`Dynamic` short-circuits on either side — it is the untyped escape hatch."""+ dynamic = _make_concept(+ code=NativeConceptCode.DYNAMIC,+ domain_code="native",+ structure_class_name=NativeConceptCode.DYNAMIC.structure_class_name,+ )+ other = _make_concept(code="Whatever", domain_code="somewhere", structure_class_name="NeverRegisteredContent")++ assert Concept.are_compatible_by_declaration(concept_1=dynamic, concept_2=other) is True+ assert Concept.are_compatible_by_declaration(concept_1=other, concept_2=dynamic) is True++ def test_same_concept_ref_is_compatible(self):+ one = _make_concept(code="Invoice", domain_code="billing", structure_class_name="NeverRegisteredContent")+ same = _make_concept(code="Invoice", domain_code="billing", structure_class_name="AlsoNeverRegistered")++ assert Concept.are_compatible_by_declaration(concept_1=one, concept_2=same) is True++ def test_same_structure_class_name_is_compatible(self):+ one = _make_concept(code="Invoice", domain_code="billing", structure_class_name="NeverRegisteredContent")+ other = _make_concept(code="Receipt", domain_code="accounting", structure_class_name="NeverRegisteredContent")++ assert Concept.are_compatible_by_declaration(concept_1=one, concept_2=other) is True++ def test_refines_the_target_directly(self):+ base = _make_concept(code="BaseScore", domain_code="scoring", structure_class_name="BaseScoreContent")+ refining = _make_concept(+ code="DetailedScore",+ domain_code="scoring",+ structure_class_name="DetailedScoreContent",+ refines="scoring.BaseScore",+ )++ assert Concept.are_compatible_by_declaration(concept_1=refining, concept_2=base) is True++ def test_siblings_refining_the_same_concept(self):+ sibling_a = _make_concept(code="ScoreA", domain_code="my_domain", structure_class_name="ScoreAContent", refines="scoring.BaseScore")+ sibling_b = _make_concept(code="ScoreB", domain_code="my_domain", structure_class_name="ScoreBContent", refines="scoring.BaseScore")++ assert Concept.are_compatible_by_declaration(concept_1=sibling_a, concept_2=sibling_b) is True++ def test_unrelated_declarations_are_not_established(self):+ """Nothing in the declarations relates these two — the class tier would have to decide."""+ one = _make_concept(code="Invoice", domain_code="billing", structure_class_name="InvoiceContent")+ other = _make_concept(code="Portrait", domain_code="gallery", structure_class_name="PortraitContent")++ assert Concept.are_compatible_by_declaration(concept_1=one, concept_2=other) is False++ def test_cross_package_refines_resolves_through_the_resolver(self):+ target = _make_concept(code="WeightedScore", domain_code="scoring", structure_class_name="WeightedScoreContent")+ refining = _make_concept(+ code="RefinedScore",+ domain_code="my_domain",+ structure_class_name="RefinedScoreContent",+ refines="scoring_dep->scoring.WeightedScore",+ )++ def resolver(concept_ref: str) -> Concept | None:+ return target if concept_ref == "scoring_dep->scoring.WeightedScore" else None++ assert Concept.are_compatible_by_declaration(concept_1=refining, concept_2=target, concept_resolver=resolver) is True+ # Without the resolver the alias is an opaque string: not established at this tier.+ assert Concept.are_compatible_by_declaration(concept_1=refining, concept_2=target) is False++ def test_cross_package_siblings_resolve_through_the_resolver(self):+ base = _make_concept(code="BaseScore", domain_code="scoring", structure_class_name="BaseScoreContent")+ sibling_a = _make_concept(+ code="ScoreA",+ domain_code="my_domain",+ structure_class_name="ScoreAContent",+ refines="scoring_dep->scoring.BaseScore",+ )+ sibling_b = _make_concept(+ code="ScoreB",+ domain_code="other_domain",+ structure_class_name="ScoreBContent",+ refines="scoring_alias->scoring.BaseScore",+ )++ def resolver(concept_ref: str) -> Concept | None:+ return base if concept_ref in {"scoring_dep->scoring.BaseScore", "scoring_alias->scoring.BaseScore"} else None++ assert Concept.are_compatible_by_declaration(concept_1=sibling_a, concept_2=sibling_b, concept_resolver=resolver) is True++ def test_resolver_returning_none_leaves_it_unestablished(self):+ target = _make_concept(code="WeightedScore", domain_code="scoring", structure_class_name="WeightedScoreContent")+ refining = _make_concept(+ code="RefinedScore",+ domain_code="my_domain",+ structure_class_name="RefinedScoreContent",+ refines="unknown_dep->scoring.Missing",+ )++ def resolver(_concept_ref: str) -> Concept | None:+ return None++ assert Concept.are_compatible_by_declaration(concept_1=refining, concept_2=target, concept_resolver=resolver) is False++ def test_declaration_tier_takes_no_strict_flag(self):+ """Strictness governs the class tier only, so it is not a parameter here.++ Pinned as a signature fact: a caller that wants strict-mode semantics must go through+ `ConceptLibrary.is_compatible`, which owns the composition of the two tiers.+ """+ assert "strict" not in inspect.signature(Concept.are_compatible_by_declaration).parametersdiff --git a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.pyindex 74b09b087..d3777e88b 100644--- a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py+++ b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py@@ -5,6 +5,7 @@ import pytestfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.stuffs.image_field_search import search_for_nested_image_fieldsfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_conceptfrom pipelex.system.registries.class_registry_utils import ClassRegistryUtils@@ -81,7 +82,7 @@ def register_test_concepts(load_test_library: Callable[[list[Path]], None]):class TestConceptFindImageFieldPaths:- """Test Concept.search_for_nested_image_fields_in_structure_class() method."""+ """Resolve a concept's structure class through the library, then search it for image fields."""@pytest.mark.parametrize(("concept_code", "expected_paths"),@@ -112,7 +113,7 @@ class TestConceptFindImageFieldPaths:concept = get_required_concept(f"{TestData.DOMAIN}.{concept_code}")# Find image paths- image_paths = concept.search_for_nested_image_fields_in_structure_class()+ image_paths = search_for_nested_image_fields(content_class=get_concept_library().get_structure_class(concept=concept))# Assert exact match of paths (order-independent)assert sorted(image_paths) == sorted(expected_paths), f"Expected paths {sorted(expected_paths)}, but got {sorted(image_paths)}"@@ -127,7 +128,7 @@ class TestConceptFindImageFieldPaths:concept = get_native_concept(NativeConceptCode.IMAGE)# Find image paths- image_paths = concept.search_for_nested_image_fields_in_structure_class()+ image_paths = search_for_nested_image_fields(content_class=get_concept_library().get_structure_class(concept=concept))# Assert - should return empty because the concept itself is an imageassert image_paths == []@@ -141,7 +142,7 @@ class TestConceptFindImageFieldPaths:concept = get_native_concept(NativeConceptCode.TEXT_AND_IMAGES)# Find image paths- image_paths = concept.search_for_nested_image_fields_in_structure_class()+ image_paths = search_for_nested_image_fields(content_class=get_concept_library().get_structure_class(concept=concept))# Assert - should find the images field which is list[ImageContent] | Noneassert image_paths == ["images"]diff --git a/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py b/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.pynew file mode 100644index 000000000..6723cfa8a--- /dev/null+++ b/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py@@ -0,0 +1,130 @@+# `Concept` is a subclass of the MTHDS-protocol wire model `ConceptAbstract` — pure serializable data.+# It used to answer behavioral questions ("are these two compatible?", "what is this concept's class?") by+# reaching into the process-global class registry, which made a standard-owned wire model depend on a+# Pipelex process-global and made the same two values answer differently depending on which async context+# asked. `refactor/Concept-purity` moved every one of those reads out: reading the registry is a+# `ConceptProviderAbstract` implementation's job, and `core/` states that dependency as a parameter.+#+# What is left inside `pipelex/core/concepts/` is the **write side** — materializing generated structure+# classes at library-load time and registering them. That is genuinely the registry's business and stays,+# so the property is not "no module here touches the registry" but "exactly these two do".+#+# Pinned as a golden set rather than as a rule, for the reason the `cogt` boundary test gives: there is no+# predicate separating the sanctioned write-side reads from a new read-side one, and a golden set needs+# none — it turns the third module into a diff a reviewer sees. Nothing else can see this: both the+# accessor and its users are runtime-layer, so the hub-layering guard is blind to the edge by construction.++from __future__ import annotations++import ast+from pathlib import Path++import pytest++#: Anchored on `tests/` by name rather than by a parent count — a depth index resolves silently to the+#: wrong directory when a module moves, and this repo has been bitten by exactly that.+_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")+_REPO_ROOT = _TESTS_ROOT.parent+_CONCEPTS_DIR = _REPO_ROOT / "pipelex" / "core" / "concepts"++#: The module that hosts the accessor, below both hubs. Importing it *at all* is registry access —+#: it exports nothing else. `pipelex.runtime_hub` is deliberately NOT listed: it re-exports the+#: accessor among many unrelated ones, so the module is not the signal, the name and the call are.+_ACCESSOR_MODULE = "pipelex.system.registries.class_registry_access"+_ACCESSOR_NAME = "get_class_registry"++#: Reaching the registry without naming the accessor. `KajsonManager.get_class_registry()` returns the+#: process-global registry directly, bypassing library scoping entirely — there is a live precedent for+#: it at `runtime_bridge/primitives/rehydration.py`. `ClassRegistryUtils` calls the accessor internally,+#: so importing it is reaching the registry by proxy. An import-name-only walk misses both, which would+#: make this a check on one import spelling rather than on the property it claims to pin.+_INDIRECT_ACCESS_ROOTS = ("KajsonManager", "ClassRegistryUtils")++#: The materialization write side: the only two modules under `pipelex/core/concepts/` that may touch the+#: class registry. `concept_factory` registers generated structure classes and decides whether one already+#: exists; `structure_generation/generator.py` looks up base classes to generate against. Both run at+#: library-load time, on the way to *producing* a class rather than resolving one for a concept.+#:+#: A new entry here is a read-side leak until proven otherwise — the thing this branch removed. Resolving a+#: concept's declared `structure_class_name` belongs on a `ConceptProviderAbstract` implementation+#: (`ConceptLibrary.get_structure_class`), which is what every reader now calls.+EXPECTED_REGISTRY_USERS: frozenset[str] = frozenset(+ {+ "pipelex/core/concepts/concept_factory.py",+ "pipelex/core/concepts/structure_generation/generator.py",+ }+)++CONCEPT_MODULE_PATHS: list[Path] = sorted(_CONCEPTS_DIR.rglob("*.py"))+++def _reaches_the_class_registry(*, module_path: Path) -> bool:+ """Whether a module reaches the class registry at all — by import, by module path, or by proxy.++ Deliberately wider than "imports `get_class_registry` by name". A check that only matched the+ import name would pass a module doing `import pipelex.runtime_hub` followed by+ `pipelex.runtime_hub.get_class_registry()`, or one calling `KajsonManager.get_class_registry()`+ (which skips library scoping outright), and this is the gate that is supposed to catch a read-side+ leak growing back — so it matches the attribute call and the two indirect roots as well.+ """+ tree = ast.parse(module_path.read_text(encoding="utf-8"), filename=str(module_path))+ for node in ast.walk(tree):+ if isinstance(node, ast.Import):+ if any(alias.name == _ACCESSOR_MODULE for alias in node.names):+ return True+ elif isinstance(node, ast.ImportFrom):+ if node.module == _ACCESSOR_MODULE:+ return True+ if any(alias.name == _ACCESSOR_NAME or alias.name in _INDIRECT_ACCESS_ROOTS for alias in node.names):+ return True+ elif isinstance(node, ast.Attribute) and node.attr == _ACCESSOR_NAME:+ # `pipelex.runtime_hub.get_class_registry()` / `KajsonManager.get_class_registry()` —+ # the call reaches the registry whether or not the name was imported.+ return True+ return False+++class TestConceptRegistryBoundary:+ def test_only_the_materialization_write_side_touches_the_class_registry(self) -> None:+ """`pipelex/core/concepts/**` reaches the class registry from exactly the two write-side modules."""+ # Anti-vacuity: an empty walk would make the assertion below pass for free.+ assert CONCEPT_MODULE_PATHS, f"no Python module found under {_CONCEPTS_DIR} — this check measures nothing"++ actual = {+ module_path.relative_to(_REPO_ROOT).as_posix()+ for module_path in CONCEPT_MODULE_PATHS+ if _reaches_the_class_registry(module_path=module_path)+ }++ assert actual == EXPECTED_REGISTRY_USERS, (+ "which modules under `pipelex/core/concepts/` touch the class registry changed.\n"+ f" added: {sorted(actual - EXPECTED_REGISTRY_USERS)}\n"+ f" removed: {sorted(EXPECTED_REGISTRY_USERS - actual)}\n"+ "An added module is a DEFECT unless it materializes classes: resolving a concept's declared "+ "`structure_class_name` belongs on a ConceptProviderAbstract implementation "+ "(`ConceptLibrary.get_structure_class`), not on an ambient registry read — that coupling is what "+ "`refactor/Concept-purity` removed from the protocol-owned `Concept` wire model. "+ "See docs/contribute/hub-layering.md, 'Injected providers, not ambient lookups'."+ )++ @pytest.mark.parametrize(+ ("source", "expected"),+ [+ ("from pipelex.system.registries.class_registry_access import get_class_registry", True),+ ("from pipelex.runtime_hub import get_class_registry", True),+ ("import pipelex.system.registries.class_registry_access", True),+ ("from pipelex.runtime_hub import get_console, get_class_registry", True),+ # The spellings an import-name-only walk would wave through.+ ("def f():\n return pipelex.runtime_hub.get_class_registry()", True),+ ("from kajson.kajson_manager import KajsonManager", True),+ ("def f():\n return KajsonManager.get_class_registry()", True),+ ("from pipelex.system.registries.class_registry_utils import ClassRegistryUtils", True),+ ("from pipelex.runtime_hub import get_console", False),+ ("from pipelex.core.stuffs.stuff_content import StuffContent", False),+ ],+ )+ def test_every_way_of_reaching_the_registry_is_detected(self, source: str, expected: bool, tmp_path: Path) -> None:+ """Import name, module path, attribute call, and the two indirect roots all count."""+ module_path = tmp_path / "probe.py"+ module_path.write_text(source, encoding="utf-8")+ assert _reaches_the_class_registry(module_path=module_path) is expecteddiff --git a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.pyindex fa2cfc100..a0d659686 100644--- a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py+++ b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py@@ -517,12 +517,6 @@ class TestSchemaRepresentationWithMultiple:def test_schema_single_item(self) -> None:"""Schema for single item returns the JSON schema directly."""- from kajson.kajson_manager import KajsonManager # noqa: PLC0415-- # Register the test class- KajsonManager.get_class_registry().register_class(SimpleContent)-- # Create a concept with the registered classconcept = Concept(code="SimpleContent",domain_code="test",@@ -531,6 +525,7 @@ class TestSchemaRepresentationWithMultiple:)result, imports = concept.render_concept_representation(+ structure_class=SimpleContent,output_format=ConceptRepresentationFormat.SCHEMA,is_multiple=False,)@@ -544,12 +539,6 @@ class TestSchemaRepresentationWithMultiple:def test_schema_multiple_items_wraps_in_array(self) -> None:"""Schema for multiple items wraps the schema in an array type."""- from kajson.kajson_manager import KajsonManager # noqa: PLC0415-- # Register the test class- KajsonManager.get_class_registry().register_class(SimpleContent)-- # Create a concept with the registered classconcept = Concept(code="SimpleContent",domain_code="test",@@ -558,6 +547,7 @@ class TestSchemaRepresentationWithMultiple:)result, imports = concept.render_concept_representation(+ structure_class=SimpleContent,output_format=ConceptRepresentationFormat.SCHEMA,is_multiple=True,)@@ -575,13 +565,6 @@ class TestSchemaRepresentationWithMultiple:def test_schema_nested_content_multiple(self) -> None:"""Schema for nested content with multiple items wraps correctly."""- from kajson.kajson_manager import KajsonManager # noqa: PLC0415-- # Register the test classes- KajsonManager.get_class_registry().register_class(NestedChild)- KajsonManager.get_class_registry().register_class(ContentWithNestedClass)-- # Create a concept with the registered classconcept = Concept(code="ContentWithNestedClass",domain_code="test",@@ -590,6 +573,7 @@ class TestSchemaRepresentationWithMultiple:)result, _ = concept.render_concept_representation(+ structure_class=ContentWithNestedClass,output_format=ConceptRepresentationFormat.SCHEMA,is_multiple=True,)diff --git a/tests/unit/pipelex/libraries/test_concept_library_compatibility.py b/tests/unit/pipelex/libraries/test_concept_library_compatibility.pynew file mode 100644index 000000000..9584ee061--- /dev/null+++ b/tests/unit/pipelex/libraries/test_concept_library_compatibility.py@@ -0,0 +1,263 @@+"""`ConceptLibrary` composes the two compatibility tiers, and fails loudly when it cannot.++`is_compatible` asks the declaration tier first; only when that is inconclusive does it resolve both+structure classes and compare them. An unresolvable structure class is *not* an answer to the+compatibility question — it means the library was asked about a concept whose class it does not+hold — so it raises `ConceptStructureClassNotFoundError` rather than returning `False`, which would+be indistinguishable from a genuine "incompatible" verdict.+"""++from __future__ import annotations++import pytest+from kajson.kajson_manager import KajsonManager+from pydantic import Field++from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+from pipelex.core.concepts.exceptions import ConceptStructureClassNotFoundError, ConceptValueError+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.libraries.concept.concept_library import ConceptLibrary+++class UnrelatedRedContent(StructuredContent):+ red: str+++class UnrelatedBlueContent(StructuredContent):+ blue: int+++class NestedImageInfo(StructuredContent):+ """A nested structure that contains image-like data (same structure as ImageContent)."""++ url: str+ public_url: str | None = None+ source_prompt: str | None = None+ source_negative_prompt: str | None = None+ caption: str | None = None+ mime_type: str | None = None+ width: int | None = Field(default=None, gt=0)+ height: int | None = Field(default=None, gt=0)+ filename: str | None = None+++class DocumentWithNestedImage(StructuredContent):+ """A content class that has a nested field containing image info."""++ title: str+ metadata: NestedImageInfo+++def _make_concept(*, code: str, domain_code: str, structure_class_name: str, refines: str | None = None) -> Concept:+ return Concept(+ code=code,+ domain_code=domain_code,+ description="Test concept",+ structure_class_name=structure_class_name,+ refines=refines,+ )+++class TestConceptLibraryCompatibility:+ def test_unregistered_structure_class_raises_instead_of_answering_false(self):+ """Declaration tier inconclusive + classes absent from the registry => loud, not `False`."""+ library = ConceptLibrary.make_empty()+ one = _make_concept(code="Ghost", domain_code="nowhere", structure_class_name="GhostContentThatIsNeverRegistered")+ other = _make_concept(code="Phantom", domain_code="elsewhere", structure_class_name="PhantomContentThatIsNeverRegistered")++ with pytest.raises(ConceptStructureClassNotFoundError):+ library.is_compatible(tested_concept=one, wanted_concept=other)++ def test_the_new_error_is_catchable_as_the_existing_concept_value_error(self):+ """Guards that already catch `ConceptValueError` keep working unmodified."""+ assert issubclass(ConceptStructureClassNotFoundError, ConceptValueError)++ def test_declaration_tier_short_circuits_before_any_class_lookup(self):+ """A declaration-established pair never touches the registry, so unregistered classes are fine."""+ library = ConceptLibrary.make_empty()+ base = _make_concept(code="BaseScore", domain_code="scoring", structure_class_name="NeverRegisteredBaseContent")+ refining = _make_concept(+ code="DetailedScore",+ domain_code="scoring",+ structure_class_name="NeverRegisteredDetailedContent",+ refines="scoring.BaseScore",+ )++ assert library.is_compatible(tested_concept=refining, wanted_concept=base) is True++ def test_registered_but_unrelated_classes_answer_false(self):+ """The class tier still answers `False` — an unregistered class is a different situation."""+ KajsonManager.get_class_registry().register_class(UnrelatedRedContent)+ KajsonManager.get_class_registry().register_class(UnrelatedBlueContent)++ library = ConceptLibrary.make_empty()+ one = _make_concept(code="Red", domain_code="palette", structure_class_name="UnrelatedRedContent")+ other = _make_concept(code="Blue", domain_code="palette", structure_class_name="UnrelatedBlueContent")++ assert library.is_compatible(tested_concept=one, wanted_concept=other) is False++ def test_the_structureless_native_concept_is_answered_not_raised(self):+ """`native.Anything` declares no content class, so there is no structural check to attempt.++ This is the one case where "no class" is a property of the concept rather than a missing+ registration, and it must stay a plain `False` — the loud raise is for names that *should*+ have resolved.+ """+ library = ConceptLibrary.make_empty_with_native_concepts()+ anything = library.get_native_concept(native_concept=NativeConceptCode.ANYTHING)+ text = library.get_native_concept(native_concept=NativeConceptCode.TEXT)++ assert anything.declares_a_structure_class is False+ assert text.declares_a_structure_class is True+ assert library.is_compatible(tested_concept=anything, wanted_concept=text) is False+ assert library.is_compatible(tested_concept=text, wanted_concept=anything) is False++ def test_get_structure_class_raises_on_an_unregistered_name(self):+ library = ConceptLibrary.make_empty()+ concept = _make_concept(code="Ghost", domain_code="nowhere", structure_class_name="GhostContentThatIsNeverRegistered")++ with pytest.raises(ConceptStructureClassNotFoundError):+ library.get_structure_class(concept=concept)++ def test_get_structure_class_returns_the_registered_class(self):+ KajsonManager.get_class_registry().register_class(UnrelatedRedContent)++ library = ConceptLibrary.make_empty()+ concept = _make_concept(code="Red", domain_code="palette", structure_class_name="UnrelatedRedContent")++ assert library.get_structure_class(concept=concept) is UnrelatedRedContent++ def test_get_structure_class_rejects_a_class_that_is_not_stuff_content(self):+ """A registered non-`StuffContent` class is as unusable as a missing one, and says so."""++ class NotAStuffContent:+ pass++ KajsonManager.get_class_registry().register_class(NotAStuffContent)++ library = ConceptLibrary.make_empty()+ concept = _make_concept(code="Bogus", domain_code="palette", structure_class_name="NotAStuffContent")++ with pytest.raises(ConceptStructureClassNotFoundError):+ library.get_structure_class(concept=concept)++ def test_native_concepts_resolve_their_structure_class(self):+ library = ConceptLibrary.make_empty_with_native_concepts()+ text_concept = library.get_native_concept(native_concept=NativeConceptCode.TEXT)++ assert library.get_structure_class(concept=text_concept).__name__ == NativeConceptCode.TEXT.structure_class_name++ def test_end_to_end_compatibility_matrix(self):+ """The composed verdict over concepts built the way the loader builds them."""+ library = ConceptLibrary.make_empty()+ concept_1 = ConceptFactory.make_from_blueprint(+ concept_code="Code1",+ domain_code="domain1",+ blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", refines=NativeConceptCode.TEXT),+ )+ concept_2 = ConceptFactory.make_from_blueprint(+ concept_code="Code2",+ domain_code="domain1",+ blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", refines=NativeConceptCode.TEXT),+ )+ concept_3 = ConceptFactory.make_from_blueprint(+ concept_code="Code3",+ domain_code="domain2",+ blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", structure="TextContent"),+ )+ concept_4 = ConceptFactory.make_from_blueprint(+ concept_code="Code4",+ domain_code="domain1",+ blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum", structure="ImageContent"),+ )+ page_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.PAGE)+ image_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.IMAGE)+ visual_description = ConceptFactory.make_from_blueprint(+ concept_code="VisualDescription",+ domain_code="images",+ blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum"),+ )++ assert library.is_compatible(tested_concept=visual_description, wanted_concept=image_concept, strict=True) is False+ assert library.is_compatible(tested_concept=visual_description, wanted_concept=image_concept, strict=False) is False++ # Both refine native Text: established by the declarations.+ assert library.is_compatible(tested_concept=concept_1, wanted_concept=concept_2) is True+ # Refining Text vs. declaring TextContent outright: the class tier settles it.+ assert library.is_compatible(tested_concept=concept_1, wanted_concept=concept_3) is True+ assert library.is_compatible(tested_concept=concept_1, wanted_concept=concept_4) is False++ # Page carries an ImageContent field: loose yes, strict no.+ assert library.is_compatible(tested_concept=page_concept, wanted_concept=image_concept, strict=False) is True+ assert library.is_compatible(tested_concept=page_concept, wanted_concept=image_concept, strict=True) is False++ def test_concept_refining_text_is_strictly_compatible_with_text(self):+ library = ConceptLibrary.make_empty()+ refining_text = ConceptFactory.make(+ domain_code="test_domain",+ concept_code="MyConceptNotNativeText",+ description="Test concept for unit tests",+ structure_class_name="TextContent",+ refines="native.Text",+ )+ text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)++ assert library.is_compatible(tested_concept=refining_text, wanted_concept=text_concept, strict=True) is True+ assert library.is_compatible(tested_concept=refining_text, wanted_concept=text_concept, strict=False) is True++ def test_structurally_identical_classes_are_compatible(self):+ """Different structure class names, identical JSON structure — the class tier says yes."""+ library = ConceptLibrary.make_empty()+ text_like = ConceptFactory.make_from_blueprint(+ concept_code="MyTextLikeConcept",+ domain_code="test_structure_equiv",+ blueprint_or_string_description=ConceptBlueprint(+ description="A concept with the exact same structure as TextContent",+ structure={+ "text": ConceptStructureBlueprint(+ type=ConceptStructureBlueprintFieldType.TEXT,+ description="The text content",+ required=True,+ ),+ },+ ),+ )+ text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)++ assert text_like.structure_class_name != text_concept.structure_class_name+ assert library.is_compatible(tested_concept=text_like, wanted_concept=text_concept, strict=True) is True+ assert library.is_compatible(tested_concept=text_like, wanted_concept=text_concept, strict=False) is True++ def test_nested_compatible_field_is_loose_only(self):+ """A class that merely *carries* a compatible value satisfies loose mode, never strict."""+ KajsonManager.get_class_registry().register_class(NestedImageInfo)+ KajsonManager.get_class_registry().register_class(DocumentWithNestedImage)++ library = ConceptLibrary.make_empty()+ with_nested_image = ConceptFactory.make(+ domain_code="test_nested",+ concept_code="DocumentWithImage",+ description="A document containing nested image info",+ structure_class_name="DocumentWithNestedImage",+ )+ image_like = ConceptFactory.make(+ domain_code="test_nested",+ concept_code="ImageInfo",+ description="Image-like info",+ structure_class_name="NestedImageInfo",+ )+ native_image = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.IMAGE)++ assert library.is_compatible(tested_concept=with_nested_image, wanted_concept=image_like, strict=True) is False+ assert library.is_compatible(tested_concept=with_nested_image, wanted_concept=image_like, strict=False) is True++ # NestedImageInfo is structurally equivalent to ImageContent.+ assert library.is_compatible(tested_concept=image_like, wanted_concept=native_image, strict=True) is True+ assert library.is_compatible(tested_concept=image_like, wanted_concept=native_image, strict=False) is True++ assert library.is_compatible(tested_concept=with_nested_image, wanted_concept=native_image, strict=True) is False+ assert library.is_compatible(tested_concept=with_nested_image, wanted_concept=native_image, strict=False) is Truediff --git a/tests/unit/pipelex/pipe_machinery/rendering/conftest.py b/tests/unit/pipelex/pipe_machinery/rendering/conftest.pynew file mode 100644index 000000000..d0a459bc1--- /dev/null+++ b/tests/unit/pipelex/pipe_machinery/rendering/conftest.py@@ -0,0 +1,22 @@+from typing import TYPE_CHECKING++import pytest++from pipelex.libraries.concept.concept_library import ConceptLibrary++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++[email protected](autouse=True)+def renderer_concept_library(mocker: "MockerFixture") -> ConceptLibrary:+ """Give the output renderer a real concept library without booting a method.++ The renderer resolves each declared concept's structure class through the loaded method's+ library, and these tests drive it with mock pipes rather than a loaded method. An empty+ `ConceptLibrary` is the honest stand-in: it holds no concepts but resolves any class the+ process registry already has, which is all the rendering needs.+ """+ concept_library = ConceptLibrary.make_empty()+ mocker.patch("pipelex.pipe_machinery.rendering.output_renderer.get_concept_library", return_value=concept_library)+ return concept_librarydiff --git a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_anything_formats.py b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_anything_formats.pyindex d39626955..031e0b953 100644--- a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_anything_formats.py+++ b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_anything_formats.py@@ -5,6 +5,7 @@ import pytestfrom pytest_mock import MockerFixturefrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat+from pipelex.libraries.concept.concept_library import ConceptLibraryfrom pipelex.pipe_machinery.rendering.output_renderer import render_outputGET_REQUIRED_PIPE_TARGET = "pipelex.pipe_machinery.rendering.output_renderer.get_required_pipe"@@ -46,7 +47,7 @@ class TestRenderOutputAnythingFormats:with pytest.raises(ValueError, match=r"native\.Anything"):render_output(anything_pipe, output_format=output_format)- def test_anything_json_renders_output_options(self, mocker: MockerFixture) -> None:+ def test_anything_json_renders_output_options(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""JSON format wraps each possible output under an output_option_N key with concept and content."""condition_pipe = _make_anything_condition_pipe(mocker, "make_summary")mapped_pipe = _make_mapped_pipe(@@ -65,9 +66,11 @@ class TestRenderOutputAnythingFormats:"content": {"text": "summary text"},}}- mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON+ )- def test_anything_python_renders_option_lines(self, mocker: MockerFixture) -> None:+ def test_anything_python_renders_option_lines(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""PYTHON format lists each possible output as a commented option with an output_N assignment."""condition_pipe = _make_anything_condition_pipe(mocker, "make_summary")mapped_pipe = _make_mapped_pipe(@@ -84,9 +87,11 @@ class TestRenderOutputAnythingFormats:assert result_lines[1] == "# The actual output will be one of the following:"assert "# Option 1: test.Summary" in result_linesassert 'output_1 = SummaryContent(text="hello")' in result_lines- mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.PYTHON)+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.PYTHON+ )- def test_anything_schema_renders_schema_options(self, mocker: MockerFixture) -> None:+ def test_anything_schema_renders_schema_options(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""SCHEMA format wraps each possible output under a schema_option_N key with concept and content."""condition_pipe = _make_anything_condition_pipe(mocker, "build_schema")schema_content = {"type": "object", "properties": {"text": {"type": "string"}}}@@ -106,4 +111,6 @@ class TestRenderOutputAnythingFormats:"content": schema_content,}}- mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.SCHEMA)+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.SCHEMA+ )diff --git a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.pyindex 1cd77452d..f97fa36fa 100644--- a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py+++ b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py@@ -5,6 +5,7 @@ from pytest_mock import MockerFixturefrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.concepts.exceptions import ConceptError+from pipelex.libraries.concept.concept_library import ConceptLibraryfrom pipelex.pipe_machinery.rendering.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]GET_REQUIRED_PIPE_TARGET = "pipelex.pipe_machinery.rendering.output_renderer.get_required_pipe"@@ -36,7 +37,7 @@ class TestCollectPossibleOutputsCondition:assert result == []get_pipe_mock.assert_not_called()- def test_single_mapped_pipe_uses_content_key(self, mocker: MockerFixture) -> None:+ def test_single_mapped_pipe_uses_content_key(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""A single mapped pipe yields one entry whose content comes from the rendered dict's 'content' key."""condition_pipe = _make_condition_pipe(mocker, {"make_summary"})mapped_pipe = _make_mapped_pipe(mocker, "test.Summary")@@ -50,7 +51,9 @@ class TestCollectPossibleOutputsCondition:assert result == [{"concept_ref": "test.Summary", "content": {"text": "summary text"}}]get_pipe_mock.assert_called_once_with(pipe_code="make_summary")- mapped_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)+ mapped_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON+ )def test_multiple_mapped_pipes_are_ordered_deterministically(self, mocker: MockerFixture) -> None:"""With several mapped pipes, outputs come back sorted by pipe code regardless of set iteration order."""diff --git a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.pyindex 8353989a7..ebb688730 100644--- a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py+++ b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py@@ -5,6 +5,7 @@ from pytest_mock import MockerFixturefrom pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormatfrom pipelex.core.concepts.exceptions import ConceptError+from pipelex.libraries.concept.concept_library import ConceptLibraryfrom pipelex.pipe_machinery.rendering.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]GET_REQUIRED_PIPE_TARGET = "pipelex.pipe_machinery.rendering.output_renderer.get_required_pipe"@@ -53,7 +54,7 @@ class TestCollectPossibleOutputsSequence:assert result == []get_pipe_mock.assert_not_called()- def test_concrete_last_pipe_yields_single_entry(self, mocker: MockerFixture) -> None:+ def test_concrete_last_pipe_yields_single_entry(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""Only the last sub-pipe is resolved and its rendered output is the single possible output."""sequence_pipe = _make_sequence_pipe(mocker, ["first_step", "final_step"])final_pipe = _make_concrete_pipe(mocker, "test.Final")@@ -67,7 +68,9 @@ class TestCollectPossibleOutputsSequence:assert result == [{"concept_ref": "test.Final", "content": {"text": "final output"}}]get_pipe_mock.assert_called_once_with(pipe_code="final_step")- final_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)+ final_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON+ )@pytest.mark.parametrize("render_error",@@ -88,7 +91,7 @@ class TestCollectPossibleOutputsSequence:assert result == []- def test_anything_last_pipe_recurses_into_it(self, mocker: MockerFixture) -> None:+ def test_anything_last_pipe_recurses_into_it(self, mocker: MockerFixture, renderer_concept_library: ConceptLibrary) -> None:"""When the last pipe itself outputs Anything, collection recurses into it down to the concrete leaf."""outer_pipe = _make_sequence_pipe(mocker, ["step_one", "mid_sequence"])mid_pipe = _make_sequence_pipe(mocker, ["leaf_step"])@@ -111,4 +114,6 @@ class TestCollectPossibleOutputsSequence:assert get_pipe_mock.call_count == 2get_pipe_mock.assert_any_call(pipe_code="mid_sequence")get_pipe_mock.assert_any_call(pipe_code="leaf_step")- leaf_pipe.output.render_stuff_spec.assert_called_once_with(output_format=ConceptRepresentationFormat.JSON)+ leaf_pipe.output.render_stuff_spec.assert_called_once_with(+ concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON+ )diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.pynew file mode 100644index 000000000..c4684ade0--- /dev/null+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py@@ -0,0 +1,59 @@+"""The image analyzer must ask the *library* about compatibility, not the bare `Concept` model.++Cross-package `refines` aliases (``dep->domain.Code``) only resolve when a concept resolver is in+hand, and the library is what holds it. A call site that compares two `Concept` values directly has+no resolver, so an aliased refinement silently fails to resolve there and the analyzer mis-answers+"is this an image?" — at authoring time, with no error to read.++The concept below refines native Image through an alias while carrying a structure class that has+nothing in common with `ImageContent`. That combination is the point: the class tier cannot possibly+establish the relationship, so the verdict is decided by the declaration tier *and only if the+resolver is consulted*.+"""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING, Callable, cast++from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.interpreter_hub import get_concept_library+from pipelex.pipe_operators.shared.image_reference import ImageReferenceKind+from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer++if TYPE_CHECKING:+ from pipelex.libraries.concept.concept_library import ConceptLibrary++_ALIASED_REF = "imgdep->native.Image"+++class TestTemplateImageAnalyzerCrossPackageRefines:+ def test_cross_package_refined_image_is_recognized_as_an_image(self, load_test_library: Callable[[list[Path]], None]) -> None:+ load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])+ library = cast("ConceptLibrary", get_concept_library())+ native_image = library.get_native_concept(native_concept=NativeConceptCode.IMAGE)++ def resolver(concept_ref: str) -> Concept | None:+ return native_image if concept_ref == _ALIASED_REF else None++ library.set_concept_resolver(resolver)+ library.add_new_concept(+ concept=Concept(+ code="AliasedImage",+ domain_code="test_pipes",+ description="An image concept reached through a cross-package alias",+ structure_class_name="TextContent",+ refines=_ALIASED_REF,+ )+ )++ result = TemplateImageAnalyzer.analyze_template_for_images(+ template_source="Describe this image:\n@pic",+ input_specs={"pic": "AliasedImage"},+ domain_code="test_pipes",+ )++ assert len(result) == 1+ assert result[0].variable_path == "pic"+ assert result[0].kind == ImageReferenceKind.DIRECTdiff --git a/wip/concept-purity/README.md b/wip/concept-purity/README.mdnew file mode 100644index 000000000..dd2318ce9--- /dev/null+++ b/wip/concept-purity/README.md@@ -0,0 +1,19 @@+# Concept purity — working docs++Working notes for the `refactor/Concept-purity` track: getting the process-global class-registry reads out of `Concept`, the MTHDS-protocol wire model. **Track complete** — [PR #1072](https://github.com/Pipelex/pipelex/pull/1072) is open against `dev` with CI green and both review bots clean. The repo-root `TODOS.md` tracker was archived here once the PR was finalized.++| doc | what it is |+| --- | --- |+| [`concept-purity-explained.html`](concept-purity-explained.html) | **Start here.** The architecture note for co-developers: TL;DR, before/after diagrams, the five critical diffs, the three bugs closed, and every judgement call with its reasoning. |+| [`concept-purity-tracker.md`](concept-purity-tracker.md) | The as-built tracker, written as the PR reviewer's guide. Phase-by-phase state, the surprises log, and the deliberate non-goals. |+| [`ts-port-handoff.md`](ts-port-handoff.md) | Heads-up for the `pipelex-js` port: invariant `CONCEPT-6` cites the compatibility block this track restructured. Three semantics to port deliberately, two Python-specific things not to. |++## What shipped, in one paragraph++`Concept` reads no registry at all. Compatibility split into a pure declaration tier on the model, a pure class tier in `tools/typing/class_utils.py`, and a composition in `ConceptLibrary.is_compatible` — the one place that owns resolution and therefore the only place that can tell "no class" from "not compatible". `ConceptProviderAbstract.get_structure_class` is the single seam turning a `structure_class_name` string into a type. Three live bugs closed on the way: cross-package `refines` aliases silently failing to resolve at five operator call sites, an unresolvable structure class answering `False` instead of raising, and `native.Anything` being answered for the wrong reason. No wire-format change.++## What is deliberately left++- **The scoping half.** Class resolution still goes through the async context's registry rather than one the provider carries. Unreachable divergence today; the mechanism, the four trip-wires, and the shape of the fix are in [`../inputs/provider-scoped-class-resolution.md`](../inputs/provider-scoped-class-resolution.md).+- **The materialization write side stays ambient.** `concept_factory` and `structure_generation/generator.py` register generated classes at library-load time — genuinely the registry's business. Pinned as a golden set by `tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py`.+- **Two run-path `except` arms deliberately not added**, and one dead one removed. Reasoning in [`../inputs/unresolvable-structure-class-escapes-the-validate-sweep.md`](../inputs/unresolvable-structure-class-escapes-the-validate-sweep.md).diff --git a/wip/concept-purity/concept-purity-explained.html b/wip/concept-purity/concept-purity-explained.htmlnew file mode 100644index 000000000..d32e0a131--- /dev/null+++ b/wip/concept-purity/concept-purity-explained.html@@ -0,0 +1,705 @@+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>Concept purity</title>+<style>+ :root{+ --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;+ --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;+ --rule:#dfe3e7; --rule-2:#cbd2d8;+ --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;+ --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;+ --stop:#b3261e; --stop-soft:#fbeae8;+ --code-bg:#f1f4f6; --code-fg:#1a2027;+ --add-bg:#e3f1e9; --del-bg:#fbeae8;+ --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);+ --serif:"Iowan Old Style","Charter","Bitstream Charter","Sitka Text",Cambria,Georgia,serif;+ --sans:ui-sans-serif,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;+ --mono:ui-monospace,"SF Mono",SFMono-Regular,"JetBrains Mono","Cascadia Mono",Menlo,Consolas,monospace;+ --measure:68ch;+ }+ @media (prefers-color-scheme: dark){+ :root{+ --paper:#0f1216; --card:#161b21; --sunk:#12171c;+ --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;+ --rule:#252d35; --rule-2:#333d47;+ --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;+ --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;+ --stop:#f5a3a0; --stop-soft:#301a1a;+ --code-bg:#0c1015; --code-fg:#dde3e9;+ --add-bg:#0f2a1d; --del-bg:#301a1a;+ --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);+ }+ }+ :root[data-theme="light"]{+ --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;+ --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;+ --rule:#dfe3e7; --rule-2:#cbd2d8;+ --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;+ --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;+ --stop:#b3261e; --stop-soft:#fbeae8;+ --code-bg:#f1f4f6; --code-fg:#1a2027;+ --add-bg:#e3f1e9; --del-bg:#fbeae8;+ --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);+ }+ :root[data-theme="dark"]{+ --paper:#0f1216; --card:#161b21; --sunk:#12171c;+ --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;+ --rule:#252d35; --rule-2:#333d47;+ --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;+ --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;+ --stop:#f5a3a0; --stop-soft:#301a1a;+ --code-bg:#0c1015; --code-fg:#dde3e9;+ --add-bg:#0f2a1d; --del-bg:#301a1a;+ --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);+ }++ *{box-sizing:border-box}+ body{+ margin:0; background:var(--paper); color:var(--ink); font-family:var(--sans);+ font-size:16.5px; line-height:1.68; -webkit-font-smoothing:antialiased;+ }+ .frame{max-width:1040px; margin:0 auto; padding:0 1.25rem 6rem}+ p,ul,ol,figcaption,.note,.tldr,blockquote{max-width:var(--measure)}++ a{color:inherit; text-decoration:underline; text-decoration-thickness:1px;+ text-decoration-color:var(--rule-2); text-underline-offset:3px}+ a:hover{text-decoration-color:currentColor}+ a:focus-visible,summary:focus-visible,input:focus-visible + label{outline:2px solid var(--rt-line); outline-offset:2px; border-radius:3px}+ @media (prefers-reduced-motion: reduce){*{animation:none !important; transition:none !important; scroll-behavior:auto !important}}++ .masthead{padding:3.2rem 0 1.6rem; border-bottom:1px solid var(--rule)}+ .eyebrow{font-family:var(--mono); font-size:.74rem; letter-spacing:.14em; text-transform:uppercase; color:var(--ink-3); margin:0 0 .9rem}+ h1{font-family:var(--serif); font-weight:600; letter-spacing:-.02em; text-wrap:balance;+ font-size:clamp(2.15rem,1.55rem + 2.2vw,3rem); line-height:1.1; margin:0 0 .6rem}+ h1 .mono{font-family:var(--mono); font-size:.82em; font-weight:500; letter-spacing:-.01em}+ .deck{font-size:1.12rem; color:var(--ink-2); margin:0 0 1.6rem; max-width:60ch; text-wrap:pretty}+ .deck b{color:var(--ink); font-weight:600}+ .meta{display:flex; flex-wrap:wrap; gap:.4rem; list-style:none; margin:0; padding:0; max-width:none}+ .meta li{font-family:var(--mono); font-size:.74rem; letter-spacing:.01em; color:var(--ink-2);+ border:1px solid var(--rule); background:var(--card); border-radius:2px; padding:.24rem .55rem}+ .meta li b{color:var(--ink); font-weight:600}+ .meta li.live{border-color:var(--rt); color:var(--rt)}++ .rail{position:sticky; top:0; z-index:9; display:flex; gap:.15rem; overflow-x:auto; scrollbar-width:none;+ padding:.5rem 0; margin:0 0 .4rem; border-bottom:1px solid var(--rule);+ background:color-mix(in srgb, var(--paper) 88%, transparent); backdrop-filter:blur(8px)}+ .rail::-webkit-scrollbar{display:none}+ .rail a{font-family:var(--mono); font-size:.72rem; letter-spacing:.04em; text-transform:uppercase;+ color:var(--ink-3); text-decoration:none; white-space:nowrap; padding:.28rem .5rem; border-radius:3px}+ .rail a:hover{color:var(--ink); background:var(--sunk)}++ h2{font-family:var(--serif); font-weight:600; font-size:1.6rem; letter-spacing:-.015em; text-wrap:balance;+ margin:3.4rem 0 1rem; scroll-margin-top:4rem; display:flex; align-items:baseline; gap:.7rem}+ h2 .n{font-family:var(--mono); font-size:.72rem; font-weight:500; letter-spacing:.1em; color:var(--rt);+ border:1px solid var(--rule); border-radius:2px; padding:.1rem .38rem; flex:none; position:relative; top:-.25em}+ h3{font-size:1.02rem; font-weight:650; margin:2rem 0 .4rem; letter-spacing:-.005em}+ h4{font-family:var(--mono); font-size:.74rem; font-weight:500; letter-spacing:.12em; text-transform:uppercase;+ color:var(--ink-3); margin:1.6rem 0 .3rem}+ p{margin:.75rem 0} ul,ol{margin:.75rem 0; padding-left:1.15rem} li{margin:.32rem 0}++ code,kbd{font-family:var(--mono); font-size:.86em}+ :is(p,li,td,th,summary,figcaption,.deck) code{background:var(--code-bg); padding:.08em .32em; border-radius:3px; white-space:nowrap}++ .tldr{margin:2.2rem 0; padding:1.3rem 1.5rem 1.4rem; background:var(--card);+ border:1px solid var(--rule); border-top:2px solid var(--ink); border-radius:3px; box-shadow:var(--shadow)}+ .tldr h2{font-family:var(--mono); font-size:.78rem; font-weight:600; letter-spacing:.16em; text-transform:uppercase;+ color:var(--ink-3); margin:0 0 .7rem; display:block}+ .tldr ul{margin:0; padding-left:1.05rem; max-width:none}+ .tldr li{margin:.5rem 0}+ .tldr li::marker{color:var(--rule-2)}++ .stats{display:grid; grid-template-columns:repeat(auto-fit,minmax(158px,1fr)); gap:.6rem; margin:1.6rem 0}+ .stat{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem .9rem .8rem}+ .stat .n{display:block; font-family:var(--mono); font-variant-numeric:tabular-nums; font-size:1.4rem;+ font-weight:600; letter-spacing:-.03em; line-height:1.2}+ .stat .n s{color:var(--ink-3); font-weight:400; font-size:.62em; text-decoration-color:var(--rule-2)}+ .stat .n em{font-style:normal; color:var(--rt)}+ .stat .l{display:block; font-size:.78rem; line-height:1.4; color:var(--ink-2); margin-top:.25rem}++ figure{margin:1.8rem 0; padding:1.1rem 1.1rem .75rem; background:var(--card);+ border:1px solid var(--rule); border-radius:3px; box-shadow:var(--shadow)}+ figure svg{display:block; width:100%; height:auto}+ figcaption{font-size:.83rem; line-height:1.55; color:var(--ink-2); margin-top:.7rem; padding-top:.7rem; border-top:1px solid var(--rule)}++ .s-box{fill:var(--card); stroke:var(--rule-2)}+ .s-rt{fill:var(--rt-soft); stroke:var(--rt-line)}+ .s-it{fill:var(--it-soft); stroke:var(--it-line)}+ .s-bad{fill:var(--stop-soft); stroke:var(--stop)}+ .s-t{fill:var(--ink); font:600 13px var(--sans)}+ .s-ts{fill:var(--ink-2); font:400 11.5px var(--mono)}+ .s-tm{fill:var(--ink-2); font:400 11.5px var(--sans)}+ .s-trt{fill:var(--rt); font:600 10.5px var(--mono); letter-spacing:.1em}+ .s-tit{fill:var(--it); font:600 10.5px var(--mono); letter-spacing:.1em}+ .s-tbad{fill:var(--stop); font:600 11.5px var(--sans)}+ .s-tok{fill:var(--rt); font:600 12px var(--sans)}+ .s-line{stroke:var(--rule-2); fill:none}+ .s-badline{stroke:var(--stop); fill:none}+ .s-okline{stroke:var(--rt-line); fill:none}++ .scroll{overflow-x:auto; margin:1.2rem 0; border:1px solid var(--rule); border-radius:3px; background:var(--card)}+ table{border-collapse:collapse; width:100%; font-size:.89rem; font-variant-numeric:tabular-nums}+ th,td{padding:.55rem .7rem; text-align:left; vertical-align:top; border-bottom:1px solid var(--rule)}+ th{font-family:var(--mono); font-size:.72rem; font-weight:600; letter-spacing:.08em; text-transform:uppercase;+ color:var(--ink-3); background:var(--sunk); white-space:nowrap}+ tbody tr:last-child td{border-bottom:0}++ pre{background:var(--code-bg); color:var(--code-fg); border:1px solid var(--rule); border-radius:3px;+ padding:.9rem 1rem; overflow-x:auto; font-size:.8rem; line-height:1.6; margin:1rem 0}+ pre code{font-family:var(--mono)}+ .diff .del{display:block; margin:0 -1rem; padding:0 1rem; background:var(--del-bg); color:var(--stop)}+ .diff .add{display:block; margin:0 -1rem; padding:0 1rem; background:var(--add-bg); color:var(--rt)}+ .diff .hdr{display:block; color:var(--ink-3)}+ .cmt{color:var(--ink-3)}++ .tabs{display:flex; flex-wrap:wrap; gap:.3rem; margin:1.3rem 0}+ .tabs input{position:absolute; width:1px; height:1px; opacity:0; clip-path:inset(50%)}+ .tabs label{cursor:pointer; font-family:var(--mono); font-size:.74rem; letter-spacing:.02em;+ border:1px solid var(--rule); background:var(--card); color:var(--ink-2);+ border-radius:2px; padding:.3rem .6rem; user-select:none}+ .tabs label:hover{color:var(--ink); border-color:var(--rule-2)}+ .tabs .panels{flex:1 0 100%; margin-top:.35rem}+ .tabs .panel{display:none}+ .tabs .panel > :first-child{margin-top:0}+ #d1:checked ~ label[for="d1"],#d2:checked ~ label[for="d2"],#d3:checked ~ label[for="d3"],+ #d4:checked ~ label[for="d4"],#d5:checked ~ label[for="d5"]+ {background:var(--ink); color:var(--paper); border-color:var(--ink)}+ #d1:focus-visible ~ label[for="d1"],#d2:focus-visible ~ label[for="d2"],#d3:focus-visible ~ label[for="d3"],+ #d4:focus-visible ~ label[for="d4"],#d5:focus-visible ~ label[for="d5"]+ {outline:2px solid var(--rt-line); outline-offset:2px}+ #d1:checked ~ .panels > .panel:nth-child(1),+ #d2:checked ~ .panels > .panel:nth-child(2),+ #d3:checked ~ .panels > .panel:nth-child(3),+ #d4:checked ~ .panels > .panel:nth-child(4),+ #d5:checked ~ .panels > .panel:nth-child(5){display:block}++ details{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem 1rem; margin:1.2rem 0}+ details[open]{padding-bottom:1rem}+ summary{cursor:pointer; font-weight:600; font-size:.92rem}+ summary::marker{color:var(--rule-2)}+ details > :nth-child(2){margin-top:.85rem}++ .note{border-left:2px solid var(--rule-2); padding:.1rem 0 .1rem .95rem; color:var(--ink-2); font-size:.93rem; margin:1.1rem 0}+ .note.stop{border-left-color:var(--stop)}+ .note.go{border-left-color:var(--rt-line)}++ .cards{display:grid; grid-template-columns:repeat(auto-fit,minmax(255px,1fr)); gap:.7rem; margin:1.4rem 0}+ .cards .card{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.9rem 1rem}+ .cards h3{margin:0 0 .3rem; font-size:.95rem}+ .cards p{margin:.3rem 0; font-size:.88rem; color:var(--ink-2); max-width:none}+ .cards p strong{color:var(--ink)}++ .legend{display:flex; flex-wrap:wrap; gap:1rem; margin:1.4rem 0 0; font-family:var(--mono); font-size:.74rem; color:var(--ink-2)}+ .legend span{display:flex; align-items:center; gap:.4rem}+ .legend i{width:10px; height:10px; border-radius:2px; display:block}+ .legend .k-rt{background:var(--rt-line)} .legend .k-it{background:var(--it-line)} .legend .k-stop{background:var(--stop)}++ footer{margin-top:3.5rem; padding-top:1.2rem; border-top:1px solid var(--rule); color:var(--ink-3); font-size:.83rem}+ footer p{max-width:none}+</style>++<div class="frame">++<header class="masthead">+ <p class="eyebrow">Pipelex · refactor/Concept-purity · architecture note</p>+ <h1>Getting the class registry out of <span class="mono">Concept</span></h1>+ <p class="deck">A protocol-owned wire model was answering behavioural questions by reaching into a process global. Pulling that out split compatibility into two tiers and <b>fixed three live bugs</b> on the way.</p>+ <ul class="meta">+ <li><b>PR</b> <a href="https://github.com/Pipelex/pipelex/pull/1072">#1072</a> → <code>dev</code></li>+ <li><b>7</b> commits</li>+ <li><b>52</b> files · +1312 / −1326</li>+ <li class="live">no wire-format change</li>+ </ul>+</header>++<nav class="rail" aria-label="Sections">+ <a href="#problem">Problem</a>+ <a href="#shape">New shape</a>+ <a href="#api">API changes</a>+ <a href="#diffs">Diffs</a>+ <a href="#bugs">Bugs fixed</a>+ <a href="#calls">Judgement calls</a>+ <a href="#notdone">Not done</a>+ <a href="#reviews">Review log</a>+ <a href="#links">Links</a>+</nav>++<section class="tldr">+ <h2>TL;DR</h2>+ <ul>+ <li><code>Concept</code> subclasses the MTHDS-protocol wire model <code>ConceptAbstract</code> — pure serialisable data — but four of its methods read the <b>process-global class registry</b>. It could not answer a question about itself without a Pipelex runtime booted around it, and every caller holding a <code>Concept</code> inherited that dependency invisibly.</li>+ <li><b>Compatibility is now two tiers.</b> A <i>declaration tier</i> on <code>Concept</code>, pure over the model's own fields. A <i>class tier</i> in <code>tools/typing/</code>, pure over two already-resolved classes. <code>ConceptLibrary.is_compatible</code> composes them — declaration first, classes only if that's inconclusive.</li>+ <li><b>Class lookup moved to the provider.</b> <code>ConceptProviderAbstract.get_structure_class(concept)</code> is now the single seam that turns a <code>structure_class_name</code> string into a type.</li>+ <li><b>Three live bugs closed:</b> cross-package <code>refines</code> aliases silently failed to resolve at five call sites; an unresolvable structure class answered <code>False</code> instead of failing; <code>native.Anything</code> was answered for the wrong reason.</li>+ <li><b>What to watch out for when you touch this:</b> a core data-model function that needs a concept — or its class — takes a <code>concept_provider</code> parameter. Don't import a hub, and don't reach for <code>get_class_registry()</code>. A golden-set test fails the build if a new module under <code>core/concepts/</code> does.</li>+ </ul>+</section>++<h2 id="problem"><span class="n">01</span> The problem</h2>++<p><code>Concept</code> carries five fields and nothing else: <code>code</code>, <code>domain_code</code>, <code>description</code>, <code>structure_class_name: str</code>, <code>refines</code>. The MTHDS standard owns that shape. Yet four of its members answered questions that needed a <i>type</i>, not a name — so they called <code>get_class_registry()</code> and looked the name up in a process global.</p>++<figure>+<svg viewBox="0 0 940 250" role="img" aria-label="Before: five call sites and the library both funnel into Concept, which reads the global class registry">+ <rect class="s-box" x="8" y="30" width="196" height="88" rx="3"/>+ <text class="s-t" x="24" y="56">5 operator call sites</text>+ <text class="s-ts" x="24" y="76">pipe_llm ×2</text>+ <text class="s-ts" x="24" y="92">template_image_analyzer ×2</text>+ <text class="s-ts" x="24" y="108">template_document_analyzer</text>++ <rect class="s-it" x="8" y="146" width="196" height="56" rx="3"/>+ <text class="s-tit" x="24" y="167">INTERPRETER</text>+ <text class="s-t" x="24" y="188">ConceptLibrary.is_compatible</text>++ <rect class="s-bad" x="300" y="70" width="238" height="108" rx="3"/>+ <text class="s-tbad" x="318" y="94">Concept (wire model)</text>+ <text class="s-ts" x="318" y="116">are_concept_compatible</text>+ <text class="s-ts" x="318" y="132">get_structure_class</text>+ <text class="s-ts" x="318" y="148">is_valid_structure_class</text>+ <text class="s-ts" x="318" y="164">search_for_nested_image_fields…</text>++ <rect class="s-bad" x="678" y="88" width="248" height="72" rx="3"/>+ <text class="s-tbad" x="696" y="112">process-global class registry</text>+ <text class="s-ts" x="696" y="132">get_class_registry()</text>+ <text class="s-ts" x="696" y="148">scoped by ContextVar</text>++ <path class="s-badline" d="M204 74 L296 110" stroke-width="1.5" marker-end="url(#ah-bad)"/>+ <path class="s-line" d="M204 172 L296 140" stroke-width="1.5" marker-end="url(#ah)"/>+ <path class="s-badline" d="M538 124 L672 124" stroke-width="1.5" marker-end="url(#ah-bad)"/>++ <text class="s-tbad" x="212" y="46">no resolver</text>+ <text class="s-tbad" x="556" y="116">ambient</text>++ <defs>+ <marker id="ah" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="7" markerHeight="7" orient="auto">+ <path d="M0 0 L8 4 L0 8 z" fill="var(--rule-2)"/>+ </marker>+ <marker id="ah-bad" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="7" markerHeight="7" orient="auto">+ <path d="M0 0 L8 4 L0 8 z" fill="var(--stop)"/>+ </marker>+ </defs>+</svg>+<figcaption>Before. The library passed a <code>concept_resolver</code> down; the five operator sites called <code>Concept.are_concept_compatible</code> directly and passed nothing — so a cross-package <code>refines</code> alias could not resolve there. Both paths bottomed out in the same global read.</figcaption>+</figure>++<p>Three consequences, in increasing order of how much they cost us:</p>++<div class="cards">+ <div class="card">+ <h3>Layer inversion</h3>+ <p>A standard-owned wire model depended on a Pipelex process global. <code>core/</code> is supposed to state its dependencies as parameters — that's the doctrine the hub split established.</p>+ </div>+ <div class="card">+ <h3>Untestable</h3>+ <p>Asking two concepts whether they were compatible required a booted runtime with the right classes registered. The compatibility matrix could not be tested with plain classes.</p>+ </div>+ <div class="card">+ <h3>Wrong answers</h3>+ <p>The one that actually bit. Two verdict bugs and a silent resolver bypass, all invisible because <code>False</code> was a legal-looking answer. See <a href="#bugs">§05</a>.</p>+ </div>+</div>++<h2 id="shape"><span class="n">02</span> The new shape</h2>++<p>The insight is that "are these two concepts compatible?" was always two questions wearing one coat. One is about <b>declarations</b> — what the author wrote — and is pure string work over the model's own fields. The other is about <b>classes</b> and needs types. Only the second needs a registry, and resolving a name into a type is a library's job.</p>++<figure>+<svg viewBox="0 0 940 300" role="img" aria-label="After: declaration tier is pure, class tier is pure, the library composes them and owns resolution">+ <rect class="s-it" x="8" y="118" width="212" height="72" rx="3"/>+ <text class="s-tit" x="24" y="142">INTERPRETER</text>+ <text class="s-t" x="24" y="163">ConceptLibrary</text>+ <text class="s-ts" x="24" y="180">.is_compatible</text>++ <rect class="s-rt" x="322" y="24" width="286" height="96" rx="3"/>+ <text class="s-trt" x="340" y="48">TIER 1 · PURE</text>+ <text class="s-t" x="340" y="70">Concept.are_compatible_by_declaration</text>+ <text class="s-ts" x="340" y="90">refs · class names · refines chains</text>+ <text class="s-ts" x="340" y="106">+ injected concept_resolver</text>++ <rect class="s-rt" x="322" y="186" width="286" height="90" rx="3"/>+ <text class="s-trt" x="340" y="210">TIER 2 · PURE</text>+ <text class="s-t" x="340" y="232">are_structure_classes_compatible</text>+ <text class="s-ts" x="340" y="252">equivalence → subclass → field</text>+ <text class="s-ts" x="340" y="268">takes types, never names</text>++ <rect class="s-it" x="686" y="118" width="242" height="72" rx="3"/>+ <text class="s-tit" x="704" y="142">RESOLUTION · ONE SEAM</text>+ <text class="s-t" x="704" y="163">provider.get_structure_class</text>+ <text class="s-ts" x="704" y="180">raises if the name is unusable</text>++ <path class="s-okline" d="M220 140 L316 82" stroke-width="1.5" marker-end="url(#ah2-ok)"/>+ <text class="s-tok" x="228" y="104">first</text>++ <path class="s-line" d="M220 172 L316 226" stroke-width="1.5" marker-end="url(#ah2)"/>+ <text class="s-tm" x="228" y="212">only if inconclusive</text>++ <path class="s-line" d="M608 226 L760 196" stroke-width="1.5" marker-end="url(#ah2)"/>+ <text class="s-tm" x="626" y="216">needs 2 classes</text>++ <path class="s-line" d="M608 72 L806 72 L806 112" stroke-width="1.5" stroke-dasharray="3 3" marker-end="url(#ah2)"/>+ <text class="s-tm" x="618" y="62">never touches it</text>++ <defs>+ <marker id="ah2" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="7" markerHeight="7" orient="auto">+ <path d="M0 0 L8 4 L0 8 z" fill="var(--rule-2)"/>+ </marker>+ <marker id="ah2-ok" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="7" markerHeight="7" orient="auto">+ <path d="M0 0 L8 4 L0 8 z" fill="var(--rt-line)"/>+ </marker>+ </defs>+</svg>+<figcaption>After. The library asks tier 1 first; when the declarations settle it, <b>no class is ever looked up</b> — so concepts whose structure classes were never materialised still get an answer. Tier 2 runs only when tier 1 is silent, and it needs both classes, which is why an unusable name raises there instead of answering.</figcaption>+</figure>++<div class="legend">+ <span><i class="k-rt"></i> pure · no registry, no ambient state</span>+ <span><i class="k-it"></i> owns resolution</span>+ <span><i class="k-stop"></i> the coupling we removed</span>+</div>++<h3>The asymmetry is deliberate, and it matters</h3>++<p>At the declaration tier, <code>True</code> means "established by the declarations". <code>False</code> means "<b>not established at this tier</b>" — it does <i>not</i> mean incompatible. Two concepts whose declarations say nothing about each other may still be compatible through their classes. Reading tier 1's <code>False</code> as a verdict is the mistake the old single-method design made structurally easy; the docstrings now say so explicitly.</p>++<h2 id="api"><span class="n">03</span> What changed on the surface</h2>++<div class="scroll">+<table>+ <thead><tr><th>Was, on <code>Concept</code></th><th>Is now</th><th>Why it moved</th></tr></thead>+ <tbody>+ <tr>+ <td><code>are_concept_compatible(…, strict=)</code></td>+ <td><code>are_compatible_by_declaration(…)</code> + <code>are_structure_classes_compatible(…)</code>, composed by <code>ConceptLibrary.is_compatible</code></td>+ <td>Two questions, one method. <code>strict</code> only ever meant anything to the class half.</td>+ </tr>+ <tr>+ <td><code>get_structure_class()</code></td>+ <td><code>ConceptProviderAbstract.get_structure_class(concept=…)</code></td>+ <td>A name → type lookup is a registry read. The model carries the name; the provider knows the registry.</td>+ </tr>+ <tr>+ <td><code>is_valid_structure_class(name)</code></td>+ <td>a private module-level helper in <code>concept_factory.py</code></td>+ <td>Its only three callers were already there. Materialisation-time only — it asks about a class, not a concept.</td>+ </tr>+ <tr>+ <td><code>search_for_nested_image_fields_in_structure_class()</code></td>+ <td><code>search_for_nested_image_fields(content_class=provider.get_structure_class(…))</code></td>+ <td>Composition of two things that already existed. The method was just a resolve-then-call.</td>+ </tr>+ <tr>+ <td><code>render_concept_representation(…)</code></td>+ <td>same, but takes the already-resolved <code>structure_class</code></td>+ <td>Rendering still labels with <code>self.concept_ref</code>; the class comes in from the caller.</td>+ </tr>+ </tbody>+</table>+</div>++<p>Three render-chain helpers gained a <code>concept_provider</code> parameter and resolve once: <code>StuffSpec.render_stuff_spec</code>, <code>InputStuffSpecs.build_inputs_template</code>, <code>render_inputs</code>. Interpreter-layer callers (<code>output_renderer</code>, <code>input_renderer</code>, <code>pipe_io_contracts</code>, <code>builder/runner_code</code>) supply <code>get_concept_library()</code>.</p>++<div class="note go"><b>Nothing serialised changed shape.</b> <code>structure_class_name</code> stays a plain <code>str</code> protocol field. No <code>mthds</code> schema edit, no wire migration, no version skew.</div>++<h2 id="diffs"><span class="n">04</span> The critical diffs</h2>++<p>Five changes carry the whole refactor. Everything else is call-site plumbing.</p>++<div class="tabs">+ <input type="radio" name="d" id="d1" checked>+ <label for="d1">1 · tier split</label>+ <input type="radio" name="d" id="d2">+ <label for="d2">2 · class tier</label>+ <input type="radio" name="d" id="d3">+ <label for="d3">3 · composition</label>+ <input type="radio" name="d" id="d4">+ <label for="d4">4 · the seam</label>+ <input type="radio" name="d" id="d5">+ <label for="d5">5 · a bypass site</label>++ <div class="panels">+ <div class="panel">+ <h4>pipelex/core/concepts/concept.py</h4>+ <p>The class-tier block leaves the model, and with it the registry import. The rename is the point: the method no longer claims to answer the whole question.</p>+<pre class="diff"><code><span class="del">-from pipelex.core.stuffs.image_field_search import search_for_nested_image_fields</span>+<span class="del">-from pipelex.system.registries.class_registry_access import get_class_registry</span>+<span class="del">-from pipelex.tools.typing.class_utils import are_classes_equivalent, has_compatible_field</span>++ @classmethod+<span class="del">- def are_concept_compatible(</span>+<span class="add">+ def are_compatible_by_declaration(</span>+ cls, *, concept_1: "Concept", concept_2: "Concept",+<span class="del">- strict: bool = False,</span>+ concept_resolver: Callable[[str], "Concept | None"] | None = None,+ ) -> bool:+ <span class="cmt"># … dynamic short-circuits, ref equality, class-name equality,</span>+ <span class="cmt"># … refines chains + cross-package alias resolution — all unchanged</span>++<span class="del">- # Check class-based compatibility</span>+<span class="del">- concept_1_class = get_class_registry().get_class(name=concept_1.structure_class_name)</span>+<span class="del">- concept_2_class = get_class_registry().get_class(name=concept_2.structure_class_name)</span>+<span class="del">- if concept_1_class is None or concept_2_class is None:</span>+<span class="del">- return False # <-- "unknown" indistinguishable from "no"</span>+<span class="del">- if are_classes_equivalent(concept_1_class, class_2=concept_2_class):</span>+<span class="del">- return True</span>+<span class="del">- if strict:</span>+<span class="del">- return False</span>+<span class="del">- # … subclass + nested-field checks</span>+<span class="add">+ return False # not established *at this tier* — see docstring</span>+</code></pre>+ <p>A new declared property replaces an inference the old code got wrong:</p>+<pre class="diff"><code><span class="add">+ @property</span>+<span class="add">+ def declares_a_structure_class(self) -> bool:</span>+<span class="add">+ """True for every concept but `native.Anything`, whose content class</span>+<span class="add">+ deliberately does not exist — so the name derived mechanically from its</span>+<span class="add">+ code never resolves, and asking a provider for it is a category error</span>+<span class="add">+ rather than a missing registration."""</span>+<span class="add">+ if not SpecialDomain.is_native(domain_code=self.domain_code):</span>+<span class="add">+ return True</span>+<span class="add">+ return not NativeConceptCode.is_structureless_concept(self.code)</span>+</code></pre>+ </div>++ <div class="panel">+ <h4>pipelex/tools/typing/class_utils.py</h4>+ <p>The class tier lands next to the two helpers it already used. It takes <i>types</i>, never names — which is what makes it testable with two throwaway classes and no boot.</p>+<pre class="diff"><code><span class="add">+def are_structure_classes_compatible(*, class_1: type[Any], class_2: type[Any], strict: bool) -> bool:</span>+<span class="add">+ """Whether `class_1` can stand in for `class_2`, structurally.</span>+<span class="add">+</span>+<span class="add">+ Structural equivalence always suffices. Beyond that, `strict` decides how much slack:</span>+<span class="add">+ strict accepts equivalence only, loose also accepts a subclass relationship (a refined</span>+<span class="add">+ concept's generated class inherits from the refined one's) and a class that merely</span>+<span class="add">+ *carries* a compatible value in a field — the "nested" case a template needs when it</span>+<span class="add">+ pulls an image out of a document.</span>+<span class="add">+</span>+<span class="add">+ Pure over the two classes: it takes resolved types, never names, and reads no registry.</span>+<span class="add">+ """</span>+<span class="add">+ if are_classes_equivalent(class_1, class_2=class_2):</span>+<span class="add">+ return True</span>+<span class="add">+ if strict:</span>+<span class="add">+ return False</span>+<span class="add">+ try:</span>+<span class="add">+ if issubclass(class_1, class_2):</span>+<span class="add">+ return True</span>+<span class="add">+ except TypeError:</span>+<span class="add">+ pass # not both classes; fall through to field checks</span>+<span class="add">+ return has_compatible_field(class_1, target_type=class_2)</span>+</code></pre>+ </div>++ <div class="panel">+ <h4>pipelex/libraries/concept/concept_library.py</h4>+ <p>The composition. Read the ordering carefully — it's where the "still answers for unmaterialised classes" property comes from.</p>+<pre class="diff"><code> @override+ def is_compatible(self, *, tested_concept, wanted_concept, strict: bool = False) -> bool:+<span class="del">- return Concept.are_concept_compatible(</span>+<span class="del">- concept_1=tested_concept, concept_2=wanted_concept,</span>+<span class="del">- strict=strict, concept_resolver=self._concept_resolver,</span>+<span class="del">- )</span>+<span class="add">+ if Concept.are_compatible_by_declaration(</span>+<span class="add">+ concept_1=tested_concept,</span>+<span class="add">+ concept_2=wanted_concept,</span>+<span class="add">+ concept_resolver=self._concept_resolver,</span>+<span class="add">+ ):</span>+<span class="add">+ return True</span>+<span class="add">+</span>+<span class="add">+ if not (tested_concept.declares_a_structure_class and wanted_concept.declares_a_structure_class):</span>+<span class="add">+ # `native.Anything` has no structure class, so there is no structural</span>+<span class="add">+ # comparison left to make: tier 1's silence is the whole answer.</span>+<span class="add">+ return False</span>+<span class="add">+</span>+<span class="add">+ return are_structure_classes_compatible(</span>+<span class="add">+ class_1=self.get_structure_class(concept=tested_concept),</span>+<span class="add">+ class_2=self.get_structure_class(concept=wanted_concept),</span>+<span class="add">+ strict=strict,</span>+<span class="add">+ )</span>+</code></pre>+ </div>++ <div class="panel">+ <h4>pipelex/libraries/concept/concept_library.py — the resolution seam</h4>+ <p>One implementation of "name → <code>StuffContent</code> subclass, or a typed error", for the whole tree. Note the <code>StuffContent</code> bound: the old path used an unbounded <code>get_class</code>, so a name registered as something else could reach <code>issubclass</code> and answer <code>True</code>.</p>+<pre class="diff"><code><span class="add">+ @override</span>+<span class="add">+ def get_structure_class(self, *, concept: Concept) -> type[StuffContent]:</span>+<span class="add">+ try:</span>+<span class="add">+ structure_class = get_class_registry().get_required_subclass(</span>+<span class="add">+ name=concept.structure_class_name, base_class=StuffContent</span>+<span class="add">+ )</span>+<span class="add">+ except (ClassRegistryNotFoundError, ClassRegistryInheritanceError) as exc:</span>+<span class="add">+ msg = (</span>+<span class="add">+ f"Concept '{concept.concept_ref}' declares structure class "</span>+<span class="add">+ f"'{concept.structure_class_name}', which is not a registered "</span>+<span class="add">+ f"subclass of StuffContent: {exc}"</span>+<span class="add">+ )</span>+<span class="add">+ raise ConceptStructureClassNotFoundError(msg) from exc</span>+<span class="add">+ return cast("type[StuffContent]", structure_class)</span>+</code></pre>+ <div class="note">The error is a <code>ConceptValueError</code> subclass, so every guard that already converted that at its own boundary keeps working untouched — which is why this landed without a sweep of <code>except</code> clauses.</div>+ </div>++ <div class="panel">+ <h4>pipelex/pipe_operators/shared/template_image_analyzer.py</h4>+ <p>Representative of all five bypass sites. Routing through the library is what makes the injected <code>concept_resolver</code> reach the comparison — this is bug #1 in <a href="#bugs">§05</a>, and the fix is a one-line swap per site.</p>+<pre class="diff"><code><span class="del">- is_image = Concept.are_concept_compatible(</span>+<span class="del">- concept_1=root_concept,</span>+<span class="del">- concept_2=native_image_concept,</span>+<span class="add">+ is_image = get_concept_library().is_compatible(</span>+<span class="add">+ tested_concept=root_concept,</span>+<span class="add">+ wanted_concept=native_image_concept,</span>+ strict=True,+ )++<span class="del">- nested_paths = root_concept.search_for_nested_image_fields_in_structure_class()</span>+<span class="add">+ nested_paths = search_for_nested_image_fields(</span>+<span class="add">+ content_class=get_concept_library().get_structure_class(concept=root_concept)</span>+<span class="add">+ )</span>+</code></pre>+ <p>The other four: <code>pipe_llm.py</code> ×2 (<code>strict=True</code>), <code>template_image_analyzer.py</code>'s nested check (<code>strict=False</code>), <code>template_document_analyzer.py</code> (<code>strict=True</code>). Direction and strictness were preserved at all five.</p>+ </div>+ </div>+</div>++<h2 id="bugs"><span class="n">05</span> The three bugs this closed</h2>++<h3>1 · Cross-package <code>refines</code> aliases silently failed to resolve</h3>+<p>Five operator call sites compared two <code>Concept</code> values directly instead of going through <code>ConceptLibrary.is_compatible</code>. That meant <code>concept_resolver=None</code>, and a refinement written across a package boundary — <code>refines = "imgdep->native.Image"</code> — never resolved <i>at those sites</i>. Every other compatibility check in the tree already went through the wrapper.</p>+<p><b>What it looked like:</b> a concept that legitimately refines <code>native.Image</code> through a dependency alias was not recognised as an image by the template analyser, so <code>@pic</code> produced no image reference — at authoring time, with no error to read. Same class of failure on the PipeLLM text-vs-object run branch.</p>+<p>Pinned by <code>test_template_image_analyzer_cross_package.py</code>, which drives the <i>public</i> <code>analyze_template_for_images</code> rather than a private resolver. It failed red with <code>0 == 1</code> before the fix. The other four sites are the same one-line swap through the same wrapper.</p>++<h3>2 · An unresolvable structure class answered <code>False</code>, not an error</h3>+<p>The old class tier did <code>if concept_1_class is None or concept_2_class is None: return False</code>. "I could not resolve this name" and "these are incompatible" are different answers, and callers cannot tell them apart. Now it raises <code>ConceptStructureClassNotFoundError</code>.</p>+<div class="note stop"><b>This one was load-bearing for the whole refactor.</b> It's the reason the tiers had to be composed by the library rather than merged: only the thing that owns resolution can tell "no class" from "not compatible", so only it can decide which to return.</div>++<h3>3 · <code>native.Anything</code> was answered for the wrong reason</h3>+<p><code>NativeConceptCode.ANYTHING.structure_class</code> is <code>None</code> by design — it is the untyped vehicle — while <code>structure_class_name</code> still derives <code>"AnythingContent"</code> mechanically, a name no registry ever holds. So <code>is_compatible(Anything, Text)</code> returned <code>False</code> via the silent <code>None</code> branch: right answer, wrong reason. Making bug #2 raise would have turned that into a crash.</p>+<p>Fixed at the source rather than papered over: <code>NativeConceptCode.is_structureless_concept</code> + <code>Concept.declares_a_structure_class</code> make "this concept has no structure" a <i>declared property</i>, checked before the class tier. Verdicts are unchanged in both directions; the reasoning is now correct. Pinned by <code>test_the_structureless_native_concept_is_answered_not_raised</code>.</p>++<h2 id="calls"><span class="n">06</span> Judgement calls worth knowing about</h2>++<details>+ <summary>Why <code>pipe_abstract.py</code> still reads the registry directly</summary>+ <p>It decorates graph-registry entries with a concept's JSON Schema, and it cannot import either hub. The constraint is a <b>static-analysis</b> cycle, not a runtime one — worth knowing before you "fix" it:</p>+ <ul>+ <li>A clean-interpreter probe after <code>import pipelex.runtime_hub</code> shows <code>pipe_machinery.pipe_abstract</code>, <code>pipe_run.pipe_job</code> and <code>plugins.orchestrator_registry</code> all <b>absent</b> — those edges are <code>TYPE_CHECKING</code>-only.</li>+ <li>But pyright's <code>reportImportCycles</code> counts them, so importing either hub there is a hard type-check failure via <code>runtime_hub → plugins.orchestrator_registry → pipe_run.pipe_job → here</code>.</li>+ <li>A <i>deferred</i> import doesn't dodge it: pyright reports at <code>interpreter_hub.py</code>, where no line-level ignore can reach.</li>+ </ul>+ <p>So it uses the below-both-hubs accessor, deliberately with the lenient <code>get_class</code> (no bound, <code>None</code> rather than a raise) because the schema is optional decoration. This is the one sanctioned read-side exception in the tree, and it's stated as such in <code>class_registry_access.py</code>.</p>+</details>++<details>+ <summary>Why <code>--save-csv</code> resolves through an <i>empty</i> library</summary>+ <p>Found by an e2e test, and it's the surprise of the branch. <code>PipelexMTHDSProtocol.execute</code> tears the run library down on its way out — so <b>every</b> post-run step in <code>_execute_run</code> (the CSV save, the pretty print, the working-memory dump) runs with no current library. Migrating the CSV row-model lookup to <code>get_concept_library()</code> produced <code>RuntimeError: No current library set</code>.</p>+ <p>The old code never noticed because it read the process-global registry, which is never unregistered at teardown — the classes outlive the library that defined them. <code>ConceptLibrary.make_empty()</code> reads that same registry while keeping the single typed "name → class, or a typed error" implementation.</p>+ <p>The lifecycle smell underneath is real and out of scope: a post-run step needing the method's <i>declarations</i> is running after the method is gone. The honest fix is a result object carrying what post-run steps need, or holding the library window open across them.</p>+</details>++<details>+ <summary>Four <code>except</code> arms: two removed, two deliberately not added</summary>+ <p><code>ConceptFactory</code> refuses to build a concept whose declared structure class does not resolve — a bad <code>structure = "…"</code> raises <code>ConceptFactoryError</code>, and the basic-blueprint path <i>generates</i> the class. Every <code>Concept(...)</code> construction in <code>pipelex/</code> source lives inside that factory. So a concept in a loaded library always has a resolvable structure class.</p>+ <p>Consequently: <code>resolve_input_kind</code>'s <code>except ConceptValueError → InputKind.DYNAMIC</code> fallback was unreachable and was <b>removed</b> (keeping it would restore exactly the silent degradation bug #2 removes), and the two run-path lookups the plan flagged as needing guards were <b>left unguarded</b>. Adding them would be guarding an impossible scenario, and bug #2's fix already made the error self-describing — it names the concept ref and the class.</p>+ <p>The asymmetry with the guarded <i>validation</i> siblings in the same files is intentional: the <code>/validate</code> sweep needs per-pipe granularity or one bad pipe aborts the whole bundle. A run has no sweep.</p>+</details>++<details>+ <summary>The purity lock, and why it's a golden set rather than a rule</summary>+ <p><code>test_concept_registry_boundary.py</code> asserts that exactly two modules under <code>pipelex/core/concepts/</code> touch the class registry, and both are the <b>materialisation write side</b> — <code>concept_factory</code> registering generated classes, <code>structure_generation/generator.py</code> looking up base classes to generate against. That's genuinely the registry's business and stays.</p>+ <p>A golden set, not a predicate, for the same reason the <code>cogt</code> boundary test gives: nothing separates a sanctioned write-side read from a new read-side one, so the value is turning a third module into a diff a reviewer sees. <b>No other gate can see this edge</b> — both the accessor and its users are runtime-layer, so the hub-layering guard is blind to it by construction.</p>+ <p>It matches four spellings, because an import-name-only walk waved three of them through: the accessor by name, the module path, the attribute call (<code>runtime_hub.get_class_registry()</code>), and two indirect roots — <code>KajsonManager.get_class_registry()</code> (which skips library scoping entirely, and has a live precedent in <code>runtime_bridge</code>) and <code>ClassRegistryUtils</code>.</p>+</details>++<h2 id="notdone"><span class="n">07</span> What this does <i>not</i> do</h2>++<div class="note stop"><b>The scoping half is not done.</b> <code>ConceptLibrary.get_structure_class</code> calls <code>get_class_registry()</code>, which selects a registry from the current async context — not one the provider carries. A <code>ConceptLibrary</code> holds no registry at all; the per-library <code>ClassRegistry</code> lives on <code>Library</code>. So passing a specific library as <code>concept_provider</code> does not scope class resolution to it.</div>++<p>Codex raised this as a P1 on the PR. The mechanism is real; the divergence it describes is not reachable:</p>++<ul>+ <li><b>Provider-library and registry-library are two reads of one variable.</b> Every non-forwarding <code>concept_provider=</code> source is <code>get_concept_library()</code> → <code>LibraryManager.get_current_library()</code> → the <code>_library_id</code> ContextVar, which is the same one <code>_resolve_scoped_class_registry</code> reads. They cannot name different libraries.</li>+ <li><b>The one place that installs a per-library registry pairs them.</b> <code>runtime_bridge/primitives/rehydration.py</code> calls <code>set_class_registry</code> and <code>set_current_library</code> on the same library in adjacent statements.</li>+ <li><b>Two sites deliberately depend on the ambient read</b> — the post-teardown <code>--save-csv</code> lookup and every boot-free test using <code>make_empty()</code>. Carrying a registry on the provider would break both unless it re-derived the global fallback <code>get_class_registry()</code> already implements.</li>+</ul>++<p>Not a regression either: on <code>dev</code>, the removed <code>Concept.get_structure_class()</code> read the same registry. This PR moved <i>where</i> the call lives, never <i>which</i> registry it reads. What it <b>did</b> buy is that scoping it later is now a one-place change.</p>++<h4>Trip-wires that would make it real</h4>+<ol>+ <li>A caller passes <code>library_manager.get_library(library_id=X).concept_library</code> instead of <code>get_concept_library()</code>.</li>+ <li>A <b>dependency/child</b> library's <code>concept_library</code> is used as a provider. Child <code>Library</code> objects live in <code>Library.dependency_libraries</code> and are <i>not</i> in <code>LibraryManager._libraries</code>, so <code>get_library_class_registry</code> structurally cannot see their registry. This is the sharpest of the four.</li>+ <li><code>InterpreterHub.set_concept_library</code> gains a live writer — it currently has zero callers, so its standalone-library fallback branch is dead code.</li>+ <li>A <code>set_class_registry</code> call site appears that is not paired with <code>set_current_library</code> on the same library.</li>+</ol>++<h4>Also deliberately out of scope</h4>+<ul>+ <li><b>The write side stays ambient.</b> Making libraries own their class registry explicitly is a separate, larger track.</li>+ <li><b>No <code>StaticConceptProvider</code></b> — build it when something needs it, not for symmetry.</li>+ <li><b>No operator parameterisation.</b> Interpreter-layer <code>get_concept_library()</code> calls are the sanctioned idiom for that layer today.</li>+</ul>++<h2 id="reviews"><span class="n">08</span> Review log — read this bit</h2>++<p>Four review passes ran over this branch. <b>Not one found a correctness defect in the code.</b> Every substantive finding was about a <i>claim</i> — prose asserting more than the implementation delivers. That pattern is the most transferable thing in this document.</p>++<div class="scroll">+<table>+ <thead><tr><th>Pass</th><th>Found</th><th>Outcome</th></tr></thead>+ <tbody>+ <tr>+ <td>Sonnet code-review (checkpoint 1)</td>+ <td>~8 unguarded call sites for the new raise</td>+ <td><b>Rejected</b> — unreachable via the factory guard. Residual sweep-granularity tradeoff recorded.</td>+ </tr>+ <tr>+ <td>Sonnet code-review (checkpoint 2)</td>+ <td>One doc inconsistency ("Two modules", named one)</td>+ <td><b>Fixed</b> before commit.</td>+ </tr>+ <tr>+ <td>Codex (P1)</td>+ <td>Provider does not scope class resolution to its own library</td>+ <td><b>Split.</b> Declined on the code (unreachable, and the fix breaks two sites). Applied on the wording — three places asserted the property.</td>+ </tr>+ <tr>+ <td>gstack <code>/review</code> finalize</td>+ <td>Four verified doc/code contradictions, one new silent-degradation path, one test narrower than its claim</td>+ <td><b>All six fixed.</b> Four design tradeoffs deferred to <code>wip/inputs/</code>.</td>+ </tr>+ </tbody>+</table>+</div>++<p>Two of the finalize findings are worth calling out because they'd bite anyone:</p>++<ul>+ <li><b><code>pipe_io_contracts</code> documented the hazard this PR removed.</b> Its docstrings warned that a post-teardown call "silently renders against whatever classes the registry last held" — but the builder now resolves the library up front, so it raises. The docstring whose entire job is to instruct callers about the library window described the inverse of the behaviour.</li>+ <li><b><code>output_renderer</code> gained a silent-degradation path.</b> <code>get_concept_library()</code> sat <i>inside</i> a <code>try</code> whose <code>except (PipelexError, ValueError)</code> renders <code><unable to render></code> — so a library-lifecycle fault would surface as the placeholder meant for an unrenderable concept. The exact loud-vs-silent conflation this branch exists to remove, reintroduced one layer up. Hoisted out; a two-line fix.</li>+</ul>++<div class="note"><b>Greptile:</b> 5/5, no findings, three reviews. <b>Codex:</b> clean on the final head. <b>Cubic:</b> could not review — the workspace hit its free monthly line limit. That's a billing state, not a verdict, so this PR shipped without a cubic pass.</div>++<h2 id="links"><span class="n">09</span> Links</h2>++<div class="scroll">+<table>+ <thead><tr><th>What</th><th>Where</th></tr></thead>+ <tbody>+ <tr><td>This work</td><td><a href="https://github.com/Pipelex/pipelex/pull/1072">pipelex#1072</a> — <code>refactor/Concept-purity</code> → <code>dev</code></td></tr>+ <tr><td>Lineage — hub split</td><td><a href="https://github.com/Pipelex/pipelex/pull/1062">pipelex#1062</a> · <a href="https://github.com/Pipelex/pipelex/pull/1064">#1064</a></td></tr>+ <tr><td>Lineage — layer placement</td><td><a href="https://github.com/Pipelex/pipelex/pull/1070">pipelex#1070</a> · <a href="https://github.com/Pipelex/pipelex/pull/1071">#1071</a></td></tr>+ </tbody>+</table>+</div>++<h3>Cross-repo</h3>++<p><b>No other repo needs a code change.</b> Cross-repo usage of the four removed member names is zero — measured by enumerating the workspace directory rather than trusting a hardcoded repo list. Two <i>documents</i> cite them and will want a look when their tracks resume:</p>++<ul>+ <li><b><code>pipelex-js</code></b> — <code>wip/gauntlet/invariants-structural.md</code>, invariant <code>CONCEPT-6</code>. A live invariant register for the in-progress TS port, citing the compatibility block this PR restructured. There is a handoff note next to this document for that track.</li>+ <li><b><code>pipelex-temporal</code></b> — <code>wip/bad-parallel-combine-class-identity-bug.md</code> cites the removed <code>get_structure_class()</code>.</li>+</ul>++<footer>+ <p>Diagrams are hand-authored inline SVG — no script, no CDN, renders offline and in both colour schemes. Written from <code>refactor/Concept-purity</code> at head <code>81ba5817c</code>.</p>+</footer>++</div>diff --git a/wip/concept-purity/concept-purity-tracker.md b/wip/concept-purity/concept-purity-tracker.mdnew file mode 100644index 000000000..e0f1a1188--- /dev/null+++ b/wip/concept-purity/concept-purity-tracker.md@@ -0,0 +1,70 @@+# Concept purity — evicting the ambient class-registry reads from the core concept model++**Reviewer's guide**, archived from the repo-root `TODOS.md` once PR [#1072](https://github.com/Pipelex/pipelex/pull/1072) was finalized. Branch `refactor/Concept-purity`, cut from `dev` at `ed7435a7c`. Two functional commits: `e94b2a4c9` (compatibility) and `89cf2158d` (class access, purity lock, docs); the rest are review-round corrections. This document is what the branch is *for* — read it before the diff.++**Lineage:** continues the hub-split / layer-placement line of work (#1062, #1064, #1070, #1071) — same doctrine, applied to the last ambient lookup left inside the core concept model.++## The problem in one paragraph++`Concept` (`pipelex/core/concepts/concept.py`) is a subclass of the MTHDS-protocol wire model `ConceptAbstract` — `code`, `domain_code`, `description`, `structure_class_name: str`, `refines`. Pure serializable data. Except that four of its members answered *behavioral* questions by reaching into the process-global class registry, and that one import is what `system/registries/class_registry_access.py`'s own docstring cited as the reason the accessor has to sit below both hubs. It coupled a standard-owned wire model to a Pipelex process-global — the model could not answer a question about itself without a Pipelex runtime having been booted around it, and every caller that held a `Concept` inherited that dependency invisibly.++## What changed++**Compatibility is now two tiers, composed by the thing that owns resolution.**++- `Concept.are_compatible_by_declaration` is the *declaration tier*: pure over the model's own fields plus an injected `concept_resolver` — dynamic short-circuits, ref equality, declared-class-name equality, `refines` chains including cross-package aliases. No registry.+- `are_structure_classes_compatible` (`tools/typing/class_utils.py`) is the *class tier*: pure over two already-resolved classes — equivalence, then (loose only) subclass or nested-field.+- `ConceptLibrary.is_compatible` composes them. Declaration tier first; classes are resolved only when it is inconclusive.++The verdicts are asymmetric on purpose, and the docstrings say so: at the declaration tier, `True` means "established by the declarations" and `False` means "*not established at this tier*" — never "incompatible".++**Class access left the model.** `ConceptProviderAbstract` grew `get_structure_class(concept)`, implemented by `ConceptLibrary` against the active registry with a `StuffContent` subclass bound.++| removed from `Concept` | replaced by |+| --- | --- |+| `are_concept_compatible(..., strict=)` | `are_compatible_by_declaration` + `are_structure_classes_compatible`, composed by `ConceptLibrary.is_compatible` |+| `get_structure_class()` | `ConceptProviderAbstract.get_structure_class(concept=…)` |+| `is_valid_structure_class(name)` | a private module-level helper in `concept_factory.py`, its only caller |+| `search_for_nested_image_fields_in_structure_class()` | compose the provider with the existing free `search_for_nested_image_fields` |++`render_concept_representation` now takes the already-resolved `structure_class`. `StuffSpec.render_stuff_spec`, `InputStuffSpecs.build_inputs_template` and `render_inputs` take a `concept_provider` and resolve once.++## Three defects this closes++1. **Cross-package `refines` silently failed to resolve at five call sites.** `pipe_llm` (×2), `template_image_analyzer` (×2) and `template_document_analyzer` compared two `Concept` values directly instead of going through `ConceptLibrary.is_compatible`, so `concept_resolver` was `None` and a `dep->domain.Code` alias never resolved. Wrong compatibility verdicts at authoring time and on the PipeLLM text-vs-object run branch. Every other compat check in the tree already went through the wrapper. One of the five is pinned by `tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py`, which drives the *public* `analyze_template_for_images` rather than a private resolver; the other four are the same one-line swap through the same wrapper.++2. **An unresolvable structure class answered `False` instead of failing.** "Unknown" and "incompatible" are different answers; conflating them is a latent wrong-verdict bug. It now raises `ConceptStructureClassNotFoundError` — a `ConceptValueError` subclass, so guards that already convert that error at their own boundary keep working unchanged.++3. **The ambient read left the wire model.** `Concept` reads no registry at all, and the declaration tier answers compatibility without resolving a class in the first place — so concepts whose structure classes were never materialized still get an answer. Class resolution still goes through the process's *active* registry rather than one the provider carries; what changed is that it now has exactly one implementation, behind `ConceptProviderAbstract`. See "the scoping half is not done" below for what that does and does not buy.++## Where to look, and what to check++- **`pipelex/core/concepts/concept.py`** — the point of the branch. It should import nothing from `system/registries/`, and every remaining member should be a function of the model's fields (plus the injected resolver or the passed-in class).+- **`pipelex/libraries/concept/concept_library.py`** — `is_compatible` and `get_structure_class`. This is the one place that legitimately owns resolution; check the composition order and the `declares_a_structure_class` guard.+- **The five former bypass sites** — check that direction and `strict` semantics survived the move. `is_image`/`is_document` are `strict=True`; `has_nested` is `strict=False`.+- **`tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py`** — the golden set that keeps this from growing back. It matches the accessor by import name, by module path, by attribute call (`runtime_hub.get_class_registry()`), and via the two indirect roots that bypass the accessor entirely (`KajsonManager`, `ClassRegistryUtils`) — an import-name-only walk would have waved all three through.++## Decisions a reviewer will want the reasoning for++**`native.Anything` declares no structure class at all, and that is not a missing registration.** `NativeConceptCode.ANYTHING.structure_class` is `None` by design (it is the untyped vehicle), while `structure_class_name` still derives `"AnythingContent"` mechanically — a name no registry ever holds. The old silent-`False` was masking that: `is_compatible(Anything, Text)` answered `False` for the *wrong reason*. `NativeConceptCode.is_structureless_concept` + `Concept.declares_a_structure_class` make "this concept has no structure" a declared property, and `is_compatible` returns `False` for it before reaching the class tier. Verdicts unchanged; the reasoning is now correct.++**`pipe_machinery/pipe_abstract.py` reads the class registry directly, and must.** Importing either hub there is a pyright `reportImportCycles` failure via `runtime_hub` → `plugins.orchestrator_registry` → `pipe_run.pipe_job` → here, and a *deferred* import does not help: the error is reported at `interpreter_hub.py`, where no line-level ignore can reach. That is exactly what the below-both-hubs accessor exists for. Note the constraint is a **static-analysis** cycle, not a runtime one: those edges are `TYPE_CHECKING`-only and a clean-interpreter probe shows all three modules absent from `runtime_hub`'s runtime closure — but pyright counts them, and the finalize review caught the first draft of this comment stating it as a runtime closure. The docstring now records the measurement. Two consequences worth knowing: this is a *second* read-side resolution in the tree, and it deliberately uses the lenient `get_class` (no `StuffContent` bound, `None` rather than a raise) because the schema is optional decoration on a graph-registry entry.++**`--save-csv` resolves through `ConceptLibrary.make_empty()`, deliberately.** `PipelexMTHDSProtocol.execute` tears the run library down on its way out, so every post-run step in `_execute_run` has no current library — migrating this site to `get_concept_library()` turned `tests/e2e/pipelex/cli/test_csv_run.py` red with `RuntimeError: No current library set`. The old code never noticed because it read the process-global registry, which is never unregistered at teardown. An empty library reads that same registry while keeping the single typed "name → `StuffContent` subclass, or `ConceptStructureClassNotFoundError`" implementation. The lifecycle smell underneath is real and out of scope — recorded in `wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md`.++**The scoping half is not done, and the branch no longer claims it is.** `ConceptLibrary.get_structure_class` calls `get_class_registry()`, which selects a registry from the current async context rather than from `self` — a `ConceptLibrary` holds no registry (the per-library `ClassRegistry` lives on `Library`). Codex flagged this as a P1 on the PR; it is a real mechanism, but the divergence it describes cannot occur: `get_concept_library()` and `_resolve_scoped_class_registry()` are two reads of the same `_library_id` ContextVar, and the one place that installs a per-library registry (`runtime_bridge/primitives/rehydration.py`) sets it and the ContextVar on the same library in adjacent statements. The proposed fix — carry a registry on the provider — would also break the two sites that deliberately depend on the ambient read (`--save-csv` post-teardown, and every boot-free test using `make_empty()`). Declined; the trip-wires that would make it real, the shape of the fix, and four sibling tradeoffs the finalize review surfaced — including that the new `StuffContent` bound tightened the *compatibility verdict* path as well as `get_structure_class` — are in `wip/inputs/provider-scoped-class-resolution.md`. What the review *did* correctly catch is that two new docstrings and the PR body overstated the property — those were corrected.++**Two `except` arms were removed rather than migrated, and two more were deliberately not added.** `resolve_input_kind` caught `ConceptValueError` and fell back to `InputKind.DYNAMIC`; `pipe_parallel` (combine) and `pipe_search` (structured output) call `get_structure_class()` unguarded on run paths where their *validation* siblings convert to `PipeValidationError`. All four concern the same question, and the answer is the same: `ConceptFactory` refuses to build a concept whose declared structure class does not resolve (`concept_factory.py` raises `ConceptFactoryError` on a bad `structure = "..."`, and the basic-blueprint path *generates* the class), and every `Concept(...)` construction in `pipelex/` source lives inside that factory. So the state is unreachable, keeping the fallback would restore exactly the silent degradation defect 2 removes, and adding two more guards would be guarding an impossible scenario. The asymmetry with the guarded validation siblings is intentional and explained in place: the `/validate` sweep needs per-pipe granularity or one bad pipe aborts the whole bundle, and a run has no sweep. Full reasoning, including what would have to change for this to become reachable, is in the wip note above.++## Deliberate non-goals++- **The materialization write side stays ambient.** `concept_factory` registering generated classes and `structure_generation/generator.py` looking up base classes are library-load-time concerns and genuinely the registry's business. Making libraries own their class registry explicitly is a separate, larger track.+- **No `StaticConceptProvider`** — build one when something needs it, not for symmetry.+- **No operator parameterization.** The interpreter-layer `get_concept_library()` calls introduced here are the sanctioned idiom for that layer today.+- **No wire-format change.** `structure_class_name` stays a plain `str` protocol field; nothing serialized changes shape, and no `mthds` schema edit is needed.++## Verification++`make agent-check` green (ruff, plxt, pyright, mypy, keyword-only, hub-layering). Full `make agent-test` green. Cross-repo usage of the four removed member names is **zero in code** (enumerated the workspace directory rather than a hardcoded list). Two live *documents* cite them and will want a follow-up when their tracks resume: `pipelex-js/wip/gauntlet/invariants-structural.md` (CONCEPT-6) is an invariant register for the in-progress TS port citing `concept.py`'s compatibility block, and `pipelex-temporal/wip/bad-parallel-combine-class-identity-bug.md` cites the removed `get_structure_class()`. No code in either repo is affected. `pipelex-transport`'s `ALLOWED_SURFACE` names none of the touched symbols and no module moved, so no spec/conformance edit is due.++One registry hygiene note: `is_valid_structure_class` was demoted to keyword-only when it moved, so its now-dead entry was deleted from `subject_grants.toml` — the guard hard-fails on a stale grant, which is how it surfaced.diff --git a/wip/inputs/README.md b/wip/inputs/README.mdindex be7dbc6f9..ec658c60e 100644--- a/wip/inputs/README.md+++ b/wip/inputs/README.md@@ -61,3 +61,9 @@ Unlike the notes above, this one is **not a tradeoff — it is a live regression**Deferred design notes** (triage outcomes above): `case1-bare-date-arm-gap.md`, `bare-file-path-cli-resolution-gap.md`, `scalar-envelope-arm-asymmetry.md`, `loader-vs-factory-date-split-duplication.md`, `input-shaper-multiplicity-gaps.md`, `d4-hint-still-envelope.md`, `container-default-temporal-codegen-gap.md`, `structure-field-fidelity-guard.md`, `uri-scheme-classification-stopgap.md`, `refines-hint-native-list-drift.md`.**Open regression** (section above): `envelope-chaining-vs-d8.md` — the one item here that is a bug rather than a tradeoff.++**From other tracks, landing on shaper code:**++- `provider-scoped-class-resolution.md` — from the `refactor/Concept-purity` branch (PR #1072). `ConceptLibrary.get_structure_class` resolves against the async context's registry rather than one the provider carries; a `ConceptLibrary` holds no registry at all. Verified unreachable today (provider-library and registry-library are two reads of one ContextVar), and the obvious fix would break the sites that deliberately depend on the ambient read. Carries the four trip-wires that would make it real.++- `unresolvable-structure-class-escapes-the-validate-sweep.md` — from the `refactor/Concept-purity` branch. `ConceptLibrary.is_compatible` now raises instead of silently answering `False` when a structure class does not resolve; `resolve_input_kind` is one of its unguarded callers. Not reachable today (the concept factory refuses to build such a concept), so no guards were added — but if it ever becomes reachable, the fix belongs at the `bundle_validator` sweep boundary, not scattered across call sites. Also records two Phase-2 outcomes on shaper-adjacent code: the dead `except` arm in `resolve_input_kind` was removed, and `--save-csv` was found to run *after* the run library is torn down (a lifecycle smell the old ambient registry read was hiding).diff --git a/wip/inputs/provider-scoped-class-resolution.md b/wip/inputs/provider-scoped-class-resolution.mdnew file mode 100644index 000000000..27673961c--- /dev/null+++ b/wip/inputs/provider-scoped-class-resolution.md@@ -0,0 +1,49 @@+# The concept provider does not carry its own class registry++**Status:** deferred — a real architectural gap with no reachable failure today. Raised by Codex (P1) on PR #1072 (`refactor/Concept-purity`), verified, and declined for that PR. What it *did* change is the branch's own wording: three places claimed a scoping property the code does not deliver, and those were corrected.++## The claim++`ConceptLibrary.get_structure_class` resolves through `get_class_registry()`, which selects a registry from the **current async context**, not from `self`. So passing a specific `ConceptLibrary` as `concept_provider` does not actually scope class resolution to that library: if a caller hands over library A while the context names library B, resolution follows B. Codex's proposed fix was to store or inject the library's registry resolver on the provider.++## Verified: the mechanism is real++- A `ConceptLibrary` **holds no registry**. The per-library `ClassRegistry` lives on `Library` (`libraries/library.py`, `_class_registry` private attr with `get_class_registry` / `set_class_registry`); `ConceptLibrary` is a plain field of `Library` with no back-reference, and `ConceptLibraryAbstract` declares no registry member. So "use `self`'s registry instead" is not a correction — there is nothing to use.+- Scoping runs `get_class_registry()` → `class_registry_scoping.resolve()` → the resolver `set_interpreter_hub` installs → `_resolve_scoped_class_registry`, which reads the `_library_id` ContextVar and asks `LibraryManager.get_library_class_registry`. Unset, or a library with no registry of its own, falls back to the process-global Kajson registry.++## Verified: the divergence is not reachable++**Provider-library and registry-library are two reads of one variable.** Every non-forwarding `concept_provider=` source in `pipelex/` is `get_concept_library()`, which is `get_interpreter_hub().get_library().concept_library` → `LibraryManager.get_current_library()` → the same `_library_id` ContextVar that `_resolve_scoped_class_registry` reads. They cannot name different libraries.++**The one place that installs a per-library registry pairs the two.** `runtime_bridge/primitives/rehydration.py` calls `library.set_class_registry(run_registry)` and `set_current_library(library_id=library_id)` in adjacent statements on the same library. Every other `set_class_registry` call is a test, and the integration fixture (`tests/integration/pipelex/fixtures/pipe_job_helpers.py`) pairs them the same way.++**The only non-hub provider deliberately depends on the ambient read.** `cli/commands/run/_run_core.py`'s `--save-csv` step uses `ConceptLibrary.make_empty()` *after* the run library is torn down, precisely so the lookup lands on the process-global registry that still holds the generated classes. Codex's fix would break that site — an empty library has no registry — unless it re-derived the global fallback `get_class_registry()` already implements. The branch's own boot-free tests depend on the same decoupling.++That is why the fix was declined: no reachable failure motivates it, it would require inventing a registry for every parentless `ConceptLibrary`, and it would end up re-implementing the fallback it replaced. Also worth noting it is **not a regression** — on `dev`, the removed `Concept.get_structure_class()` and `Concept.are_concept_compatible` called `get_class_registry()` from the same module. PR #1072 moved *where* the call lives, never *which* registry it reads.++## What was actually wrong, and was fixed++The branch asserted a scoping property in three places. Two were docstrings written in this PR — `class_registry_access.py` ("scoped to the library you asked rather than to whatever the ambient registry happens to hold") and `stuff_spec.py` ("the rendering can no longer read whatever the ambient registry last held") — and one was the PR body's defect #3. All three overstated: the ambient read left the *wire model*, and gained a single implementation behind one seam, but it is still ambient. `class_registry_access.py`'s docstring is the module's stated architectural rationale, so a reader would have taken it as a guarantee. Corrected in the same PR.++## Trip-wires — any one of these makes it real++1. A caller passes `library_manager.get_library(library_id=X).concept_library` as the provider instead of `get_concept_library()`.+2. A **dependency/child** library's `concept_library` is used as a provider. Child `Library` objects live in `Library.dependency_libraries` and are *not* in `LibraryManager._libraries`, so `get_library_class_registry` structurally cannot see their registry. Today only the cross-package `_concept_resolver` touches them, never `get_structure_class`.+3. `InterpreterHub.set_concept_library` gains a live writer (it currently has **zero** callers, so its standalone-library fallback branch is dead).+4. A `set_class_registry` call site appears that is not paired with `set_current_library` on the same library.++## The shape of the fix, if it ever lands++Give `ConceptProviderAbstract` a way to name its registry and have `ConceptLibrary` carry the one from its parent `Library`, falling back to `get_class_registry()` when it has no parent — which keeps `make_empty()` and the `--save-csv` path working. One place changes (`ConceptLibrary.get_structure_class`), which is the property the single-seam refactor bought even though it did not use it.++## Related, from the same PR's finalize review++Four items surfaced alongside this one. All are design tradeoffs or pre-existing asymmetries rather than defects, and all share the same reachability gate as the note above.++**The `StuffContent` bound changed the compatibility verdict path too, not just `get_structure_class`.** `ConceptLibrary` resolves with `get_required_subclass(base_class=StuffContent)`, where the old class tier used an unbounded `get_class`. A name registered as a *non*-`StuffContent` class used to flow into `are_classes_equivalent` / `issubclass` and could answer `True`; it now raises. That tightening is deliberate and pinned for `get_structure_class` (`test_get_structure_class_rejects_a_class_that_is_not_stuff_content`), but only the `get_structure_class` half was written down — the compatibility half rides along undocumented. Same unreachability argument applies (the factory refuses to build such a concept), which is why it was recorded rather than reverted.++**`StuffSpec.render_stuff_spec` does not consult `declares_a_structure_class`.** An input declared `native.Anything` raises on the render/template paths while `is_compatible` answers `False` for it. Not a regression — the base commit raised `ConceptValueError` at the same point — but the new property makes the asymmetry visible for the first time. Whether rendering *should* have an `Anything` arm is a real question; it is not this branch's.++**`template_image_analyzer`'s dotted-path branch resolves unconditionally** while the two single-variable branches now answer for `Anything`. So `{{ anything_var }}` is fine and `{{ anything_var.field }}` fails bundle load. Pre-existing in kind, surfaced by the same property.++**`pipe_abstract` is a second read-side resolution, with a weaker bound.** It uses the lenient `get_class` (no `StuffContent` bound, `None` rather than a raise) rather than the provider seam, because importing either hub there is a pyright cycle. Deliberate — the schema is optional decoration on a graph-registry entry — and the honest resolution was to say so in `class_registry_access.py`'s docstring rather than change the code. Worth revisiting only if that module ever escapes the cycle.diff --git a/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md b/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.mdnew file mode 100644index 000000000..0fdf5d253--- /dev/null+++ b/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md@@ -0,0 +1,51 @@+# An unresolvable structure class would escape the `/validate` sweep++**Status:** deferred — a latent granularity tradeoff, not a live bug. Raised by the Phase-1 code review on `refactor/Concept-purity`, and rejected for Phase 1 after checking reachability.++## The claim++Phase 1 made `ConceptLibrary.is_compatible` **raise** `ConceptStructureClassNotFoundError` when a concept's declared `structure_class_name` does not resolve, where `Concept.are_concept_compatible` used to silently return `False`. That is the branch's stated fix (b): a name that should have resolved and didn't is not an answer to "are these compatible?", and answering `False` makes it indistinguishable from a genuine "incompatible" verdict.++The review observed that `is_compatible` is called from many pre-existing sites that do **not** guard against a raise, and proposed adding `except` guards at each. The named sites: `core/memory/input_shaper.py:236` (`resolve_input_kind`), `core/stuffs/stuff_factory.py` (the dict-building arms), `pipe_operators/compose/pipe_compose.py`, `.../extract/pipe_extract{,_factory}.py`, `.../structure/pipe_structure.py`, `.../img_gen/pipe_img_gen.py`, `.../search/pipe_search_factory.py`.++## Why it is not reachable today++`ConceptFactory` refuses to build a concept whose declared structure class does not resolve:++- `concept_factory.py:305` — a `structure = "SomeClass"` declaration that is not a registered `StuffContent` subclass raises `ConceptFactoryError` at concept-construction time.+- The basic-blueprint path (`concept_factory.py:371-385`) either finds an existing registered class or **generates** one.++Every `Concept(...)` construction in `pipelex/` source lives inside `concept_factory.py`. So a concept sitting in a loaded library always has a resolvable structure class, and the raise cannot fire on the loader path. The two direct `Concept.model_validate` sites (`pipe_run/delivery_executor.py:212`, `runtime_bridge/primitives/hydration.py:155`) rehydrate a stuff's concept in a process that has the bundle loaded.++Applying the proposed guards would convert the loud failure back into the silent degradation this branch exists to remove — at eight call sites, for a state the factory already refuses to produce. That is the "don't guard impossible scenarios" line.++## Why it is still worth writing down++If the state ever *does* become reachable — a concept deserialized into a process where the bundle's generated classes were never registered is the plausible route — the failure mode is coarser than it should be:++`pipeline/bundle_validator.py:214-225` sweeps pipes with `pipe.validate_with_libraries()` inside a `try` that catches **only** `PipeNotFoundError`. A `ConceptStructureClassNotFoundError` is a `ConceptValueError` is a `ValueError`, so it would escape the sweep and abort the whole bundle rather than reporting the one offending pipe as failed.++This is not a hypothesis about the codebase's opinion — `pipe_controllers/parallel/pipe_parallel.py:159-176` already wraps its `get_structure_class()` call for exactly this reason, and says so: *"A plain ValueError would escape the /validate sweep and abort the whole bundle; convert it so this pipe alone is reported as failed."*++The right shape, if it ever needs doing, is **not** eight scattered `except` blocks. It is one decision at the sweep boundary: `bundle_validator` catching `ConceptValueError` alongside `PipeNotFoundError` and recording the pipe as failed — one place, matching the granularity contract the sweep already implements for unresolved dependencies.++## Resolved in Phase 2: the `input_shaper` fallback arm++`input_shaper.resolve_input_kind` carried an `except ConceptValueError: return InputKind.DYNAMIC` around `concept.get_structure_class()`, and a comment listing "any concept whose class is unregistered" among the cases that fall back to bottom-up building. Given the factory guard above, that arm was unreachable and the comment overstated it. Phase 2 migrated the call site to `concept_provider.get_structure_class(...)` and **dropped the guard**: keeping it would have converted the loud raise straight back into the silent fallback fix (b) exists to remove, for a state the factory refuses to produce. The comment now names only the cases that actually reach it.++## Also declined in Phase 2: guarding the two run-path lookups++The branch's own inventory flagged `pipe_parallel.py` (the combine step) and `pipe_search.py` (the structured-output step) as pre-existing bugs — they call `get_structure_class()` unguarded on run paths where their *validation* siblings convert to `PipeValidationError`. Phase 2 migrated all three onto the library but **did not add a third guard**, for two reasons:++- Same reachability argument as above. A concept sitting in a loaded library always has a resolvable structure class, and both sites run mid-execution with that library loaded.+- The complaint has partly aged out. It was written against `ConceptValueError("Concept class 'X' not found")`, which named neither the concept nor the pipe. Phase 1 replaced that with `ConceptStructureClassNotFoundError`, whose message carries the concept ref *and* the declared class name — so a raw escape is already self-describing. What a `PipeRunError` wrapper would add is `pipe_code` and `run_mode`.++The asymmetry with the guarded validation siblings is deliberate and already explained in place: the `/validate` sweep needs per-pipe granularity or one bad pipe aborts the whole bundle, and a run has no sweep. If the conversion is ever wanted, it is a few lines at each site — but it should be motivated by a reachable failure, not by symmetry.++## Discovered in Phase 2: `--save-csv` runs outside the library window++Migrating `_run_core.py`'s `--save-csv` step to `get_concept_library()` broke `tests/e2e/pipelex/cli/test_csv_run.py` with `RuntimeError: No current library set` — `PipelexMTHDSProtocol.execute` tears the run library down on its way out (`runner.py:298-310`), so **everything** after it in `_execute_run` (the CSV save, the pretty print, the working-memory dump) runs with no current library.++The old code did not notice because `concept.get_structure_class()` read the process-global class registry, which is never unregistered at teardown — the exact wart `pipe_io_contracts.py`'s module docstring documents for its own rendering. Phase 2 resolves through `ConceptLibrary.make_empty()` instead, which reads the same process-global registry but keeps the single typed "name → `StuffContent` subclass, or `ConceptStructureClassNotFoundError`" implementation.++That is correct for the CLI (direct execution puts generated classes in the process-global registry) but it is a lifecycle smell, not a design: a post-run step that needs the method's *declarations* is running after the method is gone. The real fix is to give `_execute_run` a result object that carries what the post-run steps need, or to hold the library window open across them — both larger than this branch. Tracked in the workspace-root `wip/library-lifecycle-hygiene.md` alongside the registry-teardown question.