Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
fix: give every opened library its own class registry (#1167)
Louis Choquel2d435cbf5d0b
diff --git a/.badges/tests.json b/.badges/tests.jsonindex fdd00b0fa..bb6e3c9d2 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "11140",+ "message": "11149","color": "blue","cacheSeconds": 300}\ No newline at end of filediff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 75d81bee9..128835aaa 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:f248fe213446457c1d1ba69bed204c9741fc91a1dd965969a3065ac7be4af20d"+digest = "sha256:2e2f3f3c4886666d48918080519c18ff9466e16a11798eaf55b7af89ecab097f"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-01T14:16:51Z"-rationale = "The --pipe slice miss now raises EntryPipeNotFoundError, so the agent-CLI validate_pipe_in_bundle_core docstring names it instead of the base. Reviewed docs/tools/cli/ -- agent-cli.md and validate.md document the --pipe flag and the error envelope generically, naming no per-command error class and no exit code that moved (the not-found arm still exits 2), so nothing there was stale. Reviewed pipelex/cli/agent_cli/CLAUDE.md -- its Error classification bullet already states the report-first rule and cites the two validate not-found arms; this change is what finally makes the validate bundle arm's label carry a real domain, which the bullet already describes, so no edit was needed."+reviewed_at = "2026-09-02T20:44:04Z"+rationale = "Pre-landing review pass on fix/Library-class-registry-scoping. The only CLI trigger change is in pipelex/cli/commands/run/_run_core.py: the comment above the --save-csv except block is rewritten to state what is true (CsvError is a ToolError and so a PipelexError, so it never escaped execute_run's generic except arm) and CsvError is dropped from that tuple because PipelexError already covers it -- no command, flag, help text, exit code or message moved. Re-reviewed docs/tools/cli/ and pipelex/cli/agent_cli/CLAUDE.md against that: neither names the exception tuple or the CsvError class, and the --save-csv behaviour they describe is unchanged, so nothing there is stale."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -111,7 +111,7 @@ rationale = "The --pipe slice miss now raises EntryPipeNotFoundError, so the age"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:71434e5eb9dc512a89f582d7f897a5a121b20eec"+"pipelex/cli/commands/run/_run_core.py" = "blob:2659db67a5c929f8de1dd47e2bbb729563ef1e2f""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/CHANGELOG.md b/CHANGELOG.mdindex f1e94459f..f0e922dd7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,8 @@### Fixed+- **A class-registry read before boot no longer starves the boot's global registry**: `KajsonManager.get_class_registry()` instantiates the kajson singleton around an empty registry when none exists, and the boot's own `KajsonManager(class_registry=…)` then handed that pre-boot manager back and silently discarded the boot's registry — the core models landed where nothing resolved, while the boot still reported ready. Any pre-boot manager is now dropped before the boot constructs its own. Reachable from any pre-boot caller of the scoped accessor's global fallback, and from a library opened on a bare `LibraryManager`.+- **A library's generated structure classes no longer escape into another request**: structure classes materialized from a concept's `structure` table are registered under a name key (`<domain>__<Concept>`), and a `Library` that carried no class registry of its own resolved through to the one process-global registry — so every load in a process shared a single slot per concept ref. Two bundles naming the same concept contaminated each other: a later bundle declaring `Summary` with only a description silently reused an earlier bundle's structured `Summary` (in its I/O contracts, in its input form, and as the class its `PipeLLM` structured output against), and two loads that interleaved at an `await` overwrote each other's registration, so whichever landed last was what both rendered schemas from. In a server handling several bundles — the validate route, the dry-validate activity, every crate route — that crossed request boundaries. `LibraryManager.open_library` now attaches a fresh `ClassRegistry`, pre-seeded from the process-global one, to every library it creates, so a load's generated classes live and die with the library that asked for them and the global registry keeps only what boot put there; isolation is structural rather than something a caller opts into. Host code should note the consequence: a structure class registered while a library is current lands in that library's registry, so a Python class every load must see has to be registered before any library is opened. `pipelex run --save-csv` now takes its row model off the produced rows rather than re-resolving the class by name after the run library is torn down. See [Runtime bridge and transport → Per-call scoping](under-the-hood/runtime-bridge-and-transport.md).- **A dict-default key carrying a double quote made the generated `types.ts` unstable under prettier**: an object-literal key that is not a plain identifier was quoted with `json.dumps`, so a key like `marked "urgent"` — reachable from `default_value = { 'marked "urgent"' = 3 }`, ordinary TOML on a `type = "dict"` field — came out double-quoted with escapes and prettier rewrote it to the escape-free `'marked "urgent"'` on the consumer's first format run, breaking the stamp. Keys now go through the same fewer-escapes quote rule as every other emitted literal, which the value side already used. This was found and deliberately deferred during the ts-zod optionality work, on the grounds that a real gate over the emission would catch its whole family at once rather than one more hand-written assertion; the newly mandatory prettier gate reddened on it immediately.- **The ts-zod projection could not parse the engine's own wire payload** (breaking for generated TypeScript — regenerate): a non-required concept field was projected as `.optional()`, which means `T | undefined` in Zod and rejects an explicit `null`. The runtime serializes an unset optional field as exactly that — the generated runtime class annotates every non-required field `X | None` and the transport dump keeps nulls on purpose (no `exclude_none`, spelled out at the composer's dump sites) — so `Schema.parse` failed on a successful run's output with one issue per nulled field. The wire genuinely carries both spellings of "unset", a key a partial payload omitted and a key the runtime nulled, and the projection now describes both: `.nullish()` for a non-required field, and `.nullable().default(…)` where it carries a default, since a producer may null a defaulted field explicitly. There is no `.transform()` folding `null` into `undefined` — the binder uses one schema for both `parse` and `serialize`, so a transform would desynchronize the pair. Parsed optional fields therefore type as `T | null | undefined` instead of `T | undefined` (`??` covers both), and a recursive concept's explicit `export type` carries the same widening, because it is checked against the schema's inferred output. The two Python targets already accepted both spellings; this is a parity fix. Because `.nullable()` costs width on every defaulted field, the emitter's line-breaking now models prettier's real rule — a member chain of two or more calls breaks entirely, whatever the expression — rather than treating `z.enum([…])` as the only shape that can overflow; a defaulted `z.string()` overflows on nothing but a long field name and default literal. Prettier then re-measures each call on its new line and leaves flat any that now fits, so an ordinary three-choice enum carrying a default — which reaches the break on its `.nullable()` width alone — keeps its members on one line rather than being exploded into a shape the formatter folds straight back. See [Codegen Projections](under-the-hood/codegen-projections.md).diff --git a/docs/building-methods/pipes/csv-input-and-output.md b/docs/building-methods/pipes/csv-input-and-output.mdindex af2b07758..d874b7aa4 100644--- a/docs/building-methods/pipes/csv-input-and-output.md+++ b/docs/building-methods/pipes/csv-input-and-output.md@@ -102,7 +102,7 @@ pipelex run bundle demo.mthds --save-csv out.csvpipelex run method my_method --save-csv out.csv```-The path is **literal and cwd-relative** — it is written exactly where you point it, not under `--output-dir`. Parent directories are created as needed. The output's main stuff must be a flat list; if it is not a list, or its row concept is not flat, you get a clear error rather than a malformed file. The header is derived from the **declared** row concept (not from the first item), so an empty list still writes a correct header-only file. On write, `None` is rendered as an empty cell and booleans as lowercase `true`/`false`, so a value round-trips back through a read unchanged.+The path is **literal and cwd-relative** — it is written exactly where you point it, not under `--output-dir`. Parent directories are created as needed. The output's main stuff must be a flat list; if it is not a list, or its row concept is not flat, you get a clear error rather than a malformed file. The header is derived from the row concept's structure — the class the run produced its rows with, or, for a run that produced no rows, the declared concept resolved by reloading the method — so an empty list still writes a correct header-only file. On write, `None` is rendered as an empty cell and booleans as lowercase `true`/`false`, so a value round-trips back through a read unchanged.## Round-trip examplediff --git a/docs/under-the-hood/pipe-routing-and-execution.md b/docs/under-the-hood/pipe-routing-and-execution.mdindex f2e2fb886..7cd299b71 100644--- a/docs/under-the-hood/pipe-routing-and-execution.md+++ b/docs/under-the-hood/pipe-routing-and-execution.md@@ -253,7 +253,7 @@ Distributed execution introduces three mechanisms that don't exist in direct mod- **LibraryCrate propagation** — the submitter attaches a serializable snapshot of all pipes and concepts to the `PipeJob`; every worker-side job loads it (idempotently, by fingerprint) so `get_required_pipe()` resolves at every level.- **Deferred hydration** — `WorkingMemory` crosses as a raw JSON dict (`working_memory_raw`) on both `PipeJob` inputs and `PipeOutput` return values, avoiding deserialization failures when a receiving process hasn't registered the bundle's dynamic concept classes. The transport-prep helpers are not part of open core; the raw field and the hydration helper are.-- **Per-call isolation** — each job gets its own `ClassRegistry` (pre-seeded from the global registry) and its own `Library`, scoped via `ContextVar`, so concurrent jobs with conflicting concept names (e.g., two bundles that both define `Result` with different fields) don't cross-contaminate.+- **Per-call isolation** — every `Library` the manager opens carries its own `ClassRegistry` (pre-seeded from the global registry), and a job's library is scoped via `ContextVar`, so concurrent loads with conflicting concept names (e.g., two bundles that both define `Result` with different fields) don't cross-contaminate — jobs, and any other load sharing the process, a validate included.!!! warning "Known backend limitation: StuffArtefact in dry-run"On a host runtime whose data converter serializes working memory for internal templating activities (Temporal's `act_jinja2_gen_text`, dispatched by PipeCondition and PipeCompose), dry-run mode can fail: working memory then holds `StuffArtefact` debug objects that are not JSON-serializable. PipeSequence and PipeParallel are unaffected — they dispatch child pipes without internal templating activities. This is a backend-specific concern; see our Temporal plugin's own docs for details and fix direction.diff --git a/docs/under-the-hood/runtime-bridge-and-transport.md b/docs/under-the-hood/runtime-bridge-and-transport.mdindex ef2982c34..f77e32748 100644--- a/docs/under-the-hood/runtime-bridge-and-transport.md+++ b/docs/under-the-hood/runtime-bridge-and-transport.md@@ -116,13 +116,15 @@ Because delivery renders from the raw dict (`pipelex/pipe_run/delivery_executor.## Per-call scoping-A single worker may process many concurrent jobs. If two jobs define a concept named `Result` with different fields, they must not share a `ClassRegistry` or `Library` — otherwise the second registration overwrites the first and silently corrupts data. Each job therefore creates its own scoped state:+A single process may handle many concurrent jobs — and, in a server, many concurrent requests that are not jobs at all. If two of them define a concept named `Result` with different fields, they must not share a `ClassRegistry` or `Library`: structure classes are registered under a name key, so the second registration overwrites the first and the two silently swap schemas and output types. The isolation is therefore structural rather than something a caller opts into — every `Library` the manager opens carries its own registry:-1. **ClassRegistry** — a fresh `ClassRegistry` pre-seeded from the global registry (which holds the base classes from `PIPELEXPATH`). The crate's dynamic classes register here, never in the global registry.-2. **Library** — a fresh `Library` (`library_manager.open_fresh_library()`) with that `ClassRegistry` attached, set as current via a `ContextVar` keyed by the run id. Run-id keying (not job/workflow id) is deliberate: a reused workflow id across retries/resets could otherwise let a closed predecessor's cleanup tear down a live successor's library on the same worker.+1. **ClassRegistry** — `library_manager.open_library()` attaches a fresh `ClassRegistry` to every library it creates, pre-seeded from the global registry (which holds the base classes from `PIPELEXPATH`). A load's dynamic classes register there, never in the global registry, and no caller can forget to ask for it.+2. **Library** — a fresh `Library` (`library_manager.open_fresh_library()`), set as current via a `ContextVar` keyed by the run id. Run-id keying (not job/workflow id) is deliberate: a reused workflow id across retries/resets could otherwise let a closed predecessor's cleanup tear down a live successor's library on the same worker.3. **Lookup chain** — `hub.get_class_registry()` reads the `ContextVar`, returns the scoped library's registry, and falls back to the global registry when no library is set (e.g. a data converter running outside the job scope — which is exactly why output uses deferred hydration).4. **Cleanup** — `library_manager.teardown(library_id)` drops the library and its registry; the `ContextVar` is reset. No manual GC needed.+One consequence is worth stating for host code: a structure class registered while a library is current lands in *that library's* registry and is gone when it is torn down. A Python structure class that every load should see must be registered before any library is opened — which is what importing it at boot, or loading it from a library directory into the library that uses it, already does.+The class-registry accessor and its library scoping (`pipelex/runtime_hub.py`, `pipelex/system/registries/class_registry_access.py`, `pipelex/interpreter_hub.py`, `pipelex/libraries/library.py`, `pipelex/libraries/library_manager.py`) is open core — the same machinery serves direct execution, the open runner, and any host-runtime plugin.---diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex 71434e5eb..2659db67a 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -27,12 +27,13 @@ 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 ConceptLibrary+from pipelex.interpreter_hub import clear_current_library, get_concept_library, get_library_managerfrom pipelex.mthds_parsing.exceptions import MthdsParserErrorfrom pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.exceptions import PipelineExecutionError+from pipelex.pipeline.execution_seams import acquire_libraryfrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.cost_report_renderer import render_cost_report_for_outputfrom pipelex.runtime_hub import get_console, get_telemetry_manager@@ -47,6 +48,7 @@ from pipelex.tools.tabular.csv_codec import assert_supported_table_suffix, csv_ffrom pipelex.tools.tabular.exceptions import CsvErrorif TYPE_CHECKING:+ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.stuffs.stuff_content import StuffContentCOMMAND = "run"@@ -75,6 +77,35 @@ def validate_run_flag_combination(*, dry_run: bool, mock_usage: bool, mock_inputraise typer.Exit(1)+def _resolve_row_model_for_empty_result(+ *,+ concept: Concept,+ bundle_path: str | None,+ mthds_content: str | None,+ library_dir: list[str] | None,+) -> type[StuffContent]:+ """Resolve the CSV row model for a run that produced no rows, by reloading its bundle.++ A run whose main output is an empty list leaves no instance to read the row class off, and the+ run's own library — which owned the ClassRegistry holding its generated structure classes — is+ torn down by the time ``--save-csv`` runs. Reloading the same bundle into a throwaway library+ regenerates the declared concept's structure class under the same name and fields, which is what+ the header needs. The load inputs are the ones handed to the runner just above, so the two see+ the same bundle. The library is torn down again immediately; only the resolved class survives.+ """+ library_id, _main_pipe = acquire_library(+ library_id="",+ library_dirs=library_dir,+ mthds_contents=[mthds_content] if mthds_content else None,+ bundle_uris=[bundle_path] if bundle_path else None,+ )+ try:+ return get_concept_library().get_structure_class(concept=concept)+ finally:+ clear_current_library()+ get_library_manager().teardown(library_id=library_id)++async def _execute_run(*,pipe_code: str | None,@@ -337,19 +368,32 @@ async def _execute_run(csv_list_content = cast("ListContent[StuffContent]", csv_content)# expanduser so a quoted/`=`-form `~/out.csv` writes to the home dir, not a literal `./~` dir.csv_path = Path(save_csv).expanduser()- # A CSV-save failure (output concept with no structure class, non-flat output, write error) is- # framed as a --save-csv failure, not a pipeline failure — the pipeline already succeeded.- # 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).+ # A CSV-save failure (output concept with no structure class, non-flat output, a failed bundle+ # reload, write error) is framed as a --save-csv failure, not a pipeline failure — the pipeline+ # already succeeded. Every PipelexError raised in this block (the codec's CsvError, a reload's+ # LibraryError) would otherwise read as "Failed to execute pipeline" under execute_run's generic+ # `except PipelexError`; ConceptValueError (a ValueError) and OSError would escape as a raw traceback.try:- # 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)+ # Resolving the row model is the one post-run step that needs the run's library, and+ # `runner.execute` tore that library down on its way out — along with the ClassRegistry its+ # dynamically generated structure classes were registered in. So there is no ambient registry+ # left to resolve `<domain>__<Concept>` by name against, and the model is recovered two ways:+ # from the rows the run produced (each is an instance of exactly the class the pipeline+ # structured its output into), and — for an empty result, which has no instance to ask —+ # by reloading the bundle into a throwaway library just long enough to resolve the declared+ # concept's class. The reload is what keeps `--save-csv` writing a correct header-only file+ # for a run that produced no rows. Its failures are ConceptValueError/PipelexError, framed as+ # a save-csv failure by the guard below rather than escaping as a pipeline failure.+ csv_row_model: type[StuffContent]+ if csv_list_content.items:+ csv_row_model = type(csv_list_content.items[0])+ else:+ csv_row_model = _resolve_row_model_for_empty_result(+ concept=csv_main_stuff.concept,+ bundle_path=bundle_path,+ mthds_content=mthds_content,+ library_dir=library_dir,+ )# 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)@@ -357,7 +401,7 @@ async def _execute_run(# nested target (e.g. reports/2026/out.csv) doesn't fail late after the run completed.csv_path.parent.mkdir(parents=True, exist_ok=True)csv_from_list_content(csv_list_content, row_model=csv_row_model, path=csv_path)- except (CsvError, ConceptValueError, OSError) as csv_exc:+ except (ConceptValueError, PipelexError, OSError) as csv_exc:typer.secho(f"Failed to --save-csv to '{save_csv}': {csv_exc}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from csv_exclog.verbose(f"Main stuff CSV saved to: {save_csv}")diff --git a/pipelex/libraries/library.py b/pipelex/libraries/library.pyindex 6b109429f..92b42ee15 100644--- a/pipelex/libraries/library.py+++ b/pipelex/libraries/library.py@@ -155,6 +155,12 @@ class Library(BaseModel):self.concept_library.teardown()self.domain_library.teardown()self.loaded_mthds_paths = []+ # Drop this library's dynamically generated structure classes with the library itself.+ # The registry object would be garbage anyway once the manager forgets the Library, but+ # a caller holding its own reference must not keep resolving a torn-down library's classes.+ if self._class_registry is not None:+ self._class_registry.teardown()+ self._class_registry = Nonedef validate_library(self) -> None:self.validate_domain_library_with_libraries()diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex db4ced3b4..11ff77802 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -5,6 +5,7 @@ from pathlib import Pathfrom typing import TYPE_CHECKINGfrom kajson.class_registry import ClassRegistry+from kajson.kajson_manager import KajsonManagerfrom mthds.package.dependency_resolver import ResolvedDependency, determine_exported_pipes, resolve_all_dependenciesfrom mthds.package.discovery import find_package_manifestfrom mthds.package.exceptions import DependencyResolveError, ManifestError@@ -187,10 +188,47 @@ class LibraryManager(LibraryManagerAbstract):the_library = self._libraries[library_id]else:the_library = LibraryFactory.make_empty()+ the_library.set_class_registry(self._make_library_class_registry())self._libraries[library_id] = the_libraryreturn library_id, the_library+ @classmethod+ def _make_library_class_registry(cls) -> ClassRegistry:+ """Build the per-library ClassRegistry every manager-opened Library carries.++ Concept materialization registers dynamically generated structure classes under a+ *name* key (``domain__Concept``), and kajson's ``register_class`` overwrites an existing+ key unconditionally. A library that carried no registry of its own resolved through to the+ process-global registry, which made two libraries loading the same concept ref share one+ slot: whichever loaded last owned the class, and neither teardown removed it. Two+ contaminations followed — a later load reusing an earlier one's class (``ConceptFactory``+ reuses a registered class for a basic concept), and two concurrent loads overwriting each+ other at any ``await`` between generation and use. Both crossed request boundaries wherever+ one process serves several bundles, and the generated classes are what+ ``pipe_io_contracts`` renders schemas from.++ Giving the registry to the library at open time makes the isolation structural rather than+ opt-in: the classes a load generates live and die with the library that asked for them, and+ the process-global registry keeps only what boot put there.++ The seed is a snapshot of the process-global registry — the boot-time core and test models,+ plus anything registered outside any library — taken from ``KajsonManager`` rather than from+ the ambient ``get_class_registry()``: opening a library while another one is current must not+ copy that library's dynamic classes into the new one. Being a snapshot, it is taken at open+ time: a class registered globally *after* a library is open is not visible to that library.+ Nothing in-tree does that — boot registers before any library exists, and every load-time+ registration runs under the library it is loading into — so the ordering that would make it+ matter is a host registering classes mid-flight, which is a case for registering them at+ startup instead.+ """+ library_class_registry = ClassRegistry()+ # The global registry really is empty before boot registers anything; kajson's+ # register_classes_dict is a no-op on an empty dict, so a library opened there comes out+ # carrying its own empty registry rather than failing to open.+ library_class_registry.register_classes_dict(KajsonManager.get_class_registry().get_classes_dict())+ return library_class_registry+@overridedef open_fresh_library(self, library_id: str) -> Library:try:diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex c3f299909..ab627afd3 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -511,6 +511,14 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# --- Tools ----------------------------------------------------------------------------self.class_registry = class_registry or ClassRegistry()+ # A read through ``KajsonManager.get_class_registry()`` before any boot — the scoped accessor's+ # global fallback, or a library opened on a bare ``LibraryManager`` — instantiates the singleton+ # around an empty registry, and ``KajsonManager(class_registry=…)`` would then hand that manager+ # back and silently discard this boot's registry: the core models would land where nothing+ # resolves, and the boot would still report ready. So any pre-boot manager is dropped first. A+ # *live* boot's manager cannot be the one dropped here: the guard in ``__init__`` and ``make()``+ # already refused a second boot, and a failed or torn-down boot released its own manager.+ KajsonManager.teardown()self.kajson_manager = KajsonManager(class_registry=self.class_registry)self.func_registry = func_registry or FuncRegistry()diff --git a/pipelex/runtime_bridge/primitives/rehydration.py b/pipelex/runtime_bridge/primitives/rehydration.pyindex 58be5537e..8a81c8bbd 100644--- a/pipelex/runtime_bridge/primitives/rehydration.py+++ b/pipelex/runtime_bridge/primitives/rehydration.py@@ -1,8 +1,5 @@from typing import Any-from kajson.class_registry import ClassRegistry-from kajson.kajson_manager import KajsonManager-from pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.interpreter_hub import get_library_manager, set_current_libraryfrom pipelex.libraries.library_crate import LibraryCrate@@ -25,22 +22,17 @@ def rehydrate_library_and_memory(Steps, in order (order matters):- 1. Create a per-run ``ClassRegistry`` pre-seeded from the global one, so this run's dynamically- generated concept classes register into an isolated registry rather than leaking globally.- 2. Open a fresh library under ``library_id`` and attach the registry; make it the current library- so the factory and hydrator resolve classes against it.- 3. ``load_from_crate`` — rebuilds domains/concepts/pipes and registers the dynamic classes.- 4. Hydrate the working memory (needs step 3 to have registered the classes it references).+ 1. Open a fresh library under ``library_id`` and make it the current library, so the factory and+ hydrator resolve classes against it. The library arrives carrying its own ``ClassRegistry``+ pre-seeded from the process-global one (``LibraryManager.open_library`` attaches it), which is+ what keeps this run's dynamically generated concept classes out of every other library.+ 2. ``load_from_crate`` — rebuilds domains/concepts/pipes and registers the dynamic classes.+ 3. Hydrate the working memory (needs step 2 to have registered the classes it references).Returns the hydrated WorkingMemory, or None when there was nothing to hydrate."""- global_registry = KajsonManager.get_class_registry()- run_registry = ClassRegistry()- run_registry.register_classes_dict(global_registry.get_classes_dict())-library_manager = get_library_manager()- library = library_manager.open_fresh_library(library_id=library_id)- library.set_class_registry(run_registry)+ library_manager.open_fresh_library(library_id=library_id)set_current_library(library_id=library_id)library_manager.load_from_crate(library_id=library_id, crate=crate)diff --git a/pipelex/system/registries/class_registry_access.py b/pipelex/system/registries/class_registry_access.pyindex 79b57605b..9230bf3f6 100644--- a/pipelex/system/registries/class_registry_access.py+++ b/pipelex/system/registries/class_registry_access.py@@ -37,18 +37,22 @@ Note what that seam does **not** yet buy. `ConceptLibrary.get_structure_class` ccontext* selects, not against one the provider carries — a `ConceptLibrary` holds no registry of itsown (the per-library `ClassRegistry` lives on `Library`). Today the two cannot disagree: theinterpreter 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+``_library_id`` ContextVar, and every library the manager holds carries a registry of its own, so a+provider read and a registry read of that one variable land on the same library. 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.-Scoping: a run may pin a per-library ClassRegistry (a workflow's own registry) rather than the-process-global Kajson one. Resolving *which* library is current is interpreter-layer knowledge, so-the kernel layer holds only a slot — ``pipelex.interpreter_hub.set_interpreter_hub`` installs the real-resolver at boot. Unresolved, or with no library pinned, callers get the process-global registry.+Scoping: every library ``LibraryManager.open_library`` hands out carries its own ClassRegistry,+pre-seeded from the process-global Kajson one, so a load's dynamically generated structure classes+live and die with the library that asked for them instead of sharing one name-keyed process-global+slot with every other request. Resolving *which* library is current is interpreter-layer knowledge,+so the kernel layer holds only a slot — ``pipelex.interpreter_hub.set_interpreter_hub`` installs the+real resolver at boot. With no library pinned, an unresolved slot, or a pinned id the manager no+longer holds, callers get the process-global registry — which, after boot, holds only what boot and+non-library callers put there."""from collections.abc import Callablediff --git a/tests/integration/pipelex/cli/test_save_csv_empty_result_row_model.py b/tests/integration/pipelex/cli/test_save_csv_empty_result_row_model.pynew file mode 100644index 000000000..170cbc18d--- /dev/null+++ b/tests/integration/pipelex/cli/test_save_csv_empty_result_row_model.py@@ -0,0 +1,59 @@+"""Pin the real reload behind ``--save-csv`` on a run that produced no rows.++The run's own library — and the ``ClassRegistry`` holding the structure classes its bundle+generated — is torn down before the CSV step runs, and an empty result leaves no instance to read+the row class off. The CLI therefore reloads the same bundle into a throwaway library just long+enough to resolve the declared concept's structure class, which is what keeps a zero-row run writing+a correct header-only file. Exercised here against a real load rather than a mock, so a class that+the reload cannot actually regenerate fails the test.+"""++from __future__ import annotations++import pytest++from pipelex.cli.commands.run._run_core import _resolve_row_model_for_empty_result # pyright: ignore[reportPrivateUsage]+from pipelex.interpreter_hub import clear_current_library, get_concept_library, get_library_manager+from pipelex.pipeline.execution_seams import acquire_library+from pipelex.tools.tabular.csv_codec import flat_field_names++_FLAT_ROW_MTHDS = """+domain = "csv_empty_result"+description = "Bundle whose row concept is generated from a structure table"++[concept.PersonSummary]+description = "A flat person summary"++[concept.PersonSummary.structure]+name = { type = "text", description = "The person's name" }+country = { type = "text", description = "The person's country" }++[pipe.summarize_people]+type = "PipeLLM"+description = "Summarize people"+inputs = { doc = "Text" }+output = "PersonSummary[]"+prompt = "Summarize $doc"+"""++[email protected](loop_scope="class")+class TestSaveCsvEmptyResultRowModel:+ async def test_the_reload_resolves_a_generated_structure_class(self) -> None:+ # Load once to obtain the concept the run's output stuff would carry, then drop that library+ # entirely — standing in for the run library the runner tears down before the CSV step.+ library_id, _main_pipe = acquire_library(library_id="", mthds_contents=[_FLAT_ROW_MTHDS])+ try:+ row_concept = get_concept_library().get_required_concept(concept_ref="csv_empty_result.PersonSummary")+ finally:+ clear_current_library()+ get_library_manager().teardown(library_id=library_id)++ row_model = _resolve_row_model_for_empty_result(+ concept=row_concept,+ bundle_path=None,+ mthds_content=_FLAT_ROW_MTHDS,+ library_dir=None,+ )++ assert flat_field_names(row_model) == ["name", "country"], "The header a zero-row CSV would carry"diff --git a/tests/integration/pipelex/fixtures/pipe_job_helpers.py b/tests/integration/pipelex/fixtures/pipe_job_helpers.pyindex a5a3a84ca..4e15a10b0 100644--- a/tests/integration/pipelex/fixtures/pipe_job_helpers.py+++ b/tests/integration/pipelex/fixtures/pipe_job_helpers.py@@ -65,7 +65,6 @@ def pipe_job_from_library(load_fn: Callable[[str], None],pipe_code: str,pipe_run_mode: PipeRunMode = PipeRunMode.DRY,- isolated_registry: bool = False,working_memory_builder: Callable[[PipeAbstract], WorkingMemory] | None = None,) -> Generator[PipeJob, None, None]:"""Shared fixture skeleton: open library, load via load_fn, build PipeJob, yield, teardown.@@ -74,28 +73,16 @@ def pipe_job_from_library(load_fn: Callable that loads content into the library.pipe_code: The pipe code to look up after loading.pipe_run_mode: Dry, mock, or live execution mode.- isolated_registry: When True, gives the library a scoped ClassRegistry so dynamic- concept classes are registered there instead of the global KajsonManager- registry. This simulates a clean worker process where the global registry- has no dynamic classes, forcing the deferred hydration path.working_memory_builder: Optional builder invoked with the looked-up pipe toproduce a pre-populated working memory (e.g. mock inputs synthesized from``pipe.needed_inputs()``). When omitted, the job carries an empty workingmemory."""library_manager = get_library_manager()- library_id, library = library_manager.open_library()- if isolated_registry:- from kajson.class_registry import ClassRegistry # ruff: ignore[import-outside-top-level]- from kajson.kajson_manager import KajsonManager # ruff: ignore[import-outside-top-level]-- # Pre-seed from global so core framework classes (PipeSequenceFactory, etc.)- # are available. Dynamic concept classes added during load_fn() will go to- # this scoped registry instead of the global, keeping the global clean.- global_registry = KajsonManager.get_class_registry()- scoped_registry = ClassRegistry()- scoped_registry.register_classes_dict(global_registry.get_classes_dict())- library.set_class_registry(scoped_registry)+ # The library arrives carrying its own ClassRegistry seeded from the process-global one+ # (``open_library`` attaches it), so the dynamic concept classes ``load_fn`` registers die+ # with the library and never reach the global registry.+ library_id, _library = library_manager.open_library()set_current_library(library_id=library_id)pipeline_run_id = _make_unique_pipeline_run_id()@@ -118,7 +105,6 @@ def pipe_job_from_bundle(bundle_file: str,pipe_code: str,pipe_run_mode: PipeRunMode = PipeRunMode.DRY,- isolated_registry: bool = False,) -> Generator[PipeJob, None, None]:"""Build a PipeJob by loading a bundle from an mthds file."""@@ -127,4 +113,4 @@ def pipe_job_from_bundle(blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content)get_library_manager().load_from_blueprints(library_id=library_id, blueprints=[blueprint])- yield from pipe_job_from_library(_load, pipe_code=pipe_code, pipe_run_mode=pipe_run_mode, isolated_registry=isolated_registry)+ yield from pipe_job_from_library(_load, pipe_code=pipe_code, pipe_run_mode=pipe_run_mode)diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.pyindex 1d95088d4..bbfe8d3b5 100644--- a/tests/integration/pipelex/pipeline/test_input_form.py+++ b/tests/integration/pipelex/pipeline/test_input_form.py@@ -23,6 +23,7 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, Any, castimport pytest+from kajson.kajson_manager import KajsonManagerfrom pydantic import Fieldfrom pipelex.core.memory.exceptions import ListWhereSingularError@@ -41,7 +42,6 @@ from pipelex.interpreter_hub import (from pipelex.pipeline.input_form import FieldKind, InputFormField, build_input_formfrom pipelex.pipeline.pipe_io_contracts import IOMultiplicity, build_pipe_io_contractsfrom pipelex.pipeline.validate_bundle import validate_bundle-from pipelex.system.registries.class_registry_access import get_class_registryfrom tests.helpers.input_form import as_list, fields_by_nameif TYPE_CHECKING:@@ -586,14 +586,23 @@ prompt = \"\"\"class TestKindAssignmentTable:async def _derive_kind_table(self, load_empty_library: Callable[[], str]) -> dict[str, PipeInputFormDescriptor]:outer_library_id = load_empty_library()+ # Register into the *process-global* registry, not the ambient one: these classes stand in+ # for structure classes a Python module put in the process, and `validate_bundle` opens its+ # own library, whose registry is seeded from the global one. Registering through+ # `get_class_registry()` here would put them in the enclosing empty library's registry,+ # where the validate library cannot see them.+ registry = KajsonManager.get_class_registry()try:- registry = get_class_registry()registry.register_class(InputFormConstrainedPayload)registry.register_class(InputFormPartlyMappablePayload)registry.register_class(InputFormFieldLessPayload)result = await validate_bundle(mthds_contents=[_KIND_TABLE_MTHDS])return build_input_form(result.pipes)finally:+ # Unregister so the stand-ins do not outlive this test and seed every library opened after it.+ registry.unregister_class(InputFormConstrainedPayload)+ registry.unregister_class(InputFormPartlyMappablePayload)+ registry.unregister_class(InputFormFieldLessPayload)_teardown_validation_library(outer_library_id)async def test_remaining_natives_complete_the_table(self, load_empty_library: Callable[[], str]) -> None:diff --git a/tests/integration/pipelex/pipeline/test_library_class_registry_isolation.py b/tests/integration/pipelex/pipeline/test_library_class_registry_isolation.pynew file mode 100644index 000000000..ee3a25ad7--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_library_class_registry_isolation.py@@ -0,0 +1,164 @@+"""Pin that a library's dynamically generated structure classes never escape into another library.++Concept materialization generates a structure class per class-backed concept and registers it under+a *name* key (``domain__Concept``). While a library carried no class registry of its own, every load+in the process resolved through to the one process-global registry, so two loads of the same concept+ref shared a single slot. Two contaminations followed, and both are reproduced here because both are+reachable from one process serving several bundles — the API's validate route, the hosted dry-validate+activity, every crate route:++- **Sequential reuse**, needing no concurrency at all: ``ConceptFactory`` reuses an already-registered+ class for a *basic* concept, so a later bundle declaring ``Summary`` with only a description inherited+ an earlier bundle's structured ``Summary`` — in its IO contracts and in the class its ``PipeLLM``+ would structure output against.+- **Concurrent overwrite**, needing a real suspension point inside the validate window: two loads+ generating the same ref overwrite each other's registration, and whichever landed last is what both+ render schemas from. A ``PipeParallel`` fan-out supplies the ``await`` (the dry-run sweep of a plain+ ``PipeLLM`` chain never yields).++Both are closed structurally by ``LibraryManager.open_library`` attaching a per-library ``ClassRegistry``+seeded from the process-global one, so these tests fail loudly if that ever regresses to opt-in. The+invariant itself is pinned directly in ``tests/unit/pipelex/test_class_registry_scoping.py``.+"""++from __future__ import annotations++import asyncio+import json+from typing import Any, cast++import pytest+from kajson.kajson_manager import KajsonManager++from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager+from pipelex.pipeline.validate_bundle import validate_bundle+from pipelex.pipeline.validate_in_process import validate_bundles_in_process+from pipelex.runtime_hub import get_class_registry++_STRUCTURED_SUMMARY_MTHDS = """+domain = "registry_isolation"+description = "Bundle whose Summary carries a private structure"++[concept.Summary]+description = "A structured summary"++[concept.Summary.structure]+first_tenant_field = { type = "text", description = "The first tenant's private field" }++[pipe.consume_summary]+type = "PipeLLM"+description = "Consume a summary"+inputs = { summary = "Summary" }+output = "Text"+prompt = "Summarize $summary"+"""++_BASIC_SUMMARY_MTHDS = """+domain = "registry_isolation"+description = "Bundle whose Summary is declared with a description only"++[concept.Summary]+description = "A plain summary"++[pipe.make_summary]+type = "PipeLLM"+description = "Make a summary"+inputs = { doc = "Text" }+output = "Summary"+prompt = "Summarize $doc"+"""+++def _fan_out_mthds(*, field_name: str, tag: str) -> str:+ """A bundle whose dry-run sweep really yields: PipeParallel fans out through ``asyncio.gather``."""+ return f"""+domain = "registry_isolation"+description = "Fan-out bundle {tag}"++[concept.Summary]+description = "A summary ({tag})"++[concept.Summary.structure]+{field_name} = {{ type = "text", description = "The {tag} tenant's private field" }}++[pipe.branch_one_{tag}]+type = "PipeLLM"+description = "Branch one"+inputs = {{ summary = "Summary" }}+output = "Text"+prompt = "One: $summary"++[pipe.branch_two_{tag}]+type = "PipeLLM"+description = "Branch two"+inputs = {{ summary = "Summary" }}+output = "Text"+prompt = "Two: $summary"++[pipe.fan_{tag}]+type = "PipeParallel"+description = "Fan out over the summary"+inputs = {{ summary = "Summary" }}+output = "Composite"+add_each_output = true+branches = [+ {{ pipe = "branch_one_{tag}", result = "one" }},+ {{ pipe = "branch_two_{tag}", result = "two" }},+]+"""+++def _schema_property_names(json_schema: dict[str, Any]) -> list[str]:+ """The sorted field names of a structure class's JSON Schema, as the IO contract carries it."""+ properties = cast("dict[str, Any]", json_schema.get("properties") or {})+ return sorted(properties)+++def _teardown_validation_library() -> None:+ """Tear down the library ``validate_bundle`` leaves open on success."""+ validation_library_id = get_current_library_id_or_none()+ clear_current_library()+ if validation_library_id is not None:+ get_library_manager().teardown(library_id=validation_library_id)+++class TestLibraryClassRegistryIsolation:+ @pytest.mark.asyncio(loop_scope="class")+ async def test_a_basic_concept_does_not_inherit_an_earlier_bundles_structure_class(self) -> None:+ """A later basic ``Summary`` must not reuse an earlier bundle's structured ``Summary`` class."""+ first_report = await validate_bundles_in_process(mthds_contents=[_STRUCTURED_SUMMARY_MTHDS])+ first_schema = first_report.pipe_io_contracts["registry_isolation.consume_summary"].inputs["summary"].json_schema+ assert _schema_property_names(first_schema) == ["first_tenant_field"]++ second_report = await validate_bundles_in_process(mthds_contents=[_BASIC_SUMMARY_MTHDS])+ second_dump = json.dumps(second_report.input_form["registry_isolation.make_summary"].model_dump(mode="json"))+ assert "first_tenant_field" not in second_dump++ # The class the second bundle's PipeLLM would structure its output against, read inside the+ # second bundle's own library window (validate_bundle leaves the library open on success).+ await validate_bundle(mthds_contents=[_BASIC_SUMMARY_MTHDS])+ try:+ structure_class = get_class_registry().get_required_subclass(+ name="registry_isolation__Summary",+ base_class=StuffContent,+ )+ assert "first_tenant_field" not in structure_class.model_fields+ finally:+ _teardown_validation_library()++ # And nothing from either bundle was left behind in the process-global registry.+ assert not KajsonManager.get_class_registry().has_class(name="registry_isolation__Summary")++ @pytest.mark.asyncio(loop_scope="class")+ async def test_concurrent_validates_do_not_overwrite_each_others_structure_class(self) -> None:+ """Two validates yielding inside their windows must each keep their own generated class."""+ first_report, second_report = await asyncio.gather(+ validate_bundles_in_process(mthds_contents=[_fan_out_mthds(field_name="alpha_field", tag="alpha")]),+ validate_bundles_in_process(mthds_contents=[_fan_out_mthds(field_name="gamma_field", tag="gamma")]),+ )++ first_schema = first_report.pipe_io_contracts["registry_isolation.fan_alpha"].inputs["summary"].json_schema+ second_schema = second_report.pipe_io_contracts["registry_isolation.fan_gamma"].inputs["summary"].json_schema+ assert _schema_property_names(first_schema) == ["alpha_field"]+ assert _schema_property_names(second_schema) == ["gamma_field"]diff --git a/tests/unit/pipelex/cli/test_run_core_execution.py b/tests/unit/pipelex/cli/test_run_core_execution.pyindex b15aade8a..cb84723ee 100644--- a/tests/unit/pipelex/cli/test_run_core_execution.py+++ b/tests/unit/pipelex/cli/test_run_core_execution.py@@ -19,7 +19,9 @@ from rich.console import Consolefrom pipelex.cli.commands.run._run_core import _execute_run # pyright: ignore[reportPrivateUsage]from pipelex.core.concepts.exceptions import ConceptValueErrorfrom pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.number_content import NumberContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.libraries.exceptions import LibraryErrorif TYPE_CHECKING:from collections.abc import Coroutine@@ -75,14 +77,27 @@ 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."""+ def _mock_structure_class(self, mocker: MockerFixture, *, resolves_to: Any = None, raises: Exception | None = None) -> SimpleNamespace:+ """Stand in for the throwaway library reload that resolves the CSV row class on an empty result.++ Returns the reload seams (``acquire``, ``clear``, ``manager``) so a test can assert the+ throwaway library was opened with the run's own load inputs and torn down again.+ """concept_library_mock = mocker.MagicMock()if raises is not None:concept_library_mock.get_structure_class.side_effect = raiseselse: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)+ acquire_mock = mocker.patch("pipelex.cli.commands.run._run_core.acquire_library", return_value=("reload-library", None))+ mocker.patch("pipelex.cli.commands.run._run_core.get_concept_library", return_value=concept_library_mock)+ clear_mock = mocker.patch("pipelex.cli.commands.run._run_core.clear_current_library")+ manager_mock = mocker.patch("pipelex.cli.commands.run._run_core.get_library_manager")+ return SimpleNamespace(acquire=acquire_mock, clear=clear_mock, manager=manager_mock)++ @staticmethod+ def _assert_reload_library_torn_down(reload: SimpleNamespace) -> None:+ reload.clear.assert_called_once_with()+ reload.manager.return_value.teardown.assert_called_once_with(library_id="reload-library")def _make_pipe_output(self,@@ -421,7 +436,10 @@ class TestRunCoreExecution:main_stuff.content = ListContent(items=[TextContent(text="row one")])pipe_output = self._make_pipe_output(mocker, main_stuff=main_stuff)self._mock_runner(mocker, pipe_output)- self._mock_structure_class(mocker, resolves_to=TextContent)+ # The row model is taken off the produced rows, not resolved by name: the run library that+ # owned the generated structure class is already torn down by the time this step runs. Point+ # the name lookup at a different class so a regression to it fails here rather than silently.+ self._mock_structure_class(mocker, resolves_to=NumberContent)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"@@ -430,19 +448,66 @@ class TestRunCoreExecution:csv_codec_mock.assert_called_once()assert csv_codec_mock.call_args.kwargs["path"] == csv_target+ assert csv_codec_mock.call_args.kwargs["row_model"] is TextContentassert csv_target.parent.is_dir()assert f"CSV saved to {csv_target}" in console.export_text()+ @pytest.mark.usefixtures("config_mock", "console")+ def test_save_csv_empty_result_resolves_the_row_model_by_reloading_the_bundle(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """An empty result has no row to read the class off, so the declared concept is resolved instead.++ This is what keeps a run that produced no rows writing a correct header-only file: the run's+ own library (and the registry holding its generated structure classes) is already torn down.+ """+ main_stuff = mocker.MagicMock()+ main_stuff.content = ListContent[TextContent](items=[])+ pipe_output = self._make_pipe_output(mocker, main_stuff=main_stuff)+ self._mock_runner(mocker, pipe_output)+ reload = 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")++ _run_async(_call_execute_run(save_csv=str(tmp_path / "out.csv"), library_dir=["libs"]))++ csv_codec_mock.assert_called_once()+ assert csv_codec_mock.call_args.kwargs["row_model"] is TextContent+ # The reload sees exactly the load inputs the run was handed, and is torn down again.+ assert reload.acquire.call_args.kwargs == {"library_id": "", "library_dirs": ["libs"], "mthds_contents": None, "bundle_uris": None}+ self._assert_reload_library_torn_down(reload)+@pytest.mark.usefixtures("config_mock", "console")def test_save_csv_concept_error_framed_as_csv_failure(self, mocker: MockerFixture, tmp_path: Path) -> None:- """A missing structure class on the output concept is a --save-csv failure."""+ """A missing structure class on the output concept is a --save-csv failure.++ An empty result is the one case with no produced row to read the model off, so it is the+ case that still falls back to resolving the concept's structure class by name.+ """main_stuff = mocker.MagicMock()- main_stuff.content = ListContent(items=[TextContent(text="row one")])+ main_stuff.content = ListContent[TextContent](items=[])+ pipe_output = self._make_pipe_output(mocker, main_stuff=main_stuff)+ self._mock_runner(mocker, pipe_output)+ reload = 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")))++ assert exc_info.value.exit_code == 1+ # The throwaway library does not outlive a failed resolution either.+ self._assert_reload_library_torn_down(reload)++ @pytest.mark.usefixtures("config_mock", "console")+ def test_save_csv_reload_failure_framed_as_csv_failure(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A bundle reload that fails on an empty result is a --save-csv failure, not a pipeline failure."""+ main_stuff = mocker.MagicMock()+ main_stuff.content = ListContent[TextContent](items=[])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"))+ reload = self._mock_structure_class(mocker, resolves_to=TextContent)+ reload.acquire.side_effect = LibraryError("reload failed")with pytest.raises(typer.Exit) as exc_info:_run_async(_call_execute_run(save_csv=str(tmp_path / "out.csv")))assert exc_info.value.exit_code == 1+ # acquire_library owns its own load-failure teardown, so nothing was left for the helper to drop.+ reload.manager.return_value.teardown.assert_not_called()diff --git a/tests/unit/pipelex/test_class_registry_scoping.py b/tests/unit/pipelex/test_class_registry_scoping.pyindex 89c79c3a1..cca151de1 100644--- a/tests/unit/pipelex/test_class_registry_scoping.py+++ b/tests/unit/pipelex/test_class_registry_scoping.py@@ -1,3 +1,5 @@+from unittest.mock import patch+from kajson.class_registry import ClassRegistryfrom kajson.kajson_manager import KajsonManagerfrom pydantic import BaseModel@@ -35,19 +37,67 @@ class TestHubClassRegistry:clear_current_library()library_manager.teardown(library_id=library_id)- def test_get_class_registry_library_without_registry_falls_back_to_global(self) -> None:- """_library_id set but library has no _class_registry -> falls back to global."""+ def test_an_opened_library_gets_its_own_registry_seeded_from_the_global_one(self) -> None:+ """open_library attaches a per-library registry — scoping is structural, never opt-in.++ Before this was the default, a library that carried no registry resolved through to the+ process-global one, which let two libraries share a single ``domain__Concept`` slot and+ disclose one bundle's generated structure class to another.+ """library_manager = get_library_manager()- library_id, _library = library_manager.open_library()- # Don't set a class_registry on the library+ library_id, library = library_manager.open_library()+ global_registry = KajsonManager.get_class_registry()++ library_registry = library.get_class_registry()+ assert library_registry is not None+ assert library_registry is not global_registry+ assert set(global_registry.get_classes_dict()) <= set(library_registry.get_classes_dict())set_current_library(library_id=library_id)+ try:+ assert get_class_registry() is library_registry+ finally:+ clear_current_library()+ library_manager.teardown(library_id=library_id)++ def test_opening_a_library_against_an_empty_global_registry_still_yields_one(self) -> None:+ """Seeding must survive an empty process-global registry.++ The global registry genuinely is empty between a teardown and the next boot, and a library+ opened there must come out carrying its own empty registry instead of failing to open+ (kajson's ``register_classes_dict`` used to raise ``IndexError`` on an empty dict).+ """+ library_manager = get_library_manager()+ with patch.object(KajsonManager, "get_class_registry", return_value=ClassRegistry()):+ library_id, library = library_manager.open_library()+ try:+ library_registry = library.get_class_registry()+ assert library_registry is not None+ assert library_registry.get_classes_dict() == {}+ finally:+ library_manager.teardown(library_id=library_id)++ def test_teardown_drops_the_library_registry_and_empties_a_held_reference(self) -> None:+ """A torn-down library's registry is gone, even through a reference a caller kept."""+ library_manager = get_library_manager()+ library_id, library = library_manager.open_library()+ held_registry = library.get_class_registry()+ assert held_registry is not None+ held_registry.register_class(ScopedModel, name="held__ScopedModel")++ library_manager.teardown(library_id=library_id)++ assert library.get_class_registry() is None+ assert not held_registry.has_class(name="held__ScopedModel")++ def test_get_class_registry_with_unknown_library_id_falls_back_to_global(self) -> None:+ """_library_id pinned to a library the manager does not hold -> falls back to global."""+ set_current_library(library_id="no-such-library")try:result = get_class_registry()assert result is KajsonManager.get_class_registry()finally:clear_current_library()- library_manager.teardown(library_id=library_id)def test_library_class_registry_not_in_model_dump(self) -> None:"""Library._class_registry (PrivateAttr) is not included in model_dump() output."""diff --git a/tests/unit/pipelex/test_runtime_boot_pre_boot_registry_read.py b/tests/unit/pipelex/test_runtime_boot_pre_boot_registry_read.pynew file mode 100644index 000000000..f8bd2f905--- /dev/null+++ b/tests/unit/pipelex/test_runtime_boot_pre_boot_registry_read.py@@ -0,0 +1,42 @@+"""A class-registry read before any boot must not starve the next boot's global registry.++``KajsonManager.get_class_registry()`` instantiates the singleton when none exists, around an empty+``ClassRegistry``. That read is one call away from any pre-boot code: the scoped accessor+``pipelex.runtime_hub.get_class_registry`` falls back to it when no library is pinned, and+``LibraryManager.open_library`` seeds every library's registry from it. ``KajsonManager`` is a+``MetaSingleton``, so the boot's own ``KajsonManager(class_registry=…)`` would hand that pre-boot+manager back and discard the boot's registry — the core models then land where nothing resolves,+while the boot still reports ready. The boot drops any pre-boot manager before constructing its own.+"""++from kajson.kajson_manager import KajsonManager++from pipelex.pipelex import Pipelex+from pipelex.runtime_hub import get_class_registry+from pipelex.system.runtime import IntegrationMode, runtime_manager+++def _test_integration_mode() -> IntegrationMode:+ """The boot mode the session conftest uses, so a re-boot here matches the one it replaces."""+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST+++class TestPreBootRegistryRead:+ def test_a_pre_boot_registry_read_does_not_starve_the_next_boot(self) -> None:+ Pipelex.teardown_if_needed()+ try:+ # The pre-boot read, through the same accessor any pre-boot caller would use.+ pre_boot_registry = get_class_registry()+ assert not pre_boot_registry.has_class(name="TextContent"), "no boot has registered the core models yet"+ assert KajsonManager.get_class_registry() is pre_boot_registry, "the read instantiated the singleton"++ pipelex = Pipelex.make(integration_mode=_test_integration_mode())++ served_registry = KajsonManager.get_class_registry()+ assert served_registry is pipelex.class_registry, "the boot must serve its own registry, not the pre-boot one"+ assert served_registry.has_class(name="TextContent")+ assert get_class_registry() is served_registry+ finally:+ # Restore what the module fixture set up, so its teardown is sane.+ Pipelex.teardown_if_needed()+ Pipelex.make(integration_mode=_test_integration_mode())diff --git a/wip/inputs/provider-scoped-class-resolution.md b/wip/inputs/provider-scoped-class-resolution.mdindex 27673961c..7ed31a576 100644--- a/wip/inputs/provider-scoped-class-resolution.md+++ b/wip/inputs/provider-scoped-class-resolution.md@@ -15,9 +15,9 @@**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.+**Every library the manager holds carries a registry.** `LibraryManager.open_library` attaches one at open time, seeded from the process-global registry, so `get_library_class_registry` answers for any library that can become current. (Before that was the default, the pairing argument was narrower: only `runtime_bridge/primitives/rehydration.py` installed a registry, and it set the registry and the ContextVar in adjacent statements on the same library.)-**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.+**The only non-hub provider used to depend on the ambient read, and no longer does.** `cli/commands/run/_run_core.py`'s `--save-csv` step used `ConceptLibrary.make_empty()` *after* the run library was torn down, precisely so the lookup landed on the process-global registry that still held the generated classes. Once `open_library` began attaching a per-library registry, the generated classes went with the run library, and that site now takes the row model off the produced rows — each is an instance of exactly the class the pipeline structured its output into. The name lookup remains only for an empty result, which has no instance to ask.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.@@ -30,11 +30,11 @@ The branch asserted a scoping property in three places. Two were docstrings writ1. 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.+4. ~~A `set_class_registry` call site appears that is not paired with `set_current_library` on the same library.~~ Moot: `open_library` now attaches a registry to every library, so a library that becomes current always has one to resolve. What would revive the concern is a caller that *replaces* a library's registry with one belonging to a different 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.+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()` 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