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.
feature/Concept-object-leaks-onto · L-260918-2ddf41 (#1211)
Louis Choquel3de404702a2e
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 30c72f1ce..1eab82a67 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:0f04ef9927c69cc0d91d68490a0dfe4f65840553414fd92773028b3192630db4"+digest = "sha256:106c7b09f674096aaa1c469914b38a86faf7dcb8919ae1d13cedafa12904a481"reviewed_by = "Claude (Opus 5)"-reviewed_at = "2026-09-16T08:54:19Z"-rationale = "Round-2 review fix in graph_cmd: the refused-spec handler now escapes its message before handing it to log.error and console.print, so a user path holding square brackets prints as written instead of being swallowed or raising MarkupError; no flag, option, exit code or output contract moved. Listed docs/tools/cli: it has no page for graph render. Grepped pipelex/cli/agent_cli/CLAUDE.md: its graph mentions are the agent run and validate graph options, none of which this touches. Nothing stale."+reviewed_at = "2026-09-18T19:26:40Z"+rationale = "The stdin resolver's shape refusal moved off the JSONDecodeError label onto its own synthetic StdinEnvelopeShapeError, with a matching AGENT_ERROR_HINTS/AGENT_ERROR_DOMAINS entry. docs/tools/cli/agent-cli.md's stdin paragraph now names that label and why it is not a decode error, and its --with-memory line now says the receiving method must declare the same <domain>.<Code>, since the ref travels with its domain and a method declaring another one refuses it. The error envelope block documents error_type generically and needed no change, and pipelex/cli/agent_cli/CLAUDE.md already describes synthetic labels as the sanctioned mechanism for a failure with no exception class, which is exactly what this is."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -12,7 +12,7 @@ rationale = "Round-2 review fix in graph_cmd: the refused-spec handler now escap"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:cb8338c09a7b5dee6088551c156d69dab613213a""pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:ba63ff317613e9be35677fca949f0991a6f6c47e"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:a1ffa37559c51d6272d0ec26bfbd073303233096"+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:3dc0283ef1daee4e17183b01f8a5c9d92f2688af""pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0""pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:ff33446143044332983a0cb7b204b8eca349795a""pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -45,7 +45,7 @@ rationale = "Round-2 review fix in graph_cmd: the refused-spec handler now escap"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:daf6207146c0ea41fe34bb272ed51350208af790""pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:f61145e5706f2b36134aafe844653ae6d719be8c""pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad"-"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690"+"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:df07de7f203f57041907e080bc5fd80f9f593301""pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex 8e629b392..c4ec93e12 100644--- a/.drift/acks/pipelex-kernel-docs.toml+++ b/.drift/acks/pipelex-kernel-docs.toml@@ -1,8 +1,8 @@contract = "pipelex-kernel-docs"-digest = "sha256:835a768141c5702b53e3924ae1b50d218d89cbf2038049432b7d610738a2123d"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-08-27T08:35:00Z"-rationale = "Reviewed docs/under-the-hood/pipelex-kernel.md against the compose_ops.py change: build_composed_content no longer fabricates an empty css_class for an Html-shaped output class (native.Html made css_class optional per MTHDS v0.9.0). The doc names the function in the surface table only and does not describe the fabricated value, so nothing is stale and no edit is needed."+digest = "sha256:b71924eeeafa924135c4e1658e999cb8591249a729083996bb01291f6f315096"+reviewed_by = "Claude (Opus 5)"+reviewed_at = "2026-09-18T19:26:43Z"+rationale = "ConceptProviderAbstract gained list_concept_keys_for_ref, so the boot-contract test's NativeOnlyConceptProvider implements it, returning an empty list — a provider that builds native concepts on demand stores none under a key. docs/under-the-hood/pipelex-kernel.md describes that smallest provider under shape_inputs and now names the enumeration beside the three capabilities it already listed; nothing else in the doc touches the provider surface."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -25,4 +25,4 @@ rationale = "Reviewed docs/under-the-hood/pipelex-kernel.md against the compose_"pipelex/kernel/search_ops.py" = "blob:ed0a8c7953aca1e38de852d0ddef11731b819539""pipelex/kernel/search_results.py" = "blob:101b70dc96cc5ee1721c9f6b1cb725a5ca78ff70""pipelex/kernel/templating_style_ops.py" = "blob:395473806d600dfc4f124c07f2afebb951fc086b"-"tests/unit/pipelex/kernel/test_kernel_boot_contract.py" = "blob:f7520706acd4ba906e30ca5dc2a2c2d5dd1fbf11"+"tests/unit/pipelex/kernel/test_kernel_boot_contract.py" = "blob:4f440b21ad51f27c098efff4d3a04433b53914bc"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 68a820f7b..4c9a13573 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,15 @@## [Unreleased]+### Changed++- **A dump of a working memory names each stuff's concept by ref (Breaking)**: every path that serializes a `Stuff` — `model_dump`, `smart_dump`, `dump_for_transport`, the `working_memory.json` a run saves, the agent CLI's `--with-memory` envelope and the runner's `PipeOutput` response — now emits `"concept": "<domain>.<Code>"` beside `stuff_code`, `stuff_name` and `content` instead of the full `Concept` object. A dump is one-way: a `Stuff`, a `WorkingMemory` or a `PipeOutput` cannot be validated back from its own dump, because the definition no longer travels with the data. Every consumer that read `concept.code`, `concept.domain_code` or `concept.structure_class_name` off a dumped stuff must read the ref string and resolve it instead.+- **A transported stuff's concept is resolved through the loaded library (Breaking)**: one shared rule matches the ref against every entry the library holds for that spelling — the host or native concept keyed by the ref itself, plus each concept a dependency package contributed, which the library keys under that package's address. One match resolves, none refuses naming the ref, and a spelling that a host bundle and a dependency both declare refuses naming every key that matched, rather than binding one package's definition to the other's data. Outside any library scope the readers answer from the pinned native set alone, so a delivery worker that never loaded the crate now renders a bundle-declared concept as a raw dict where it previously got a typed render from the definition on the wire.+- **`ConceptProviderAbstract` and `ConceptLibraryAbstract` gained abstract methods (Breaking)**: a provider must now implement `list_concept_keys_for_ref`, and a concept library must implement `add_dependency_concept`. An out-of-tree implementation of either fails to instantiate until it does.+- **The agent CLI's stdin resolver passes the concept ref through with its domain intact (Breaking)**: it used to reduce the concept object to a bare code, which let a bare code match any domain's concept of that spelling. A `--with-memory` envelope therefore pipes into a receiving method only where that method declares the same `<domain>.<Code>`; the looser behaviour silently bound one domain's definition to another domain's data. A concept the resolver cannot accept is reported under the new `error_type` `StdinEnvelopeShapeError` — the envelope parsed, so labelling it `JSONDecodeError` sent readers hunting for syntax errors in valid JSON.++ Note the limit: the MTHDS standard also defines `<package_address>::<domain>.<Code>` for a concept a dependency contributes, and this runtime neither emits nor resolves that form.+### Fixed- **`PINNED_NATIVES_MTHDS_VERSION` names the set it labels**: the constant read `1.0.0` while the standard pins the native set at `2.0.0`, so anything taking it as the answer to "which pinned set is this engine's" — a downstream port gating its own native goldens, for one — read a version the standard now describes as predating the pinning regime. It now reads `2.0.0`, and it is no longer a value nothing reads: the standard-conformance suite holds it to the page's own "Pinned at MTHDS" statement, and a check that needs no sibling checkout refuses a label later than the standard version this engine implements.diff --git a/docs/building-methods/pipes/working-memory.md b/docs/building-methods/pipes/working-memory.mdindex 7353eecc6..414e40905 100644--- a/docs/building-methods/pipes/working-memory.md+++ b/docs/building-methods/pipes/working-memory.md@@ -43,6 +43,21 @@ This mechanism allows you to chain pipes together, creating a flow of informatio* **Access**: Any pipe can access data from the Working Memory by declaring it in their `inputs` field.* **Disposal**: The Working Memory is cleared when the pipeline run completes.+## In memory and on the wire++A stuff has two shapes, and which one you are looking at depends on which side of the runtime you stand.++* **In memory**, a `Stuff` holds a resolved `Concept`: the runtime's own concept model, carrying the definition it needs to work — the description, the `structure_class_name` that names the content class, and what the concept `refines`. That definition is the library's: it comes from the bundle the method loaded.+* **On the wire**, a stuff *names* its concept and carries no definition. Every dump of a working memory — the `working_memory.json` a run saves, the agent CLI's `--with-memory` envelope, the runner's response — spells each stuff as `{"stuff_code": …, "stuff_name": …, "concept": "<domain>.<Code>", "content": …}`, which is the form the MTHDS [CLI I/O contract](https://mthds.ai/latest/spec/cli-io-contract/) requires.++A dump is therefore one-way: a stuff cannot be rebuilt from its own dump alone. A reader that needs the definition resolves the ref through the library the method loads — exactly how an input envelope's `"concept": "my_domain.Invoice"` is resolved when a run starts (see [Providing Inputs](provide-inputs.md#the-explicit-format-escape-hatch)), which is why the `--with-memory` envelope of one run can be piped straight into the next — as long as the receiving method declares that same `<domain>.<Code>`. The ref travels with its domain intact, so a method declaring `beta.Invoice` will not accept a stuff named `alpha.Invoice`, even where the two are shaped identically. That is deliberate: binding one domain's definition to another domain's data is the silent mistake the ref form exists to prevent.++### The limit of `<domain>.<Code>`, and what this runtime does about it++The MTHDS standard defines two spellings for a concept on the wire: `<domain>.<Code>` for a concept the running method's own bundles declare (and for the native set), and `<package_address>::<domain>.<Code>` for a concept a **dependency package** contributes. **This runtime emits only the first, and resolves only the first** — it neither writes nor accepts the `::` form.++That is enough in the ordinary case, because the library a reader resolves against knows which package contributed each concept: a dependency's concept is held under its package address internally, so a bare `<domain>.<Code>` arriving from the wire finds it. What the bare form cannot express is a *collision* — when the running method's own bundle and one of its dependencies both declare, say, `scoring.WeightedScore`, the ref names both and nothing on the wire says which was meant. Rather than pick one and bind the wrong definition to your data, the runtime refuses the hydration and names every candidate it found. Two ways out: rename one of the two concepts, or keep them in methods that do not run together.+## Best Practices* **Meaningful Names**: Use descriptive names for your `result` values to make your pipeline easier to understand.diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.mdindex 3458d8a47..6b20b8107 100644--- a/docs/errors/authoring-and-language.md+++ b/docs/errors/authoring-and-language.md@@ -21,6 +21,7 @@ own page. Classes are grouped by subsystem.- [`ConceptError`](concept-error.md) — Concept error- [`ConceptFactoryError`](concept-factory-error.md) — Concept factory- [`ConceptLibraryConceptNotFoundError`](concept-library-concept-not-found-error.md) — Concept library concept not found+- [`ConceptRefAmbiguousError`](concept-ref-ambiguous-error.md) — Concept ref ambiguous- [`ConceptRefineError`](concept-refine-error.md) — Concept refine- [`ConceptStringError`](concept-string-error.md) — Concept string- [`ConceptStructureGeneratorError`](concept-structure-generator-error.md) — Concept structure generatordiff --git a/docs/errors/concept-ref-ambiguous-error.md b/docs/errors/concept-ref-ambiguous-error.mdnew file mode 100644index 000000000..5e64cc1e6--- /dev/null+++ b/docs/errors/concept-ref-ambiguous-error.md@@ -0,0 +1,21 @@+---+title: "Concept ref ambiguous"+description: "Reference for the `ConceptRefAmbiguousError` Pipelex error class."+---++<!-- pipelex:generated -->++# Concept ref ambiguous++A bare `<domain>.<Code>` ref matches more than one concept the provider holds.++| Field | Value |+|---|---|+| `error_type` | `ConceptRefAmbiguousError` |+| `title` | Concept ref ambiguous |+| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-ref-ambiguous-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.concepts.exceptions` |+| Parent class | [`ConceptError`](concept-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 0389abe2e..9648d7f53 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -38,14 +38,14 @@ pipelex-agent run method <NAME> [OPTIONS]- `--mock-inputs` - Use mock inputs (requires `--dry-run`)- `--graph` / `--no-graph` - Enable/disable execution graph (enabled by default)- `--library-dir`, `-L` - Additional library directory-- `--with-memory` - Include full working memory in output+- `--with-memory` - Include full working memory in output, each stuff naming its concept by ref (`"concept": "<domain>.<Code>"`); piped back into another `run` on stdin, the envelope's stuffs become that run's inputs, provided the receiving method declares the same `<domain>.<Code>` — the ref carries its domain, and a method declaring another one refuses it rather than guessing- `--format` - Success output format: `markdown` (default) or `json`- `--error-format` - Error output format: `markdown` or `json` (defaults to `--format`'s value)For `bundle` and `method`, use `--pipe` to target a specific pipe.!!! note "Stdin inputs stay JSON"- The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist.+ The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist. In a `working_memory` envelope each stuff must name its concept as the ref string; anything else there — the full concept object an older runtime dumped, for instance — is refused under `"error_type": "StdinEnvelopeShapeError"`, which is the label for an envelope that parsed as JSON but does not hold the shape the contract asks for, as distinct from the `JSONDecodeError` that means the JSON itself did not parse.### Validatediff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex 6eafa5210..30005f341 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -214,7 +214,7 @@ The output JSON contains the complete working memory after pipeline execution, i### The results directory-Each run that saves anything gets its own numbered directory under `--output-dir` (`results/<pipe_code>_output_01/`, then `_02`, and so on). With `--save-working-memory` it holds `working_memory.json`, with `--save-main-stuff` the `main_stuff.*` renders, and with `--graph` the graph outputs that `graphs_inclusion` enables: `graphspec.json`, the Mermaid code and viewer, and the ReactFlow viewer.+Each run that saves anything gets its own numbered directory under `--output-dir` (`results/<pipe_code>_output_01/`, then `_02`, and so on). With `--save-working-memory` it holds `working_memory.json`, with `--save-main-stuff` the `main_stuff.*` renders, and with `--graph` the graph outputs that `graphs_inclusion` enables: `graphspec.json`, the Mermaid code and viewer, and the ReactFlow viewer. In `working_memory.json` each stuff names its concept by ref — `{"stuff_code": …, "stuff_name": …, "concept": "<domain>.<Code>", "content": …}` — and carries no concept definition; see [Working Memory](../../building-methods/pipes/working-memory.md#in-memory-and-on-the-wire).Beside `graphspec.json`, and gated by the same `graphspec_json` flag, the run writes the three files that describe the data the graph carries:diff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.mdindex 0a56e6a5b..2fe66251e 100644--- a/docs/under-the-hood/pipelex-kernel.md+++ b/docs/under-the-hood/pipelex-kernel.md@@ -101,7 +101,7 @@ Every kernel function is **fully keyword-only**, with zero entries in `subject_g`pipelex.kernel.memory_ops` holds the three ends of that boundary — shape in, write back, read out:-- **`shape_inputs`** — interpret raw values against the specs declared for them (Smart Inputs: a bare string becomes the declared concept, a dict validates against a structured one, a list shapes element-wise). It takes a `ConceptProviderAbstract` explicitly, because resolving concepts is what a loaded method's library is for and the kernel must stay callable without one. The interpreter hands over its concept library; a library-free caller supplies its own provider (the boot-contract test shows the smallest one that works — native concepts from `ConceptFactory`, compatibility from the declaration tier, structure classes from the class registry a boot fills).+- **`shape_inputs`** — interpret raw values against the specs declared for them (Smart Inputs: a bare string becomes the declared concept, a dict validates against a structured one, a list shapes element-wise). It takes a `ConceptProviderAbstract` explicitly, because resolving concepts is what a loaded method's library is for and the kernel must stay callable without one. The interpreter hands over its concept library; a library-free caller supplies its own provider (the boot-contract test shows the smallest one that works — native concepts from `ConceptFactory`, compatibility from the declaration tier, structure classes from the class registry a boot fills, and an empty key enumeration, since a provider that builds its concepts on demand stores none under a key).- **`store_result`** — the write-back every operator's ops end with, and the one place the memory contract is implemented.- **`extract_main_content` / `extract_named_content`** — the typed read. Needed even though every result envelope already carries the produced content, because those fields are annotated with the base `StuffContent`: pass the class you asked for and get it back narrowed.- **`extract_main_content_as_list` / `extract_named_content_as_list`** — the same typed read for a call that produced several objects. A multiple-output call stores one `ListContent`, which the single-content reads cannot narrow: the bare item class raises, and `ListContent[item_type]` is rejected by design. These verify every item against `item_type`, so the list comes back typed all the way down.diff --git a/docs/under-the-hood/runtime-bridge-and-transport.md b/docs/under-the-hood/runtime-bridge-and-transport.mdindex b4178fdac..3b3deca1c 100644--- a/docs/under-the-hood/runtime-bridge-and-transport.md+++ b/docs/under-the-hood/runtime-bridge-and-transport.md@@ -92,10 +92,14 @@ A host runtime's data converter deserializes a payload (a job input, a return vaBoth `PipeJob` and `PipeOutput` carry a `working_memory_raw` field — a plain JSON dict — alongside the typed `working_memory`. The raw dict needs no class resolution to cross a boundary, which decouples transport from class registration.+A working memory therefore has two shapes. In memory, a `Stuff` holds a resolved `Concept` — the runtime's own subclass of the protocol's `ConceptAbstract`, carrying the `description`, the `structure_class_name` and the `refines` the standard keeps in the library a method loads. On the wire, a stuff *names* its concept: every dump — `model_dump`, `smart_dump`, `dump_for_transport`, the `working_memory.json` a run saves, the runner's `PipeOutput` response — emits `{"stuff_code": …, "stuff_name": …, "concept": "<domain>.<Code>", "content": …}`, the form the MTHDS [CLI I/O contract](https://mthds.ai/latest/spec/cli-io-contract/) requires, because `StuffAbstract` serializes `concept` as the ref string. The definition never leaves the runtime, so a dump is one-way: a reader resolves each ref through the concept library the method loaded, the same way the input side resolves an input envelope's `concept`.++**This runtime emits and resolves `<domain>.<Code>` only.** The standard also defines `<package_address>::<domain>.<Code>`, the spelling for a concept a *dependency package* contributes, and nothing here writes it or accepts it — that form is not implemented yet. The gap is closed on the reading side rather than on the writing side, by the one rule both readers share, `ConceptProviderAbstract.resolve_wire_concept_ref`: a bare ref is matched against every key the concept library holds for that spelling — the host/native entry keyed by the ref itself, plus each `<alias>-><domain>.<Code>` entry a dependency landed under (`ConceptLibrary.add_dependency_concept`, where the alias is the whole package address on the live route). One candidate resolves, none raises naming the ref, and **more than one raises naming every key that matched**, because a bare ref genuinely cannot say whether the host's `scoring.WeightedScore` or a dependency's was meant, and binding one package's definition to another package's data is a silent data fault rather than a failure. Enumeration is why `list_concept_keys_for_ref` sits on the provider abstraction at all: resolution alone cannot distinguish "one match" from "two".+- **Input dehydration** — before dispatch, the working memory is moved into `working_memory_raw` (a plain dict produced by `WorkingMemory.dump_for_transport()`, which stays in open core at `pipelex/core/memory/working_memory.py`). After the worker loads the crate, the job's entry point hydrates the raw dict back to a typed `WorkingMemory`, inside the job's scope.- **Output dehydration** — before a nested job returns, its working memory is dehydrated to `working_memory_raw`. A **parent job** that consumes the nested output (a controller combining branch results — PipeParallel, PipeBatch) rehydrates it on receive, inside its **own already-loaded scope**: the parent's library carries the same crate (checked by fingerprint via `is_crate_loaded`), so hydration rebinds the nested output to the parent's own dynamic classes — the identity the parent's models reference. **Delivery** workers never load the crate — they render from the raw dict, only best-effort hydrating the main stuff via globally registered classes (falling back to a generic dict render when the class isn't registered), so they stay crate-free. The **top-level submitter** rehydrates too, opening a fresh scoped library when it hasn't loaded the crate itself.-The worker-side hydration helper (`pipelex/runtime_bridge/primitives/hydration.py`) is open core: it iterates the raw dict, uses `StuffContentFactory` to rebuild typed content from the registered classes, and preserves aliases. It also guards against cross-exec class-identity mismatches (`_validate_as_known_class` round-trips items through `model_dump()`): the dynamic classes a worker re-execs from the crate are new Python identities sharing a name with whatever a data converter eagerly rebuilt, and a naive `model_validate` would reject the older instance.+The worker-side hydration helper (`pipelex/runtime_bridge/primitives/hydration.py`) is open core: it iterates the raw dict, resolves each stuff's concept ref through the concept library of the current library — `load_from_crate` having run first, so the crate's concepts are declared and its dynamic classes registered — uses `StuffContentFactory` to rebuild typed content from the registered classes, and preserves aliases. A stuff whose `concept` is not a ref string, names a concept the library does not hold, or names a spelling the library holds more than once, fails the hydration with a `PipeJobError`. A current library is **not** a precondition, because a caller legitimately has none: `Pipelex.make()` sets no current library, and the transport boundary's `scoped_library_for_crate(None, …)` is a documented no-op that falls back to the active class registry. With no library, hydration resolves the native refs from the pinned native set and refuses anything a bundle declares, naming the stuff — the same answer the delivery executor's best-effort local hydration gives, which likewise resolves a native ref from the pinned native set with no library and falls back to the raw render for anything else, since a delivery worker never loads the crate. That reader treats an ambiguous ref as "not known here" too — a logged warning naming the colliding keys and a raw render — because rendering a result must never fail a delivery. It also guards against cross-exec class-identity mismatches (`_validate_as_known_class` round-trips items through `model_dump()`): the dynamic classes a worker re-execs from the crate are new Python identities sharing a name with whatever a data converter eagerly rebuilt, and a naive `model_validate` would reject the older instance.### Boundary-by-boundary (backend-neutral)diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex a1ffa3755..3dc0283ef 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -125,6 +125,11 @@ AGENT_ERROR_HINTS: dict[str, str] = {"FileNotFoundError": "Verify the file path exists and is accessible from the current working directory","ArgumentError": "Check command usage with 'pipelex-agent <command> --help'","JSONDecodeError": "Verify the JSON input is valid (check for trailing commas, unquoted keys, etc.)",+ "StdinEnvelopeShapeError": (+ "The JSON parsed — its shape is what the envelope contract refuses. In a 'working_memory' envelope each stuff "+ "names its concept as the ref string '<domain>.<Code>'; replace a concept object with its ref, or re-pipe the "+ "output of a current 'pipelex-agent run --with-memory'."+ ),# Interpreter errors"MthdsParserError": "Check MTHDS file TOML syntax and ensure all referenced concepts and pipes are defined",# Configuration/initialization errors@@ -190,6 +195,7 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {"FixBundleError": "input","FileNotFoundError": "input","JSONDecodeError": "input",+ "StdinEnvelopeShapeError": "input","JsonTypeError": "input","TomlError": "input","ArgumentError": "input",diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.pyindex 4bc7f4e91..c7c7d7495 100644--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py@@ -31,29 +31,18 @@ class ParsedCliInputs(NamedTuple):inputs_base_dir: Path | None-def _extract_concept_code(concept_data: Any) -> str:- """Extract a concept code string from a concept data value.-- Args:- concept_data: The concept field from a stuff dict — may be a dict with- a ``code`` key, a plain string, or another type.-- Returns:- The concept code string.- """- if isinstance(concept_data, dict):- concept_dict = cast("dict[str, Any]", concept_data)- return str(concept_dict.get("code", ""))- if isinstance(concept_data, str):- return concept_data- return str(concept_data)---def _extract_stuff_entry(stuff_data: dict[str, Any]) -> dict[str, Any] | None:+def _extract_stuff_entry(stuff_data: dict[str, Any], *, stuff_name: str) -> dict[str, Any] | None:"""Extract a ``{ concept, content }`` input entry from a serialized stuff dict.+ A serialized stuff names its concept by ref — ``"concept": "<domain>.<Code>"`` — and carries+ no definition, so the ref passes through untouched: the runner resolves it through the loaded+ library when it shapes the inputs, exactly as it does for an explicit ``{concept, content}``+ envelope in an inputs file. Anything but a string is refused rather than reduced: the standard+ puts no object there, and reducing one to its bare code would drop the domain.+Args:stuff_data: A serialized Stuff dict with ``concept`` and ``content`` keys.+ stuff_name: The key the stuff sits under in ``working_memory.root``, for the error.Returns:A dict with ``concept`` (str) and ``content`` (Any) keys, or None if@@ -63,8 +52,17 @@ def _extract_stuff_entry(stuff_data: dict[str, Any]) -> dict[str, Any] | None:content_data: Any = stuff_data.get("content")if concept_data is None or content_data is None:return None+ if not isinstance(concept_data, str):+ # Not a JSONDecodeError: the envelope parsed. What failed is its *shape* — the concept+ # field holds something the CLI I/O contract does not put there — and the label is a+ # machine contract, so it must not send a consumer hunting for trailing commas.+ agent_error(+ f"stdin envelope has invalid 'working_memory.root.{stuff_name}.concept': "+ f"expected the concept ref string '<domain>.<Code>', got {type(concept_data).__name__}",+ error_type="StdinEnvelopeShapeError",+ )return {- "concept": _extract_concept_code(concept_data),+ "concept": concept_data,"content": content_data,}@@ -79,7 +77,8 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:- **Full envelope**: a dict with a ``working_memory`` key at the top level(from upstream ``--with-memory`` output). Stuffs are extracted from``working_memory.root`` and converted to ``{ concept, content }`` entries- suitable for ``PipelineInputs``.+ suitable for ``PipelineInputs``, each stuff's ``concept`` being the+ namespaced ref string the upstream run dumped.Args:stdin_data: Parsed JSON dict from stdin.@@ -113,7 +112,7 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:continuestuff_data = cast("dict[str, Any]", stuff_data_raw)- entry = _extract_stuff_entry(stuff_data)+ entry = _extract_stuff_entry(stuff_data, stuff_name=stuff_name)if entry is not None:resolved[stuff_name] = entry@@ -121,7 +120,7 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:main_data_raw: Any = root.get(MAIN_STUFF_KEY)if main_data_raw is not None and MAIN_STUFF_KEY not in aliases and isinstance(main_data_raw, dict):main_data = cast("dict[str, Any]", main_data_raw)- entry = _extract_stuff_entry(main_data)+ entry = _extract_stuff_entry(main_data, stuff_name=MAIN_STUFF_KEY)if entry is not None:resolved[MAIN_STUFF_KEY] = entrydiff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.pyindex f6ca97eb8..12cfbc14e 100644--- a/pipelex/core/concepts/concept.py+++ b/pipelex/core/concepts/concept.py@@ -20,13 +20,31 @@ from pipelex.tools.misc.string_utils import pascal_case_to_sentenceclass Concept(ConceptAbstract):+ """A concept as the runtime holds it in memory: its name and its definition.++ The protocol model, `ConceptAbstract`, is a name and nothing more — `code`, `domain_code`+ and the `concept_ref` they form — because the standard keeps a concept's definition in the+ library a method loads, never beside a stuff. The runtime needs the definition in memory to+ resolve a structure class, check compatibility and render a representation, so it declares+ those fields here, on its own subclass.++ The fields declared here never travel beside a stuff: `StuffAbstract` serializes `concept`+ as the ref string, so every dump of a `Stuff`, of a `WorkingMemory` and of a `PipeOutput`+ carries `{"concept": "<domain>.<Code>", "content": …}`. A reader of such a dump resolves the+ ref through the concept library the method loads, the way the input side does.+ """++ description: str+ structure_class_name: str+ refines: str | None = None+@field_validator("code")@classmethoddef validate_code(cls, code: str) -> str:try:validate_concept_code(concept_code=code)except ConceptCodeError as exc:- msg = f"Concept code '{code}' is not a valid concept code for concept '{cls.concept_ref}'"+ msg = f"Concept code '{code}' is not a valid concept code"raise ConceptValueError(msg) from excreturn code@@ -36,7 +54,7 @@ class Concept(ConceptAbstract):try:validate_domain_code(code=domain_code)except DomainCodeError as exc:- msg = f"Domain code '{domain_code}' is not a valid domain code for concept '{cls.concept_ref}'"+ msg = f"Domain code '{domain_code}' is not a valid domain code for a concept"raise ConceptValueError(msg) from excreturn domain_codediff --git a/pipelex/core/concepts/concept_provider_abstract.py b/pipelex/core/concepts/concept_provider_abstract.pyindex 0233aad96..8721d94a0 100644--- a/pipelex/core/concepts/concept_provider_abstract.py+++ b/pipelex/core/concepts/concept_provider_abstract.py@@ -14,7 +14,9 @@ See ``docs/contribute/hub-layering.md``.from abc import ABC, abstractmethodfrom pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.exceptions import ConceptRefAmbiguousErrorfrom pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.qualified_ref import QualifiedReffrom pipelex.core.stuffs.stuff_content import StuffContent@@ -25,6 +27,17 @@ class ConceptProviderAbstract(ABC):def get_required_concept(self, concept_ref: str) -> Concept:"""Resolve a fully-qualified concept ref, raising when it is not known."""+ @abstractmethod+ def list_concept_keys_for_ref(self, *, concept_ref: str) -> list[str]:+ """Every key under which this provider holds a concept spelled `<domain>.<Code>`.++ A host-declared or native concept is keyed by the ref itself; a concept a dependency+ package contributes is keyed `<alias>-><domain>.<Code>`, and on the live route the alias+ is the dependency's whole package address. One spelling can therefore have several+ entries, and only an enumeration says so — which is what+ :meth:`resolve_wire_concept_ref` needs to tell one candidate from several.+ """+@abstractmethoddef get_native_concept(self, native_concept: NativeConceptCode) -> Concept:"""Resolve one of the native concepts."""@@ -45,6 +58,44 @@ class ConceptProviderAbstract(ABC):def is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:"""Whether `tested_concept` satisfies `wanted_concept` (refinement only when `strict`)."""+ def resolve_wire_concept_ref(self, *, concept_ref: str) -> Concept:+ """Resolve the concept ref a transported stuff carries, the one rule both readers share.++ On the wire a stuff names its concept `<domain>.<Code>` — the form this runtime emits, and+ the one the MTHDS standard defines for a host-declared or native concept. The standard also+ defines `<package_address>::<domain>.<Code>` for a concept a *dependency* contributes; this+ runtime neither emits nor resolves that form, so a dependency's concept arrives spelled+ exactly like a host's, and the library is what tells them apart:++ * one candidate — the host/native entry, or a single dependency's aliased entry — is the+ answer, which is what kept a dependency-contributed concept hydrating back when the+ definition rode along on the wire;+ * several candidates mean a host bundle and a dependency (or two dependencies) spell the+ same `<domain>.<Code>`, and the ref cannot say which is meant, so it raises naming every+ key that matched rather than silently binding the wrong definition to the data;+ * no candidate raises the way it always has, naming the ref.++ A ref that already carries the internal `alias->` prefix is not a wire spelling at all and+ goes straight to its direct lookup.++ Raises:+ ConceptRefAmbiguousError: the spelling matches more than one entry.+ """+ if QualifiedRef.has_cross_package_prefix(concept_ref):+ return self.get_required_concept(concept_ref=concept_ref)++ candidate_keys = self.list_concept_keys_for_ref(concept_ref=concept_ref)+ if len(candidate_keys) > 1:+ msg = (+ f"Concept ref '{concept_ref}' is ambiguous: this library holds it under {sorted(candidate_keys)}. "+ "A stuff on the wire names its concept '<domain>.<Code>', which cannot tell a host concept from a "+ "dependency's concept of the same spelling — rename one of them, or run the two bundles apart."+ )+ raise ConceptRefAmbiguousError(msg)+ if len(candidate_keys) == 1:+ return self.get_required_concept(concept_ref=candidate_keys[0])+ return self.get_required_concept(concept_ref=concept_ref)+@abstractmethoddef get_structure_class(self, *, concept: Concept) -> type[StuffContent]:"""Resolve a concept's declared `structure_class_name` into the class itself.diff --git a/pipelex/core/concepts/exceptions.py b/pipelex/core/concepts/exceptions.pyindex 626d124bc..99e82c0dd 100644--- a/pipelex/core/concepts/exceptions.py+++ b/pipelex/core/concepts/exceptions.py@@ -36,3 +36,14 @@ class ConceptRefineError(ConceptError):class ConceptLibraryConceptNotFoundError(PipelexError):pass+++class ConceptRefAmbiguousError(ConceptError):+ """A bare `<domain>.<Code>` ref matches more than one concept the provider holds.++ A stuff on the wire names its concept as `<domain>.<Code>`, and that spelling is not unique+ across a crate: a host bundle and a dependency package may each declare it, the dependency's+ entry being keyed `<alias>-><domain>.<Code>`. Picking a winner would bind one package's+ definition to the other's data without a word, so the ambiguity is raised instead, naming+ every key that matched.+ """diff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.pyindex af773a953..73260ec98 100644--- a/pipelex/core/memory/working_memory.py+++ b/pipelex/core/memory/working_memory.py@@ -565,7 +565,14 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):################################################################################################def smart_dump(self) -> dict[str, Any]:- """Serialize the working memory as a dictionary."""+ """Serialize the working memory as a dictionary.++ Each stuff comes out in the standard's wire form, ``{"concept": "<domain>.<Code>",+ "content": …}`` beside its ``stuff_code`` and ``stuff_name``: ``StuffAbstract``+ serializes ``concept`` as the ref string, so the definition the in-memory ``Concept``+ carries never leaves the runtime. The dump is one-way — a reader resolves each ref+ through the concept library the method loads.+ """return self.model_dump(serialize_as_any=True)def dump_for_transport(self) -> dict[str, Any]:@@ -574,7 +581,8 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):Like smart_dump(), but serializes ListContent as a plain list instead of``{"items": [...]}``. This removes the ambiguity at hydration time: a``list`` content value is always a ListContent, a ``dict`` is always a- single StuffContent.+ single StuffContent. Each stuff's ``concept`` is the ref string here too;+ the hydrator resolves it through the library the far side has loaded.Per-item type metadata for the list path is written under thepipelex-private keys ``__pipelex_class__`` / ``__pipelex_module__``diff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.pyindex fde06db3a..f94e4018b 100644--- a/pipelex/libraries/concept/concept_library.py+++ b/pipelex/libraries/concept/concept_library.py@@ -168,6 +168,23 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):raise ConceptLibraryError(msg)return the_concept+ @override+ def list_concept_keys_for_ref(self, *, concept_ref: str) -> list[str]:+ """Every key of this library holding a concept spelled `concept_ref`.++ The host-declared or native entry is keyed by the ref itself (`add_new_concept`); a+ dependency's concept is keyed `<alias>-><domain>.<Code>` (`add_dependency_concept`) and+ has no unaliased twin — the loader removes the temporary unaliased entries once the child+ library is built. So a bare ref arriving from the wire matches the host entry, every+ dependency that contributes that spelling, or both.+ """+ candidate_keys: list[str] = []+ if concept_ref in self.root:+ candidate_keys.append(concept_ref)+ aliased_suffix = f"->{concept_ref}"+ candidate_keys.extend(sorted(key for key in self.root if key.endswith(aliased_suffix)))+ return candidate_keys+@overridedef get_native_concept(self, native_concept: NativeConceptCode) -> Concept:the_native_concept = self.get_optional_concept(f"{SpecialDomain.NATIVE}.{native_concept}")@@ -304,6 +321,7 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):raise ConceptLibraryConceptNotFoundError(msg)return None+ @overridedef add_dependency_concept(self, *, alias: str, concept: Concept) -> None:"""Add a concept from a dependency package with an aliased key.diff --git a/pipelex/libraries/concept/concept_library_abstract.py b/pipelex/libraries/concept/concept_library_abstract.pyindex 92273733c..55bf71a78 100644--- a/pipelex/libraries/concept/concept_library_abstract.py+++ b/pipelex/libraries/concept/concept_library_abstract.py@@ -20,6 +20,16 @@ class ConceptLibraryAbstract(ConceptProviderAbstract):def add_concepts(self, concepts: list[Concept]) -> None:pass+ @abstractmethod+ def add_dependency_concept(self, *, alias: str, concept: Concept) -> None:+ """Add a concept a dependency package contributed, keyed under that dependency's alias.++ Declared here rather than on the concrete library because the aliased key is half of what+ :meth:`ConceptProviderAbstract.resolve_wire_concept_ref` reads back: a bare `<domain>.<Code>`+ off the wire finds a dependency's concept only through this entry, so a caller holding the+ abstraction must be able to create one.+ """+@abstractmethoddef remove_concepts_by_concept_refs(self, concept_refs: list[str]) -> None:passdiff --git a/pipelex/pipe_operators/func/pipe_func_execution_transport.py b/pipelex/pipe_operators/func/pipe_func_execution_transport.pyindex 2c76b00e3..8f2ca3036 100644--- a/pipelex/pipe_operators/func/pipe_func_execution_transport.py+++ b/pipelex/pipe_operators/func/pipe_func_execution_transport.py@@ -64,9 +64,9 @@ def pipe_func_execution_result_from_response(response: PipeFuncExecutionResponse"""Rebind a transported response into a PipeFuncExecutionResult against THIS process's registry.The output rode back as a transported working memory whose main stuff is the PipeFunc output;- hydrating it here rebinds the class from the concept's ``structure_class_name`` (present for- native and inline-structure concepts; a customer output class shipped only as .py is a known,- deferred limitation).+ hydrating it here resolves the stuff's concept ref through the current library and rebinds the+ class from that concept's ``structure_class_name`` (present for native and inline-structure+ concepts; a customer output class shipped only as .py is a known, deferred limitation)."""output_memory = hydrate_working_memory(response.output_memory_raw)content = output_memory.get_main_stuff().contentdiff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.pyindex 24ca11ff1..d3186502c 100644--- a/pipelex/pipe_run/delivery_executor.py+++ b/pipelex/pipe_run/delivery_executor.py@@ -10,15 +10,20 @@ from pydantic import ValidationErrorfrom pipelex import logfrom pipelex.base_exceptions import DisclosureMode, ErrorReportfrom pipelex.config import get_config-from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.exceptions import ConceptLibraryConceptNotFoundError, ConceptRefAmbiguousError+from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.absence import AbsenceRecordfrom pipelex.core.memory.absence_render import build_absence_html, build_absence_json, build_absence_markdownfrom pipelex.core.memory.working_memory import MAIN_STUFF_NAMEfrom pipelex.core.pipes.pipe_io_artifacts import INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME, PIPE_IO_CONTRACTS_FILE_NAME+from pipelex.core.qualified_ref import QualifiedRef, QualifiedRefErrorfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_viewer import render_stuff_viewerfrom pipelex.graph.graph_factory import generate_graph_outputs+from pipelex.interpreter_hub import get_concept_library, get_current_library_id_or_none+from pipelex.libraries.exceptions import LibraryErrorfrom pipelex.pipe_run.exceptions import PipeJobError, StorageDeliveryError, WebhookDeliveryErrorfrom pipelex.reporting.usage_records import dump_tokens_usage_recordsfrom pipelex.runtime_bridge.primitives.hydration import hydrate_content@@ -27,6 +32,7 @@ from pipelex.tools.misc.json_utils import clean_json_dumpsfrom pipelex.tools.network.ssrf_guard import SsrfGuardedTransportif TYPE_CHECKING:+ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifactsfrom pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.pipe_run.delivery_assignment import DeliveryAssignment, DeliveryStatus, StorageTarget, WebhookTarget@@ -92,11 +98,12 @@ class DeliveryExecutor:Supports two `pipe_output` shapes:- Typed: `working_memory` populated (in-process / same-worker path).- Raw: `working_memory_raw` populated (cross-process Temporal path,- where the activity worker may not have the dynamic concept classes- loaded). The activity tries to locally hydrate using only globally- registered classes; on failure it falls back to a generic dict- render so built-in content types still get typed rendering and- dynamic concepts produce a readable JSON dump.+ where the activity worker may not have the method's library loaded).+ The activity tries to locally hydrate the main stuff with the concepts+ this process knows — the current library when one is set, the native+ set otherwise — and the globally registered classes; on failure it+ falls back to a generic dict render so built-in content types still+ get typed rendering and dynamic concepts produce a readable JSON dump.A completed run always resolves its declared output: a value or arecorded absence. The main_stuff.* artifact files are always produced —@@ -217,17 +224,69 @@ class DeliveryExecutor:files["main_stuff.html"] = ResultFile(data=build_absence_html(absence_record).encode("utf-8"), content_type="text/html")@classmethod- def try_local_hydrate_stuff(cls, stuff_raw: dict[str, Any]) -> Stuff | None:- """Attempt to hydrate a single Stuff dict using only globally-registered classes.+ def _resolve_concept_locally(cls, *, concept_ref: str) -> Concept | None:+ """Resolve a transported stuff's concept ref with what this process holds.++ A delivery worker never loads the crate, so a dynamic concept is unknown to it by+ design. When a library is current — an in-process run delivering its own result — the+ ref goes through the shared wire-ref rule, so a concept a dependency package contributed+ resolves through its aliased entry; otherwise only the native concepts are known, and they+ are built from their pinned definitions. ``None`` means "not known here", and it means that+ for a malformed ref and for a library that has gone away as much as for an unknown one:+ this reader renders a result and must never fail a delivery, so every way of failing to+ name a concept ends in the raw render.++ A spelling the library holds more than once is "not known here" too, deliberately: the+ collision is logged by name and the caller falls back to the raw render rather than binding+ one package's definition to another package's data.+ """+ if get_current_library_id_or_none() is not None:+ try:+ return get_concept_library().resolve_wire_concept_ref(concept_ref=concept_ref)+ except ConceptRefAmbiguousError as exc:+ log.warning(f"Concept ref '{concept_ref}' is ambiguous in the current library, rendering the delivery raw: {exc}")+ return None+ except (LibraryError, ConceptLibraryConceptNotFoundError):+ return None+ except RuntimeError as exc:+ # The contextvar still names a library, but the hub that held it is gone. A delivery+ # outlives the run it renders, so this is a race to survive, not a state to assert.+ log.warning(f"The current library is no longer reachable, rendering the delivery raw: {exc}")+ return None+ try:+ is_native_ref = NativeConceptCode.is_valid_native_concept_ref(concept_ref=concept_ref)+ except QualifiedRefError as exc:+ log.warning(f"Concept ref '{concept_ref}' is not a valid concept ref, rendering the delivery raw: {exc}")+ return None+ if not is_native_ref:+ return None+ native_code = QualifiedRef.parse(concept_ref).local_code+ return ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode(native_code))- Returns None when the structure class isn't available locally (typically- a dynamic concept class missing from the activity worker's registry) —- callers then fall back to a generic raw-dict render. A warning is- emitted on the fallback path so silent regressions on built-in- hydration surface in logs.+ @classmethod+ def try_local_hydrate_stuff(cls, stuff_raw: dict[str, Any]) -> Stuff | None:+ """Attempt to hydrate a single Stuff dict with the concepts and classes this process holds.++ The stuff names its concept by ref (``"concept": "<domain>.<Code>"``); the ref is+ resolved locally — the current library when one is set, the native set otherwise —+ and the concept's structure class is then looked up in the class registry. Returns+ None when the concept or its class isn't available locally (typically a dynamic+ concept the activity worker never loaded) — callers then fall back to a generic+ raw-dict render. A warning is emitted on the fallback path so silent regressions+ on built-in hydration surface in logs."""try:- concept = Concept.model_validate(stuff_raw["concept"])+ concept_ref = stuff_raw["concept"]+ if not isinstance(concept_ref, str):+ log.warning(+ f"Local hydration failed for delivery main stuff, falling back to raw render: "+ f"'concept' must be the concept ref string, got {type(concept_ref).__name__}"+ )+ return None+ concept = cls._resolve_concept_locally(concept_ref=concept_ref)+ if concept is None:+ log.warning(f"Local hydration failed for delivery main stuff, falling back to raw render: concept '{concept_ref}' not known locally")+ return Noneregistry = get_class_registry()item_class = registry.get_class(name=concept.structure_class_name)if item_class is None or not issubclass(item_class, StuffContent):diff --git a/pipelex/runtime_bridge/primitives/hydration.py b/pipelex/runtime_bridge/primitives/hydration.pyindex 6a6921508..b2ad3af48 100644--- a/pipelex/runtime_bridge/primitives/hydration.py+++ b/pipelex/runtime_bridge/primitives/hydration.py@@ -4,14 +4,22 @@ from kajson.exceptions import KajsonExceptionfrom pydantic import ValidationErrorfrom pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract+from pipelex.core.concepts.exceptions import ConceptLibraryConceptNotFoundError, ConceptRefAmbiguousError+from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.absence import AbsenceRecordfrom pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.qualified_ref import QualifiedRef, QualifiedRefErrorfrom pipelex.core.stuffs.composite_content import CompositeContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_content_factory import StuffContentFactoryfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.interpreter_hub import get_concept_library, get_current_library_id_or_none+from pipelex.libraries.concept.exceptions import ConceptLibraryError+from pipelex.libraries.exceptions import LibraryErrorfrom pipelex.pipe_run.exceptions import PipeJobErrorfrom pipelex.runtime_hub import get_class_registry@@ -137,22 +145,98 @@ def hydrate_content(raw_content: list[Any] | dict[str, Any] | str, *, concept: C)+def _resolve_native_stuff_concept(*, concept_ref: str, stuff_name: str) -> Concept:+ """Resolve a transported stuff's concept ref with the pinned native set alone.++ A reader outside any library scope is a live path, not a fixture: ``Pipelex.make()`` sets no+ current library, and on the transport boundary ``scoped_library_for_crate(None, …)`` is a true+ no-op that falls back to the active class registry. What such a reader can honestly answer is+ the native set, which the runtime pins and no bundle declares — the same answer+ ``DeliveryExecutor._resolve_concept_locally`` gives in the same situation. A ref a bundle+ declares is refused by name instead, because only a loaded library holds its definition.++ Raises:+ PipeJobError: the ref is malformed, or names a non-native concept.+ """+ try:+ is_native_ref = NativeConceptCode.is_valid_native_concept_ref(concept_ref=concept_ref)+ except QualifiedRefError as exc:+ msg = f"Failed to hydrate stuff '{stuff_name}': '{concept_ref}' is not a valid concept ref: {exc}"+ raise PipeJobError(msg) from exc+ if not is_native_ref:+ msg = (+ f"Failed to hydrate stuff '{stuff_name}': concept '{concept_ref}' is not native and no library is current — "+ "a stuff whose concept a bundle declares can only be hydrated against the loaded library that declares it"+ )+ raise PipeJobError(msg)+ native_code = QualifiedRef.parse(concept_ref).local_code+ return ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode(native_code))+++def resolve_stuff_concept(*, concept_ref: Any, stuff_name: str, concept_provider: ConceptProviderAbstract | None) -> Concept:+ """Resolve the concept a transported stuff names.++ On the wire a stuff carries ``"concept": "<domain>.<Code>"`` and no definition — the+ standard's form, which ``StuffAbstract`` emits on every dump — so the definition, the+ ``structure_class_name`` above all, comes from the concept library the method loaded, the+ way the input side resolves an input envelope's ``concept``. Anything but a string is+ refused: the full-object form the runtime once dumped is not a shape a reader accepts.++ ``concept_provider`` is ``None`` when no library is current, and the native set then answers+ on its own — see :func:`_resolve_native_stuff_concept`. With a provider, the shared rule on+ :meth:`ConceptProviderAbstract.resolve_wire_concept_ref` decides, so a concept a dependency+ package contributed resolves through its aliased entry and a spelling two packages share is+ refused rather than bound to whichever one the reader happened to reach first.++ Raises:+ PipeJobError: ``concept_ref`` is not a string, names no concept of the library, or names+ a spelling the library holds more than once.+ """+ if not isinstance(concept_ref, str):+ msg = f"Failed to hydrate stuff '{stuff_name}': 'concept' must be the concept ref string '<domain>.<Code>', got {type(concept_ref).__name__}"+ raise PipeJobError(msg)+ if concept_provider is None:+ return _resolve_native_stuff_concept(concept_ref=concept_ref, stuff_name=stuff_name)+ try:+ return concept_provider.resolve_wire_concept_ref(concept_ref=concept_ref)+ except ConceptRefAmbiguousError as exc:+ msg = f"Failed to hydrate stuff '{stuff_name}': {exc}"+ raise PipeJobError(msg) from exc+ except (ConceptLibraryError, ConceptLibraryConceptNotFoundError) as exc:+ msg = f"Failed to hydrate stuff '{stuff_name}': concept '{concept_ref}' is not in the loaded library: {exc}"+ raise PipeJobError(msg) from exc++def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:- """Reconstruct typed WorkingMemory from a raw dict.+ """Reconstruct typed WorkingMemory from its transport dump.++ A stuff on the wire names its concept and carries no definition, so each ref is resolved+ through the concept library of the current library when there is one: ``load_from_crate()``+ declares the concepts and registers the dynamic classes in one move, and the resolved+ concept's ``structure_class_name`` is then looked up in the scoped ClassRegistry to pick the+ StuffContent subclass.- Must be called AFTER load_from_crate() has registered dynamic classes- in the scoped ClassRegistry. Uses concept.structure_class_name to look up- the correct StuffContent subclass from the registry.+ A current library is not a precondition, because a caller legitimately has none — ``Pipelex.make()``+ sets no current library, and the transport boundary's ``scoped_library_for_crate(None, …)`` is a+ documented no-op that falls back to the active class registry. Such a reader resolves the native+ refs from the pinned native set and refuses anything a bundle declares, naming the stuff.The absence ledger round-trips too: a recorded absence must survive cross-processtransit, or a resolved-as-absent slot would degrade to a hard miss on the other side."""+ try:+ concept_provider: ConceptProviderAbstract | None = get_concept_library() if get_current_library_id_or_none() is not None else None+ except (LibraryError, RuntimeError) as exc:+ # The contextvar naming a library is not the same fact as that library still being there.+ # Whichever way it went, this function answers with PipeJobError and never with a raw one.+ msg = f"Failed to hydrate the working memory: the current library is no longer reachable: {exc}"+ raise PipeJobError(msg) from excworking_memory = WorkingMemory()raw_root = working_memory_raw.get("root", {})for stuff_name, stuff_dict in raw_root.items():try:- concept = Concept.model_validate(stuff_dict["concept"])+ concept = resolve_stuff_concept(concept_ref=stuff_dict["concept"], stuff_name=stuff_name, concept_provider=concept_provider)content = hydrate_content(concept=concept, raw_content=stuff_dict["content"])stuff = Stuff(stuff_code=stuff_dict["stuff_code"],diff --git a/pyproject.toml b/pyproject.tomlindex 34bde88ee..da4f66cbd 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -31,7 +31,7 @@ dependencies = ["json2html>=1.3.0","kajson==0.7.1","markdown>=3.6",- "mthds==0.14.0",+ "mthds==0.15.0","networkx>=3.4.2","openai>=2.0.0","opentelemetry-api",diff --git a/subject_grants.toml b/subject_grants.tomlindex 84126466f..d92bf86dd 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -268,10 +268,6 @@ rationale = "Runs the pipe identified by pipe_code; single operand."param = "pipe_code"rationale = "Runs the pipe identified by pipe_code via the API; single operand."-["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_extract_concept_code"]-param = "concept_data"-rationale = "Extracts from the concept_data; single operand."-["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_extract_stuff_entry"]param = "stuff_data"rationale = "Extracts from the stuff_data; single operand."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 0079d38a1..f95916d68 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -32,6 +32,7 @@ ConceptFactoryError | Concept factory | https://docs.pipelex.com/latest/errors/cConceptLibraryConceptNotFoundError | Concept library concept not found | https://docs.pipelex.com/latest/errors/concept-library-concept-not-found-error/ConceptLibraryError | Concept library | https://docs.pipelex.com/latest/errors/concept-library-error/ConceptLoadingError | Concept loading | https://docs.pipelex.com/latest/errors/concept-loading-error/+ConceptRefAmbiguousError | Concept ref ambiguous | https://docs.pipelex.com/latest/errors/concept-ref-ambiguous-error/ConceptRefineError | Concept refine | https://docs.pipelex.com/latest/errors/concept-refine-error/ConceptSpecError | Concept spec | https://docs.pipelex.com/latest/errors/concept-spec-error/ConceptStringError | Concept string | https://docs.pipelex.com/latest/errors/concept-string-error/diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.pyindex 49d59aba8..978f034d9 100644--- a/tests/unit/pipelex/cli/test_agent_output_drift.py+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py@@ -50,6 +50,7 @@ _NON_PIPELEX_ERROR_KEYS: frozenset[str] = frozenset("CodegenDriftError", # synthetic error_type label (a drift verdict, not an exception)"CodegenLockNotFoundError", # synthetic error_type label"InitConfigError", # synthetic error_type label+ "StdinEnvelopeShapeError", # synthetic error_type label"UnknownCommandError", # synthetic error_type label})diff --git a/tests/unit/pipelex/cli/test_stdin_resolver.py b/tests/unit/pipelex/cli/test_stdin_resolver.pyindex 1c494a5b4..da5ef04f5 100644--- a/tests/unit/pipelex/cli/test_stdin_resolver.py+++ b/tests/unit/pipelex/cli/test_stdin_resolver.py@@ -157,21 +157,49 @@ class TestStdinResolver:result = resolve_stdin_inputs(data)assert result["item"]["concept"] == "Text"- def test_concept_as_dict(self) -> None:- """Concept given as a dict with 'code' key extracts the code value."""+ def test_namespaced_concept_ref_keeps_its_domain(self) -> None:+ """A stuff names its concept by ref on the wire; the ref passes through with its domain intact."""+ data: dict[str, Any] = {+ "working_memory": {+ "root": {+ "contract": {+ "stuff_code": "abc123",+ "stuff_name": "contract",+ "concept": "legal.Contract",+ "content": {"title": "NDA"},+ },+ },+ "aliases": {},+ },+ }+ result = resolve_stdin_inputs(data)+ assert result == {"contract": {"concept": "legal.Contract", "content": {"title": "NDA"}}}++ def test_concept_object_form_is_refused(self, capsys: pytest.CaptureFixture[str]) -> None:+ """The full-object concept a stale runtime dumped is refused, never reduced to a bare code.++ The label is a shape error, not a decode error: the envelope parsed, so a consumer must not+ be told to go hunting for trailing commas in JSON that was valid.+ """+ set_agent_cli_error_format(CliOutputFormat.JSON)data: dict[str, Any] = {"working_memory": {"root": {"item": {- "concept": {"code": "Text", "module": "core"},+ "concept": {"code": "Contract", "domain_code": "legal", "structure_class_name": "Contract"},"content": {"value": 1},},},"aliases": {},},}- result = resolve_stdin_inputs(data)- assert result["item"]["concept"] == "Text"+ with pytest.raises(typer.Exit) as exc_info:+ resolve_stdin_inputs(data)+ assert exc_info.value.exit_code == 1+ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "StdinEnvelopeShapeError"+ assert "working_memory.root.item.concept" in envelope["message"]+ assert "trailing commas" not in envelope["hint"]def test_stuff_missing_concept_skipped(self) -> None:"""Stuff entries missing concept or content are silently skipped."""diff --git a/tests/unit/pipelex/core/pipes/test_stuff_spec.py b/tests/unit/pipelex/core/pipes/test_stuff_spec.pyindex f8c660837..65186bedf 100644--- a/tests/unit/pipelex/core/pipes/test_stuff_spec.py+++ b/tests/unit/pipelex/core/pipes/test_stuff_spec.py@@ -124,6 +124,11 @@ class _RefusingConceptProvider(ConceptProviderAbstract):msg = "get_native_concept must not be called for a structureless render"raise AssertionError(msg)+ @override+ def list_concept_keys_for_ref(self, *, concept_ref: str) -> list[str]:+ msg = "list_concept_keys_for_ref must not be called for a structureless render"+ raise AssertionError(msg)+@overridedef get_required_entry_concept(self, concept_ref_or_code: str, *, search_scope: str | None = None) -> Concept:msg = "get_required_entry_concept must not be called for a structureless render"diff --git a/tests/unit/pipelex/core/stuffs/test_composite_content.py b/tests/unit/pipelex/core/stuffs/test_composite_content.pyindex 0ae0068fb..e39c7e78b 100644--- a/tests/unit/pipelex/core/stuffs/test_composite_content.py+++ b/tests/unit/pipelex/core/stuffs/test_composite_content.py@@ -1,5 +1,7 @@+from collections.abc import Callablefrom typing import cast+import pytestfrom kajson import kajsonfrom pipelex.core.concepts.concept_factory import ConceptFactory@@ -14,6 +16,11 @@ from pipelex.runtime_bridge.primitives.hydration import hydrate_working_memoryclass TestCompositeContent:+ @pytest.fixture(scope="class", autouse=True)+ def _open_library(self, load_empty_library: Callable[[], str]) -> None:+ """Hydration resolves each stuff's concept ref through the current library, so one must be open."""+ load_empty_library()+def test_named_sub_contents_are_top_level_fields(self):"""Branch names must surface as top-level serialized fields, with no wrapper key."""composite = CompositeContent.model_validate(diff --git a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py b/tests/unit/pipelex/kernel/test_kernel_boot_contract.pyindex f7520706a..4f440b21a 100644--- a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py+++ b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py@@ -151,6 +151,12 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(def get_required_concept(self, concept_ref):return ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode(concept_ref.split(".")[-1]))+ @override+ def list_concept_keys_for_ref(self, *, concept_ref):+ # A library-free provider holds no entries to enumerate: the native set is built on+ # demand by the factory above, never stored under a key.+ return []+@overridedef get_native_concept(self, native_concept):return ConceptFactory.make_native_concept(native_concept_code=native_concept)diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.pyindex a7bd08563..d21d78845 100644--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py@@ -24,6 +24,7 @@ from pipelex.core.pipes.pipe_io_artifacts import (from pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.graph.graphspec import GraphSpec, PipelineRef+from pipelex.interpreter_hub import get_concept_library, get_current_library_id_or_none, get_library_manager, scoped_current_libraryfrom pipelex.pipe_run.delivery_assignment import (DeliveryAssignment,DeliveryStatus,@@ -476,12 +477,7 @@ class TestDeliveryExecutor:stuff_raw = {"stuff_code": "test","stuff_name": "greeting",- "concept": {- "code": "Text",- "domain_code": "native",- "description": "Plain text",- "structure_class_name": "TextContent",- },+ "concept": "native.Text","content": {"text": "Hello!"},}@@ -491,7 +487,8 @@ class TestDeliveryExecutor:assert isinstance(result.content, TextContent)assert result.content.text == "Hello!"- async def test_try_local_hydrate_stuff_returns_none_for_missing_class(self, mocker: MockerFixture) -> None:+ async def test_try_local_hydrate_stuff_returns_none_for_unknown_concept(self, mocker: MockerFixture) -> None:+ """A dynamic concept is unknown to a crate-free delivery worker: the ref resolves to nothing, the raw render takes over."""from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]warn_spy = mocker.spy(pipelex_log, "warning")@@ -499,12 +496,7 @@ class TestDeliveryExecutor:stuff_raw = {"stuff_code": "test","stuff_name": "x",- "concept": {- "code": "Greeting",- "domain_code": "dynamic_test",- "description": "Dynamic concept",- "structure_class_name": "dynamic_test__Greeting",- },+ "concept": "dynamic_test.Greeting","content": {"message": "hi"},}@@ -526,6 +518,180 @@ class TestDeliveryExecutor:assert result is Noneassert warn_spy.call_count == 1+ async def test_try_local_hydrate_stuff_returns_none_for_object_form_concept(self, mocker: MockerFixture) -> None:+ """The full-object concept a stale runtime dumped is not a shape the reader accepts: raw render, with a warning."""+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]++ warn_spy = mocker.spy(pipelex_log, "warning")++ stuff_raw: dict[str, object] = {+ "stuff_code": "test",+ "stuff_name": "greeting",+ "concept": {"code": "Text", "domain_code": "native", "description": "Plain text", "structure_class_name": "TextContent"},+ "content": {"text": "Hello!"},+ }++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None+ assert warn_spy.call_count == 1+ assert "concept ref string" in str(warn_spy.call_args)++ async def test_try_local_hydrate_stuff_resolves_the_native_concept_without_a_library(self) -> None:+ """A crate-free delivery worker has no current library; a native ref still resolves, from the pinned native set."""+ assert get_current_library_id_or_none() is None++ stuff_raw = {"stuff_code": "test", "stuff_name": "greeting", "concept": "native.Text", "content": {"text": "Hello!"}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is not None+ assert result.concept.concept_ref == "native.Text"+ assert result.concept.structure_class_name == "TextContent"++ @pytest.mark.parametrize("malformed_ref", ["native..Text", "native.", ".Text"])+ async def test_try_local_hydrate_stuff_renders_raw_on_a_malformed_ref(self, malformed_ref: str) -> None:+ """A malformed ref is "not known here" like any other: rendering a result must never fail a delivery.++ Without a current library the ref goes to the native check, which parses it — and a ref with a+ leading, trailing or doubled dot raises there. That raise used to escape this method's own+ handler tuple and kill the delivery before the webhook ever fired.+ """+ assert get_current_library_id_or_none() is None++ stuff_raw = {"stuff_code": "test", "stuff_name": "greeting", "concept": malformed_ref, "content": {"text": "Hello!"}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None++ async def test_try_local_hydrate_stuff_renders_raw_when_the_current_library_is_gone(self) -> None:+ """The contextvar naming a library is not the same fact as that library still being there.++ A delivery outlives the run it renders, so the binding can survive the library it names. That+ is a race to survive with a raw render, not a reason to fail the delivery.+ """+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ with scoped_current_library(library_id=library_id):+ library_manager.teardown(library_id=library_id)+ stuff_raw = {"stuff_code": "test", "stuff_name": "greeting", "concept": "native.Text", "content": {"text": "Hello!"}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None++ async def test_try_local_hydrate_stuff_resolves_through_the_current_library(self) -> None:+ """When a library is current — an in-process run delivering its own result — the ref is resolved there."""+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ try:+ with scoped_current_library(library_id=library_id):+ stuff_raw = {"stuff_code": "test", "stuff_name": "greeting", "concept": "native.Text", "content": {"text": "Hello!"}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is not None+ assert result.concept is get_concept_library().get_required_concept(concept_ref="native.Text")+ assert isinstance(result.content, TextContent)+ finally:+ library_manager.teardown(library_id=library_id)++ async def test_try_local_hydrate_stuff_within_a_library_falls_back_on_unknown_ref(self, mocker: MockerFixture) -> None:+ """A ref the current library does not hold falls back to the raw render rather than raising."""+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]++ warn_spy = mocker.spy(pipelex_log, "warning")+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ try:+ with scoped_current_library(library_id=library_id):+ stuff_raw = {"stuff_code": "test", "stuff_name": "x", "concept": "dynamic_test.Greeting", "content": {"message": "hi"}}++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None+ assert warn_spy.call_count == 1+ assert "dynamic_test.Greeting" in str(warn_spy.call_args)+ finally:+ library_manager.teardown(library_id=library_id)++ async def test_try_local_hydrate_stuff_resolves_a_dependency_contributed_concept(self) -> None:+ """A concept only a dependency package declares is keyed under its alias, and the bare wire ref still finds it."""+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ dependency_concept = Concept(+ code="WeightedScore",+ domain_code="delivery_scoring",+ description="the score as the dependency package shapes it",+ structure_class_name="TextContent",+ )+ try:+ with scoped_current_library(library_id=library_id):+ get_concept_library().add_dependency_concept(alias="github.com/mthds/scoring-lib/scoring_lib", concept=dependency_concept)+ stuff_raw = {+ "stuff_code": "test",+ "stuff_name": "score",+ "concept": "delivery_scoring.WeightedScore",+ "content": {"text": "87"},+ }++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is not None+ assert result.concept.description == "the score as the dependency package shapes it"+ assert isinstance(result.content, TextContent)+ finally:+ library_manager.teardown(library_id=library_id)++ async def test_try_local_hydrate_stuff_renders_raw_on_an_ambiguous_ref(self, mocker: MockerFixture) -> None:+ """A spelling a host bundle and a dependency share is logged and rendered raw, never bound to one of them.++ This reader must never fail a delivery, so the collision that hydration refuses outright+ degrades here to the same raw-render fallback an unknown ref takes — with the colliding+ keys named in the log so the cause is not invisible.+ """+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]++ warn_spy = mocker.spy(pipelex_log, "warning")+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ try:+ with scoped_current_library(library_id=library_id):+ concept_library = get_concept_library()+ concept_library.add_new_concept(+ Concept(+ code="WeightedScore",+ domain_code="delivery_scoring",+ description="the HOST's weighted score",+ structure_class_name="TextContent",+ )+ )+ concept_library.add_dependency_concept(+ alias="github.com/mthds/scoring-lib/scoring_lib",+ concept=Concept(+ code="WeightedScore",+ domain_code="delivery_scoring",+ description="the dependency's weighted score",+ structure_class_name="TextContent",+ ),+ )+ stuff_raw = {+ "stuff_code": "test",+ "stuff_name": "score",+ "concept": "delivery_scoring.WeightedScore",+ "content": {"text": "87"},+ }++ result = DeliveryExecutor.try_local_hydrate_stuff(stuff_raw)++ assert result is None+ logged = " ".join(str(call) for call in warn_spy.call_args_list)+ assert "ambiguous" in logged+ assert "github.com/mthds/scoring-lib/scoring_lib->delivery_scoring.WeightedScore" in logged+ finally:+ library_manager.teardown(library_id=library_id)+async def test_raw_fallback_html_escapes_special_chars(self, mocker: MockerFixture) -> None:"""Fallback HTML rendering must escape HTML-special chars to prevent XSS.@@ -538,12 +704,7 @@ class TestDeliveryExecutor:"root": {"main_stuff": {"stuff_code": "main_stuff",- "concept": {- "code": "Unknown",- "domain_code": "dynamic_test",- "description": "Dynamic concept not registered locally",- "structure_class_name": "dynamic_test__Unknown",- },+ "concept": "dynamic_test.Unknown","content": {"payload": "</pre><script>alert(1)</script><pre>"},}},@@ -597,12 +758,7 @@ class TestDeliveryExecutor:"cv_pages": {"stuff_code": "cv_pages","stuff_name": "cv_pages",- "concept": {- "code": "Page",- "domain_code": "native",- "description": "A page",- "structure_class_name": "PageContent",- },+ "concept": "native.Page","content": [page],}},diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.pyindex 855a5b1b9..5a1cc7c9f 100644--- a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py@@ -1,5 +1,6 @@import datetimeimport json+from collections.abc import Callablefrom typing import Any, castimport pytest@@ -8,12 +9,21 @@ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.memory.absence import AbsenceKind, AbsenceRecordfrom pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.pipes.pipe_output import PipeOutputfrom pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.number_content import NumberContentfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.core.stuffs.yes_no_content import YesNoContent+from pipelex.interpreter_hub import (+ clear_current_library,+ get_concept_library,+ get_current_library_id_or_none,+ get_library_manager,+ scoped_current_library,+ set_current_library,+)from pipelex.pipe_run.exceptions import PipeJobErrorfrom pipelex.runtime_bridge.primitives.hydration import (_hydrate_list_item, # pyright: ignore[reportPrivateUsage]@@ -63,6 +73,11 @@ def _make_date_concept() -> Concept:class TestHydrateWorkingMemory:+ @pytest.fixture(scope="class", autouse=True)+ def _open_library(self, load_empty_library: Callable[[], str]) -> None:+ """A stuff names its concept by ref, and the hydrator resolves it through the current library."""+ load_empty_library()+@pytest.fixture(autouse=True)def _register_content_classes(self) -> None:"""Ensure TextContent and NumberContent are registered for hydration tests."""@@ -312,18 +327,47 @@ class TestHydrateWorkingMemory:assert isinstance(result, NumberContent)assert result.number == 42- def test_hydrate_raises_on_missing_registry_class(self) -> None:- """Hydration raises PipeJobError when the concept's structure_class_name is not in the registry."""+ def test_every_dump_carries_the_concept_ref_string(self) -> None:+ """Every dump of a working memory names a stuff's concept by ref: the definition never leaves the runtime."""+ working_memory = WorkingMemory()+ working_memory.root["greeting"] = _make_text_stuff("greeting", "Hello!")+ pipe_output = PipeOutput(working_memory=working_memory, pipeline_run_id="run-dump")++ dumps: dict[str, dict[str, Any]] = {+ "model_dump": working_memory.model_dump(),+ "smart_dump": working_memory.smart_dump(),+ "dump_for_transport": working_memory.dump_for_transport(),+ "json_mode": working_memory.model_dump(mode="json", serialize_as_any=True),+ "pipe_output": pipe_output.model_dump(mode="json", serialize_as_any=True)["working_memory"],+ }++ for dump_name, dump in dumps.items():+ assert dump["root"]["greeting"]["concept"] == "native.Text", dump_name+ assert working_memory.root["greeting"].model_dump()["concept"] == "native.Text"++ def test_hydrate_resolves_the_concept_through_the_library(self) -> None:+ """The hydrated stuff carries the library's own Concept, definition and all, not one rebuilt from the wire."""+ working_memory = WorkingMemory()+ working_memory.root["greeting"] = _make_text_stuff("greeting", "Hello!")++ hydrated = hydrate_working_memory(working_memory.dump_for_transport())++ concept = hydrated.root["greeting"].concept+ assert concept is get_concept_library().get_required_concept(concept_ref="native.Text")+ assert concept.structure_class_name == "TextContent"++ def test_hydrate_refuses_the_object_form(self) -> None:+ """The full-object concept the runtime once dumped is not a shape the reader accepts."""raw = {"root": {- "bad_stuff": {+ "greeting": {"stuff_code": "test",- "stuff_name": "bad_stuff",+ "stuff_name": "greeting","concept": {- "code": "NonExistent",+ "code": "Text","domain_code": "native",- "description": "Missing class",- "structure_class_name": "NonExistentContent",+ "description": "Plain text",+ "structure_class_name": "TextContent",},"content": {"text": "hello"},},@@ -331,9 +375,127 @@ class TestHydrateWorkingMemory:"aliases": {},}+ with pytest.raises(PipeJobError, match="concept ref string"):+ hydrate_working_memory(raw)++ def test_hydrate_without_a_library_resolves_a_native_ref(self) -> None:+ """No current library is a live path, not a fixture, and the pinned native set answers on its own.++ ``Pipelex.make()`` sets no current library, and on the transport boundary+ ``scoped_library_for_crate(None, …)`` is a documented no-op that falls back to the active+ class registry — so a precondition demanding a library would break a hydration that has+ everything it needs.+ """+ working_memory = WorkingMemory()+ working_memory.root["greeting"] = _make_text_stuff("greeting", "Hello!")+ raw = working_memory.dump_for_transport()+ library_id = get_current_library_id_or_none()+ assert library_id is not None++ clear_current_library()+ try:+ hydrated = hydrate_working_memory(raw)+ finally:+ set_current_library(library_id=library_id)++ assert hydrated.root["greeting"].concept.concept_ref == "native.Text"+ assert hydrated.root["greeting"].content == TextContent(text="Hello!")++ def test_hydrate_without_a_library_refuses_a_non_native_ref(self) -> None:+ """Only a loaded library holds a bundle-declared concept's definition, so the refusal names the stuff."""+ raw: dict[str, Any] = {+ "root": {+ "invoice": {+ "stuff_code": "test",+ "stuff_name": "invoice",+ "concept": "accounting.Invoice",+ "content": {"text": "hello"},+ },+ },+ "aliases": {},+ }+ library_id = get_current_library_id_or_none()+ assert library_id is not None++ clear_current_library()+ try:+ with pytest.raises(PipeJobError, match="invoice") as exc_info:+ hydrate_working_memory(raw)+ finally:+ set_current_library(library_id=library_id)++ assert "accounting.Invoice" in str(exc_info.value)+ assert "no library is current" in str(exc_info.value)++ def test_hydrate_raises_on_unknown_concept_ref(self) -> None:+ """Hydration raises PipeJobError when the stuff names a concept the loaded library does not hold."""+ raw = {+ "root": {+ "bad_stuff": {+ "stuff_code": "test",+ "stuff_name": "bad_stuff",+ "concept": "native.NonExistent",+ "content": {"text": "hello"},+ },+ },+ "aliases": {},+ }+with pytest.raises(PipeJobError, match="bad_stuff"):hydrate_working_memory(raw)+ def test_hydrate_raises_pipe_job_error_when_the_current_library_is_gone(self) -> None:+ """Every failure in this function is normalized to PipeJobError, the stale-binding one included.++ The guard tests whether a library is *named*, not whether it is still *there*, so a binding that+ outlived its library used to surface a raw LibraryError from the hub — an exception every caller+ of this function was written not to expect.+ """+ library_manager = get_library_manager()+ library_id, _ = library_manager.open_library()+ with scoped_current_library(library_id=library_id):+ library_manager.teardown(library_id=library_id)+ working_memory_raw: dict[str, Any] = {+ "root": {"greeting": {"stuff_code": "test", "stuff_name": "greeting", "concept": "native.Text", "content": {"text": "Hello!"}}}+ }++ with pytest.raises(PipeJobError, match="no longer reachable"):+ hydrate_working_memory(working_memory_raw)++ def test_hydrate_raises_when_the_structure_class_is_not_registered(self) -> None:+ """A concept the library holds whose structure class this process never registered still refuses clearly.++ Resolving the ref and finding the content class are two separate failures, and the ref+ resolving is no guarantee the class is here: a dynamic concept travels to a worker that+ never loaded the crate that defines it.+ """+ concept_library = get_concept_library()+ concept_library.add_new_concept(+ Concept(+ code="Unregistered",+ domain_code=SpecialDomain.NATIVE,+ description="A concept whose structure class this process never registered",+ structure_class_name="NotRegisteredContent",+ )+ )+ raw = {+ "root": {+ "bad_stuff": {+ "stuff_code": "test",+ "stuff_name": "bad_stuff",+ "concept": "native.Unregistered",+ "content": {"text": "hello"},+ },+ },+ "aliases": {},+ }++ try:+ with pytest.raises(PipeJobError, match="bad_stuff"):+ hydrate_working_memory(raw)+ finally:+ concept_library.remove_concepts_by_concept_refs(["native.Unregistered"])+def test_hydrate_raises_on_validation_error(self) -> None:"""Hydration raises PipeJobError when content doesn't match the expected schema."""raw = {@@ -341,12 +503,7 @@ class TestHydrateWorkingMemory:"invalid_stuff": {"stuff_code": "test","stuff_name": "invalid_stuff",- "concept": {- "code": "Text",- "domain_code": "native",- "description": "Plain text",- "structure_class_name": "TextContent",- },+ "concept": "native.Text","content": {"completely_wrong_field": 42},},},diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_wire_concept_ref_resolution.py b/tests/unit/pipelex/runtime_bridge/primitives/test_wire_concept_ref_resolution.pynew file mode 100644index 000000000..5ff63a37e--- /dev/null+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_wire_concept_ref_resolution.py@@ -0,0 +1,123 @@+from collections.abc import Callable++import pytest++from pipelex.core.concepts.concept import Concept+from pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.stuffs.stuff import Stuff+from pipelex.core.stuffs.text_content import TextContent+from pipelex.interpreter_hub import get_concept_library+from pipelex.pipe_run.exceptions import PipeJobError+from pipelex.runtime_bridge.primitives.hydration import hydrate_working_memory+from pipelex.runtime_hub import get_class_registry++#: On the live route a dependency's alias is its whole package address (`_load_address_based_dependency`),+#: so the key a dependency concept lands under is long and contains slashes — which the enumeration must+#: still match on its `-><domain>.<Code>` tail alone.+_DEPENDENCY_ALIAS = "github.com/mthds/scoring-lib/scoring_lib"+_SHARED_SPELLING = "wire_ref_scoring.WeightedScore"+++def _make_weighted_score_concept(description: str) -> Concept:+ return Concept(+ code="WeightedScore",+ domain_code="wire_ref_scoring",+ description=description,+ structure_class_name="TextContent",+ )+++class TestWireConceptRefResolution:+ """A stuff names its concept `<domain>.<Code>`, and the library is what says which package meant it.++ This runtime emits only that form. The standard also defines `<package_address>::<domain>.<Code>`+ for a concept a dependency contributes, which this runtime neither emits nor resolves — so a+ dependency's concept arrives spelled exactly like a host's, and the library holds it under+ `<alias>-><domain>.<Code>` with no unaliased twin. One candidate is the answer; two are a+ collision no ref can settle.+ """++ @pytest.fixture(scope="class", autouse=True)+ def _open_library(self, load_empty_library: Callable[[], str]) -> None:+ load_empty_library()++ @pytest.fixture(autouse=True)+ def _register_content_classes(self) -> None:+ registry = get_class_registry()+ if not registry.has_class(name="TextContent"):+ registry.register_class(TextContent)++ @pytest.fixture(autouse=True)+ def _clean_concepts(self):+ yield+ get_concept_library().remove_concepts_by_concept_refs([_SHARED_SPELLING, f"{_DEPENDENCY_ALIAS}->{_SHARED_SPELLING}"])++ def test_a_dependency_contributed_concept_round_trips(self) -> None:+ """A concept only a dependency declares hydrates back, through its aliased entry.++ This is the parity claim: back when the definition rode along on the wire, such a stuff+ rebuilt itself without any lookup. With the ref alone, the aliased key is the only entry+ that holds it — a direct lookup by the bare ref misses.+ """+ dependency_concept = _make_weighted_score_concept("the score as the dependency package shapes it")+ get_concept_library().add_dependency_concept(alias=_DEPENDENCY_ALIAS, concept=dependency_concept)+ working_memory = WorkingMemory()+ working_memory.root["score"] = Stuff(+ stuff_code="s1",+ stuff_name="score",+ concept=dependency_concept,+ content=TextContent(text="87"),+ )++ raw = working_memory.dump_for_transport()+ assert raw["root"]["score"]["concept"] == _SHARED_SPELLING++ hydrated = hydrate_working_memory(raw)++ assert hydrated.root["score"].concept.concept_ref == _SHARED_SPELLING+ assert hydrated.root["score"].concept.description == "the score as the dependency package shapes it"+ assert hydrated.root["score"].content == TextContent(text="87")++ def test_a_spelling_two_packages_share_refuses_by_name(self) -> None:+ """A host bundle and a dependency spelling the same `<domain>.<Code>` refuse, listing both keys.++ This is the case that used to bind the host's definition to the dependency's data with no+ error at all, which is worse than a failure: wrong data, silently.+ """+ host_concept = _make_weighted_score_concept("the HOST's weighted score")+ dependency_concept = _make_weighted_score_concept("the dependency's weighted score")+ concept_library = get_concept_library()+ concept_library.add_new_concept(host_concept)+ concept_library.add_dependency_concept(alias=_DEPENDENCY_ALIAS, concept=dependency_concept)+ working_memory = WorkingMemory()+ working_memory.root["score"] = Stuff(+ stuff_code="s1",+ stuff_name="score",+ concept=dependency_concept,+ content=TextContent(text="87"),+ )++ with pytest.raises(PipeJobError) as exc_info:+ hydrate_working_memory(working_memory.dump_for_transport())++ message = str(exc_info.value)+ assert "score" in message+ assert "ambiguous" in message+ assert _SHARED_SPELLING in message+ assert f"{_DEPENDENCY_ALIAS}->{_SHARED_SPELLING}" in message++ def test_the_host_entry_alone_still_resolves(self) -> None:+ """With no dependency contributing that spelling, the host entry is the one candidate."""+ host_concept = _make_weighted_score_concept("the HOST's weighted score")+ get_concept_library().add_new_concept(host_concept)+ working_memory = WorkingMemory()+ working_memory.root["score"] = Stuff(+ stuff_code="s1",+ stuff_name="score",+ concept=host_concept,+ content=TextContent(text="87"),+ )++ hydrated = hydrate_working_memory(working_memory.dump_for_transport())++ assert hydrated.root["score"].concept.description == "the HOST's weighted score"diff --git a/uv.lock b/uv.lockindex 188b8e855..c26d0eb66 100644--- a/uv.lock+++ b/uv.lock@@ -2552,7 +2552,7 @@ wheels = [[[package]]name = "mthds"-version = "0.14.0"+version = "0.15.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "httpx" },@@ -2561,9 +2561,9 @@ dependencies = [{ name = "tomlkit" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/92/59/4ca9539571a2030f9427aeddb01bc334910953ebdfa4ab7db2051a6b8ae7/mthds-0.14.0.tar.gz", hash = "sha256:d2b4a9cd064004dfd5b802bb71c9894601fba9e598426f96e4bede16d52c3900", size = 221186, upload-time = "2026-09-06T21:44:54.585Z" }+sdist = { url = "https://files.pythonhosted.org/packages/54/16/1aa1219f44bc469213018478f582eb4eb28f69ea43a09fe73afc9cfb4e34/mthds-0.15.0.tar.gz", hash = "sha256:2e612174b089cae799eb236f5b1bcd183b8847a62a06a265f72f0e50b4c89555", size = 250552, upload-time = "2026-09-18T20:23:09.888Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/28/0b/32908eeed33396c5aafd4bcb2a1adc38d0ab8d85c2fde3af0bf4c2f73745/mthds-0.14.0-py3-none-any.whl", hash = "sha256:59a706205b6e6df47345caac01038588d21ab9e9c246afc765ee50b5f27f05a8", size = 87192, upload-time = "2026-09-06T21:44:53.022Z" },+ { url = "https://files.pythonhosted.org/packages/c0/5c/7526815d8bc8cd8690c8cf4de3819e3f322886280af05bf9aed7bdce450c/mthds-0.15.0-py3-none-any.whl", hash = "sha256:98670ca1f97fc2211ace0f404acd416ce5882edb728845d48440d6e73eedc34c", size = 99711, upload-time = "2026-09-18T20:23:08.283Z" },][[package]]@@ -3472,7 +3472,7 @@ requires-dist = [{ name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },{ name = "mkdocs-redirects", marker = "extra == 'docs'", specifier = "==1.2.2" },{ name = "moto", extras = ["dynamodb", "s3"], marker = "extra == 'dev'", specifier = ">=5.0.0" },- { name = "mthds", specifier = "==0.14.0" },+ { name = "mthds", specifier = "==0.15.0" },{ name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" },{ name = "networkx", specifier = ">=3.4.2" },{ name = "openai", specifier = ">=2.0.0" },