Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Fix PR #1052 review findings: PipeFunc transport hardening + review follow-ups (#1056)
Louis Choquelf6776a439ef0
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 5f09f3767..4aef20904 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "9113",+ "message": "9120","color": "blue","cacheSeconds": 300}\ No newline at end of filediff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex 6f3ff9966..d63e71734 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -2,7 +2,7 @@ contract = "config-docs"digest = "sha256:5edb794b698cc0513be0e904c3a2f82a1a7ff470e86d05df5e710dd30368ee25"reviewed_by = "Claude (Fable 5)"reviewed_at = "2026-07-16T09:45:00Z"-rationale = "Trigger diff is comment-only wording in pipelex.toml + pipe_func_config.py: removed the stale claim of a core 'local_sandbox' execution mode (nobody registers it; core ships only 'direct', our Daytona plugin ships 'daytona') and switched plugin mentions to the 'our Daytona sandbox plugin' style. No field, type, or default changed. Reviewed docs/configuration: pipe_func_config still deliberately has no page (like its internal siblings), library-config.md's @pipe_func registration prose is unaffected, and no configuration doc mentions local_sandbox — nothing to update."+rationale = "Trigger diff: configs.py wires the new pipe_func section onto the main config model (PipeFuncConfig import + pipe_func_config field on Pipelex), plus comment-only wording in pipelex.toml + pipe_func_config.py: removed the stale claim of a core 'local_sandbox' execution mode (nobody registers it; core ships only 'direct', our Daytona plugin ships 'daytona') and switched plugin mentions to the 'our Daytona sandbox plugin' style. No default changed. Reviewed docs/configuration: pipe_func_config (incl. its new attachment on the root model) deliberately has no page, like its internal siblings; library-config.md's @pipe_func registration prose is unaffected; no configuration doc mentions local_sandbox — nothing to update. (Rationale amended 2026-07-17: the original wrongly described the trigger diff as comment-only, omitting the configs.py field wiring; the reviewed conclusion is unchanged.)"[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:fca7b96f9147122b6b8300471cac637b05fed1ee"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ff398b916..2cf0d010b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,10 @@### Fixed- **Validation errors stay domain-qualified: every raise site that names a `pipe_code` now also carries `domain_code`.** The presentation chain (VS Code extension + mthds-ui) identifies pipes by full pipe ref (`domain_code.pipe_code`); a handful of `PipeValidationError` raise sites (PipeLLM static input checks, PipeStructure input-mismatch, the pipe sorter's circular-dependency error) omitted `domain_code`, degrading node decorations and click-to-navigate for those errors in multi-domain bundles. The sorter gains a `domain_code` parameter threaded from the bundle spec's domain.+- **Hosted PipeFunc dry runs now honor output multiplicity.** In sandbox-hosted mode a PipeFunc with a multiplicity output (e.g. `Foo[]`) mocked a single scalar item because the function annotation is unavailable in-process; downstream pipes expecting a list (e.g. `batch_over`) then failed the dry-run/`/validate` of a perfectly valid method. The mock now takes its shape from the declared output multiplicity.+- **`get_optional_config()` honors its non-raising contract before any hub exists.** It used to raise `RuntimeError: PipelexHub is not initialized` when no hub had been created at all, which broke the documented safe pre-boot path — e.g. constructing a `PipeFunc` in an isolated unit test crashed instead of defaulting to the `direct` execution mode.+- **PipeFunc transport hardening:** the wire contract now rejects a non-finite `timeout_seconds` (`float("inf")` used to disable the runaway-code guard entirely), and the transported executor removes its materialized source workdir on every path (success, timeout, failure) instead of leaking a temp directory per invocation, pruning the `sys.path` entries it inserted for that workdir in the same cleanup so dead entries can't accumulate (or be hijacked by a recreated path) in a reused process.+- **Error reference pages generated for the PipeFunc transport errors** (`PipeFuncTransportError`, `PipeFuncExecutionError`, `DuplicatePipeFuncExecutorError`, `UnknownPipeFuncExecutionModeError`) — their `type_uri`s previously dereferenced to 404s.## [v0.39.2] - 2026-07-17diff --git a/TODOS.md b/TODOS.mdindex d25ff9cf6..f11d162cc 100644--- a/TODOS.md+++ b/TODOS.md@@ -1,6 +1,6 @@# PipeCompose construct: whole-stuff → native-field conversion fixes-**Status: GREEN — CHECKPOINT 2 reached (2026-07-17). Phases 1+2+3 complete: fix landed and verified, docs + changelog written. Remaining: Phase 4 cross-repo follow-ups, release-gated — do NOT do them before a pipelex release ships the fix.**+**Status: GREEN — CHECKPOINT 2 closed. Phases 1+2+3 complete: fix landed and verified (PR #1051 merged to `dev`, shipped in release v0.39.2). Remaining: Phase 4 cross-repo follow-ups — now DE-GATED since v0.39.2 ships the fix.**## Cold-start state (as of Checkpoint 2, 2026-07-17)@@ -20,7 +20,7 @@A user designing a method with `/pipelex-design` used PipeCompose construct mode to copy whole native stuffs into native-typed fields of a structured output — `rejection_email = { from = "email" }` where `email` is a whole `Text` stuff, and `interview_questions = { from = "questions" }` where `questions` is a whole `Text[5]` stuff. Structural validation accepted it; the dry-run runnable gate rejected it because the composed field received the content wrapper object (`TextContent`, `ListContent[...]`) instead of the native value (`str`, `list[str]`). The user's usage was correct: the PipeCompose reference (`docs/building-methods/pipes/pipe-operators/PipeCompose.md`, "Copy value from input variable or nested field") and the composer's own design (`_resolve_from_var` docstring: "TextContent -> str: extract .text", "ListContent -> list[X]: extract items") both promise exactly this conversion. The implementation has gaps. **Verdict: fix pipelex, do not change the language or warn users off the pattern.**-Full analysis with the user's original bundle and reasoning: `/Users/lchoquel/repos/Pipelex/mcp-demos/wip/pipe-compose-issue/README.md` (+ runnable repro under `repro/`). Note: that README's §5/§8 conclude "whole-stuff `from` hands over the wrapper **by design**" — that is a misdiagnosis of these bugs as a language rule; this plan is the correction.+Full analysis with the user's original bundle and reasoning: `../mcp-demos/wip/pipe-compose-issue/README.md` (workspace sibling repo; + runnable repro under `repro/`). Note: that README's §5/§8 conclude "whole-stuff `from` hands over the wrapper **by design**" — that is a misdiagnosis of these bugs as a language rule; this plan is the correction.## Diagnosis — three gaps, all in `pipelex/pipe_operators/compose/structured_content_composer.py`@@ -30,9 +30,9 @@ All verified empirically against the dev tree (v0.39.1 era, branch `dev`):2. **List items that are native scalars are not extracted.** Even with a required `list`/`item_type = "text"` target (`List[str]`), `_convert_list_items_as_dicts` (`:501`) dumps each `TextContent` item as a dict `{"text": "..."}` via `model_dump` instead of extracting `.text` → `questions.N: string_type` pydantic errors. Related: `_validate_item_compatibility` (`:555`) silently no-ops when the expected item type has no `model_validate` (e.g. `str`), so the mismatch surfaces as a confusing downstream pydantic error rather than a clear conversion error.3. **Scalar wrappers other than `TextContent` are not handled at all.** `_convert_for_target_type` (`:298`) special-cases only `TextContent` and `ListContent`. A whole `Number` stuff into a required `number` field fails with `NumberContent (expected float)`. Same family presumably applies to `YesNo` → `boolean` and `Date` → `date` fields.-Reference matrix of what works vs. breaks today (from the repro):+Reference matrix of what worked vs. broke PRE-FIX (v0.39.1 behavior, from the repro — every ❌ row is green since the fix):-| Construct source | Target field | Today |+| Construct source | Target field | Pre-fix (v0.39.1) ||---|---|---|| `{ from = "score.candidate_name" }` (dotted path to scalar leaf) | any matching native | ✅ works (raw Python value, skips conversion) || literal (`is_fit = true`) | matching native | ✅ works |@@ -46,7 +46,7 @@ Reference matrix of what works vs. breaks today (from the repro):- `tests/e2e/test_pipe_compose_whole_stuff_mthds.py` — one dry-run test (`validate_bundle` must pass the runnable gate on every pipe) + one parametrized live test (deterministic PipeCompose execution, no inference, asserts composed values AND exact native types).- Fixture bundle: `tests/e2e/fixtures/compose_whole_stuff/compose_whole_stuff.mthds` — one holder concept + one compose pipe per row of the matrix above.-- Current state: `whole_text_to_required_text_field` (control) passes; the dry-run test and the other live cases fail with the wrapper-mismatch errors quoted in the diagnosis.+- Pre-fix state (red): `whole_text_to_required_text_field` (control) passed; the dry-run test and the other live cases failed with the wrapper-mismatch errors quoted in the diagnosis. All green since Phase 1 landed.- Run it: `.venv/bin/pytest -n auto -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" -o log_level=WARNING --tb=short -q tests/e2e/test_pipe_compose_whole_stuff_mthds.py`## Fix design@@ -106,9 +106,9 @@ All changes in `pipelex/pipe_operators/compose/structured_content_composer.py` (- [x] `CHANGELOG.md` `[Unreleased]` → Fixed: PipeCompose construct `{ from = "..." }` now converts whole native stuffs into optional native fields, native-scalar list items, and non-Text scalar wrappers (Number/YesNo/…)- [x] Grep `docs/` for other PipeCompose construct mentions that describe or constrain `from` semantics; align them (no other page describes construct `from`; error pages are generated boilerplate — nothing to change)-**CHECKPOINT 2 — ready for PR.** Commit, run the pre-push gates, open PR to `dev`. The cross-repo items below are release-gated — do NOT do them before a pipelex release ships the fix.+**CHECKPOINT 2 — ✅ CLOSED.** Committed, gates passed, PR #1051 merged to `dev`; the fix shipped in release v0.39.2.-### Phase 4 — cross-repo follow-ups (release-gated)+### Phase 4 — cross-repo follow-ups (de-gated by v0.39.2)- [ ] `pipelex-plugins/skills/pipelex-design/references/writing-mthds.md` (source of truth; per-target copies under `pipelex-plugins/{pipelex,pipelex-vibe,pipelex-codex}/skills/...`): add a worked whole-stuff copy example to the PipeCompose construct section. Do NOT add a "from must reference a structured field" warning — that would enshrine the bug- [ ] `mthds-plugins/mthds-dev/skills/shared/mthds-reference.md`: same check — align the construct `from` description if neededdiff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.mdindex c1834fdb8..95e9af68c 100644--- a/docs/errors/authoring-and-language.md+++ b/docs/errors/authoring-and-language.md@@ -68,6 +68,8 @@ own page. Classes are grouped by subsystem.- [`PipeComposeError`](pipe-compose-error.md) — Pipe compose- [`PipeComposeFactoryError`](pipe-compose-factory-error.md) — Pipe compose factory- [`PipeExtractFactoryError`](pipe-extract-factory-error.md) — Pipe extract factory+- [`PipeFuncExecutionError`](pipe-func-execution-error.md) — Pipe func execution+- [`PipeFuncTransportError`](pipe-func-transport-error.md) — Pipe func transport- [`PipeImgGenFactoryError`](pipe-img-gen-factory-error.md) — Pipe img gen factory- [`PipeImgGenRunError`](pipe-img-gen-run-error.md) — Pipe img gen run- [`PipeLLMFactoryError`](pipe-llm-factory-error.md) — Pipe LLM factorydiff --git a/docs/errors/duplicate-pipe-func-executor-error.md b/docs/errors/duplicate-pipe-func-executor-error.mdnew file mode 100644index 000000000..d95b9caf9--- /dev/null+++ b/docs/errors/duplicate-pipe-func-executor-error.md@@ -0,0 +1,21 @@+---+title: "Duplicate pipe func executor"+description: "Reference for the `DuplicatePipeFuncExecutorError` Pipelex error class."+---++<!-- pipelex:generated -->++# Duplicate pipe func executor++Two plugins registered a PipeFunc executor for the same execution mode.++| Field | Value |+|---|---|+| `error_type` | `DuplicatePipeFuncExecutorError` |+| `title` | Duplicate pipe func executor |+| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-pipe-func-executor-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.mdindex cc5adc3ad..795ffad6a 100644--- a/docs/errors/inference-and-providers.md+++ b/docs/errors/inference-and-providers.md@@ -90,6 +90,7 @@ own page. Classes are grouped by subsystem.- [`DuplicateInferenceBackendError`](duplicate-inference-backend-error.md) — Duplicate inference backend- [`DuplicateModelListerError`](duplicate-model-lister-error.md) — Duplicate model lister- [`DuplicateOrchestratorError`](duplicate-orchestrator-error.md) — Duplicate orchestrator+- [`DuplicatePipeFuncExecutorError`](duplicate-pipe-func-executor-error.md) — Duplicate pipe func executor- [`DuplicateSecretsProviderError`](duplicate-secrets-provider-error.md) — Duplicate secrets provider- [`DuplicateStorageProviderError`](duplicate-storage-provider-error.md) — Duplicate storage provider- [`GatewayCredentialsError`](gateway-credentials-error.md) — Gateway credentials@@ -113,6 +114,7 @@ own page. Classes are grouped by subsystem.- [`PortkeyError`](portkey-error.md) — Portkey- [`PortkeyFactoryError`](portkey-factory-error.md) — Portkey factory- [`UnknownBootOrchestratorError`](unknown-boot-orchestrator-error.md) — Unknown boot orchestrator+- [`UnknownPipeFuncExecutionModeError`](unknown-pipe-func-execution-mode-error.md) — Unknown pipe func execution mode- [`UnknownSecretsMethodError`](unknown-secrets-method-error.md) — Unknown secrets method- [`UnknownStorageMethodError`](unknown-storage-method-error.md) — Unknown storage method- [`VertexAIConfigError`](vertex-ai-config-error.md) — VertexAI configuration errordiff --git a/docs/errors/pipe-func-execution-error.md b/docs/errors/pipe-func-execution-error.mdnew file mode 100644index 000000000..28c1e03b9--- /dev/null+++ b/docs/errors/pipe-func-execution-error.md@@ -0,0 +1,21 @@+---+title: "Pipe func execution"+description: "Reference for the `PipeFuncExecutionError` Pipelex error class."+---++<!-- pipelex:generated -->++# Pipe func execution++A transported PipeFunc failed to run to a usable result out-of-process.++| Field | Value |+|---|---|+| `error_type` | `PipeFuncExecutionError` |+| `title` | Pipe func execution |+| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-execution-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.pipe_operators.func.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/pipe-func-transport-error.md b/docs/errors/pipe-func-transport-error.mdnew file mode 100644index 000000000..2c0f6aca6--- /dev/null+++ b/docs/errors/pipe-func-transport-error.md@@ -0,0 +1,21 @@+---+title: "Pipe func transport"+description: "Reference for the `PipeFuncTransportError` Pipelex error class."+---++<!-- pipelex:generated -->++# Pipe func transport++A PipeFunc could not be packaged for, or rebound from, out-of-process execution.++| Field | Value |+|---|---|+| `error_type` | `PipeFuncTransportError` |+| `title` | Pipe func transport |+| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-transport-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.pipe_operators.func.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/unknown-pipe-func-execution-mode-error.md b/docs/errors/unknown-pipe-func-execution-mode-error.mdnew file mode 100644index 000000000..04ad188aa--- /dev/null+++ b/docs/errors/unknown-pipe-func-execution-mode-error.md@@ -0,0 +1,21 @@+---+title: "Unknown pipe func execution mode"+description: "Reference for the `UnknownPipeFuncExecutionModeError` Pipelex error class."+---++<!-- pipelex:generated -->++# Unknown pipe func execution mode++A configured PipeFunc execution mode has no registered executor factory.++| Field | Value |+|---|---|+| `error_type` | `UnknownPipeFuncExecutionModeError` |+| `title` | Unknown pipe func execution mode |+| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-pipe-func-execution-mode-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/pipelex/core/validation.py b/pipelex/core/validation.pyindex 6da2690e3..08d11eeab 100644--- a/pipelex/core/validation.py+++ b/pipelex/core/validation.py@@ -1,6 +1,6 @@from pydantic import ValidationError-from pipelex.hub import PipelexHub+from pipelex.hub import get_optional_configfrom pipelex.system.configuration.configs import MigrationConfig, PipelexConfigfrom pipelex.tools.typing.pydantic_utils import analyze_pydantic_validation_error@@ -9,10 +9,9 @@ def report_validation_error(*, category: str, validation_error: ValidationError)validation_error_analysis = analyze_pydantic_validation_error(validation_error)# Doctor calls this from inside its bootstrap, where setup_config may have raised- # mid-flight and the hub's _config is still None. Reading via the optional getters+ # mid-flight and the hub's _config is still None. Reading via the optional getter# lets the friendly translation work without a try/except RuntimeError catch-all.- pipelex_hub = PipelexHub.get_optional_instance()- config = pipelex_hub.get_optional_config() if pipelex_hub is not None else None+ config = get_optional_config()migration_config: MigrationConfig | Noneif isinstance(config, PipelexConfig):migration_config = config.migrationdiff --git a/pipelex/hub.py b/pipelex/hub.pyindex 17fca8ddc..4e6fd0801 100644--- a/pipelex/hub.py+++ b/pipelex/hub.py@@ -514,7 +514,9 @@ def get_required_config() -> ConfigRoot:def get_optional_config() -> ConfigRoot | None:- return get_pipelex_hub().get_optional_config()+ """Non-raising by contract: also covers the no-hub-at-all state, not just hub-without-config."""+ pipelex_hub = PipelexHub.get_optional_instance()+ return pipelex_hub.get_optional_config() if pipelex_hub is not None else Nonedef get_secrets_provider() -> SecretsProviderAbstract:diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex e61cbb426..35e52038f 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -342,7 +342,10 @@ class LibraryManager(LibraryManagerAbstract):if is_sandbox_hosted:# Sandbox-hosted mode: never import/register the customer's PipeFunc bodies in this# process. Capture every .py as source text (no import) so it can travel to the- # sandbox, where it is registered and executed instead. Accumulate across dirs, but+ # sandbox, where it is registered and executed instead. No force-include here (unlike+ # the direct branch): the only force-included dir is pipelex's own builder package,+ # which must NOT travel in a customer crate — the sandbox has pipelex installed.+ # Accumulate across dirs, but# fail loud on a relpath collision: the sandbox writes sources flat by relpath, so two# dirs sharing a path would otherwise silently clobber one customer's code and run the# wrong PipeFunc body.diff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.pyindex 544cf1d4a..c581baeaa 100644--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py@@ -1,5 +1,6 @@import asyncioimport inspect+import shutilimport sysimport tempfilefrom pathlib import Path@@ -91,6 +92,18 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):concept (and thus its dynamic-class identity), rebound against the receiver's registry."""workdir = Path(tempfile.mkdtemp(prefix="pipelex_pipe_func_"))+ try:+ return await self._run_transported_from_workdir(request=request, workdir=workdir)+ finally:+ # The imported modules live on in memory; the materialized sources are only needed during+ # import, so the workdir is removed on every path (success, timeout, failure). The sys.path+ # entries inserted for that import are pruned too — the mkdtemp path is unique, so removing+ # exactly the entries under this workdir is safe even with concurrent transported runs+ # (unlike a snapshot/restore of the whole list).+ sys.path[:] = [entry for entry in sys.path if not Path(entry).is_relative_to(workdir)]+ shutil.rmtree(workdir, ignore_errors=True)++ async def _run_transported_from_workdir(self, *, request: PipeFuncExecutionRequest, workdir: Path) -> PipeFuncExecutionResponse:for relpath, source in request.crate.python_sources.items():target = workdir / relpathtarget.parent.mkdir(parents=True, exist_ok=True)@@ -102,10 +115,10 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):# file path (spec_from_file_location), which does NOT add its directory to sys.path either — so a# top-level `from helpers import ...` between sibling files raises ModuleNotFoundError, the module# never finishes importing, and its @pipe_func never registers. A local direct run does not hit- # this: its funcs were registered at boot from the real on-disk project already on sys.path. The- # box is one-shot and disposable, so mutating sys.path is safe: add workdir (resolves- # `from funcs.helpers import ...`) and every subdirectory holding a .py file (resolves the- # sibling-relative `from helpers import ...`).+ # this: its funcs were registered at boot from the real on-disk project already on sys.path. Add+ # workdir (resolves `from funcs.helpers import ...`) and every subdirectory holding a .py file+ # (resolves the sibling-relative `from helpers import ...`); the caller's finally prunes these+ # entries once the import phase is over, so they never outlive the run.source_dirs = {workdir} | {py_file.parent for py_file in workdir.rglob("*.py")}for source_dir in source_dirs:sys.path.insert(0, str(source_dir))@@ -125,7 +138,10 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):msg = f"Transported rehydration produced no working memory for pipe '{request.pipe_code}'"raise PipeFuncExecutionError(msg)- # Runaway-code guard: kill the PipeFunc if it runs past the request's (plan-dependent) timeout.+ # Runaway-code guard: time out the PipeFunc if it runs past the request's (plan-dependent)+ # deadline. Best-effort in-process — a blocking sync function keeps its worker thread; the+ # hard kill is the execution boundary's job (the sandbox destroys the box, the subprocess is+ # terminated).try:execution_result = await asyncio.wait_for(self.run_pipe_func(diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.pyindex 6fc91ba0b..9f6a38620 100644--- a/pipelex/pipe_operators/func/pipe_func.py+++ b/pipelex/pipe_operators/func/pipe_func.py@@ -284,7 +284,11 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)return_type = hinted_return_type- # TODO: Support PipeFunc returning with multiplicity. Create an equivalent of TypedNamedInputRequirement for outputs.+ # Without an annotation (hosted mode), `return_type` is the ITEM structure class, so the+ # declared output multiplicity decides the mock's shape; with a live annotation the return+ # type itself already carries the list-ness (`ListContent[...]`), so wrapping again would+ # double-nest.+ mock_multiplicity = (self.output.multiplicity or False) if function is None else Falsestuff_spec = TypedNamedStuffSpec(variable_name="mock_output",concept=ConceptFactory.make(@@ -294,9 +298,9 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):structure_class_name=self.output.concept.structure_class_name,),structure_class=return_type,- multiplicity=False,+ multiplicity=mock_multiplicity,)- mock_content = WorkingMemoryFactory.make_mock_content(stuff_spec)+ mock_content = WorkingMemoryFactory.make_mock_stuff(stuff_spec).contentoutput_stuff = StuffFactory.make_stuff(name=output_name,diff --git a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py b/pipelex/pipe_operators/func/pipe_func_execution_dtos.pyindex 05206f764..78ff026b0 100644--- a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py+++ b/pipelex/pipe_operators/func/pipe_func_execution_dtos.py@@ -11,7 +11,9 @@ from pipelex.pipeline.job_metadata import JobMetadata# can reference these types for its transported seam without closing an import cycle through the hub.# The hub-bound builders that produce/consume them live in ``pipe_func_execution_transport``.-# Runaway-code guard: how long a single PipeFunc may run out-of-process before it is killed. Lives on+# Runaway-code guard: how long a single PipeFunc may run out-of-process before it times out. The+# in-process guard is best-effort (it cannot interrupt a blocking sync function); the hard kill is+# the execution boundary's job — the sandbox destroys the box, the subprocess is terminated. Lives on# the request (not a process-wide setting) so it can vary per run — e.g. by the user's plan. 5s# default; the caller may raise it for a higher tier.DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS = 5.0@@ -39,7 +41,8 @@ class PipeFuncExecutionRequest(BaseModel):timeout_seconds: float = Field(default=DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS,gt=0,- description="Max wall-clock seconds the PipeFunc may run before it is killed (plan-dependent).",+ allow_inf_nan=False,+ description="Max wall-clock seconds the PipeFunc may run before it times out (plan-dependent).",)diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.pynew file mode 100644index 000000000..48399fd74--- /dev/null+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py@@ -0,0 +1,69 @@+import sys+from pathlib import Path++import pytest+from pydantic import ValidationError+from pytest_mock import MockerFixture++from pipelex.base_exceptions import PipelexError+from pipelex.hub import get_library_manager, scoped_current_library+from pipelex.libraries.library_crate import LibraryCrate+from pipelex.pipe_operators.func import direct_pipe_func_executor+from pipelex.pipe_operators.func.direct_pipe_func_executor import DirectPipeFuncExecutor+from pipelex.pipe_operators.func.pipe_func_execution_dtos import PipeFuncExecutionRequest+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipe_run.pipe_run_params import PipeRunParams+from pipelex.pipeline.job_metadata import JobMetadata+++class TestDirectExecutorWorkdir:+ @pytest.mark.asyncio+ async def test_transported_run_cleans_up_workdir_on_failure(self, tmp_path: Path, mocker: MockerFixture):+ """The materialized source workdir must not leak, even when the transported run fails."""+ workdir = tmp_path / "transported_workdir"+ workdir.mkdir()+ mocker.patch("tempfile.mkdtemp", return_value=str(workdir))++ request = PipeFuncExecutionRequest(+ crate=LibraryCrate(python_sources={"funcs.py": "x = 1\n"}),+ working_memory_raw={},+ pipe_code="missing_pipe",+ function_name="missing_func",+ job_metadata=JobMetadata(user_id="user", pipeline_run_id="run"),+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),+ )++ with scoped_current_library(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID): # noqa: SLF001 # pyright: ignore[reportPrivateUsage]+ try:+ with pytest.raises((PipelexError, ValidationError)):+ await DirectPipeFuncExecutor().run_pipe_func_transported(request=request)+ finally:+ get_library_manager().teardown(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert not workdir.exists()++ @pytest.mark.asyncio+ async def test_transported_run_restores_sys_path(self, tmp_path: Path, mocker: MockerFixture):+ """No sys.path entry under the workdir may survive a transported run, even a failing one."""+ workdir = tmp_path / "transported_workdir"+ workdir.mkdir()+ mocker.patch("tempfile.mkdtemp", return_value=str(workdir))++ request = PipeFuncExecutionRequest(+ crate=LibraryCrate(python_sources={"funcs/helpers.py": "x = 1\n"}),+ working_memory_raw={},+ pipe_code="missing_pipe",+ function_name="missing_func",+ job_metadata=JobMetadata(user_id="user", pipeline_run_id="run"),+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),+ )++ with scoped_current_library(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID): # noqa: SLF001 # pyright: ignore[reportPrivateUsage]+ try:+ with pytest.raises((PipelexError, ValidationError)):+ await DirectPipeFuncExecutor().run_pipe_func_transported(request=request)+ finally:+ get_library_manager().teardown(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ stale_entries = [entry for entry in sys.path if Path(entry).is_relative_to(workdir)]+ assert stale_entries == []diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.pyindex c3a133e77..f41eb0c94 100644--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py@@ -6,11 +6,18 @@ response must be JSON-serialization-safe (it crosses the Temporal activity boundmust forbid extras (it is a wire contract)."""+import pytest+from pydantic import ValidationError++from pipelex.libraries.library_crate import LibraryCratefrom pipelex.pipe_operators.func.pipe_func_execution_transport import (DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS,PipeFuncExecutionRequest,PipeFuncExecutionResponse,)+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipe_run.pipe_run_params import PipeRunParams+from pipelex.pipeline.job_metadata import JobMetadataclass TestPipeFuncExecutionTransport:@@ -30,4 +37,16 @@ class TestPipeFuncExecutionTransport:assert "crate" in PipeFuncExecutionRequest.model_fieldsassert "working_memory_raw" in PipeFuncExecutionRequest.model_fieldsassert PipeFuncExecutionRequest.model_fields["timeout_seconds"].default == DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS- assert DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS == 5.0++ def test_request_rejects_non_finite_timeout(self) -> None:+ """A non-finite timeout would disable the runaway-code guard, so the wire contract rejects it."""+ with pytest.raises(ValidationError):+ PipeFuncExecutionRequest(+ crate=LibraryCrate(),+ working_memory_raw={},+ pipe_code="my_pipe",+ function_name="my_func",+ job_metadata=JobMetadata(user_id="user", pipeline_run_id="run"),+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),+ timeout_seconds=float("inf"),+ )diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.pyindex 3c0e71d17..875dd8608 100644--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py@@ -4,9 +4,14 @@ import pytestfrom pydantic import ValidationErrorfrom pytest_mock import MockerFixture+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactoryfrom pipelex.core.pipes.pipe_factory import PipeFactory+from pipelex.core.stuffs.list_content import ListContentfrom pipelex.pipe_operators.func.pipe_func import PipeFuncfrom pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipe_run.pipe_run_params import PipeRunParams+from pipelex.pipeline.job_metadata import JobMetadata_UNREGISTERED = PipeFuncBlueprint(description="Hosted-mode case: function lives only in the sandbox, never in this process.",@@ -60,3 +65,33 @@ class TestPipeFuncHostedMode:pipe_func = _make_pipe_func()# Must not raise even though the function is not registered and its return type is unknown here.pipe_func.validate_output_with_library()++ @pytest.mark.asyncio+ async def test_hosted_dry_run_honors_output_multiplicity(+ self,+ load_empty_library: Callable[[], str],+ mocker: MockerFixture,+ ):+ """Hosted dry run must mock a list-shaped output for a multiplicity output like `Text[]`."""+ load_empty_library()+ mocker.patch("pipelex.pipe_operators.func.pipe_func.is_pipe_func_sandbox_hosted", return_value=True)+ blueprint = PipeFuncBlueprint(+ description="Hosted-mode multiplicity case: the mock output must be a list, not a scalar.",+ inputs={},+ output="native.Text[]",+ function_name="a_function_that_is_not_registered_here",+ )+ pipe_func = PipeFactory[PipeFunc].make_from_blueprint(+ domain_code="hosted_test",+ pipe_code="hosted_multiplicity_pipe",+ blueprint=blueprint,+ )++ pipe_output = await pipe_func._dry_run_operator_pipe( # noqa: SLF001 # pyright: ignore[reportPrivateUsage]+ job_metadata=JobMetadata(user_id="user", pipeline_run_id="run"),+ working_memory=WorkingMemoryFactory.make_empty(),+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),+ )++ content = pipe_output.working_memory.get_main_stuff().content+ assert isinstance(content, ListContent)diff --git a/tests/unit/pipelex/test_config_pre_boot.py b/tests/unit/pipelex/test_config_pre_boot.pynew file mode 100644index 000000000..28d8d833b--- /dev/null+++ b/tests/unit/pipelex/test_config_pre_boot.py@@ -0,0 +1,20 @@+from pytest_mock import MockerFixture++from pipelex.config import get_pipe_func_execution_mode, is_pipe_func_sandbox_hosted+from pipelex.hub import PipelexHub, get_optional_config+from pipelex.plugins.pipe_func_executor_registry import DIRECT_PIPE_FUNC_EXECUTION_MODE+++class TestConfigPreBoot:+ """The optional config accessors honor their non-raising contract before any hub exists."""++ def test_get_optional_config_returns_none_without_hub(self, mocker: MockerFixture):+ """With no PipelexHub instance at all, the optional getter returns None instead of raising."""+ mocker.patch.object(PipelexHub, "_instance", None)+ assert get_optional_config() is None++ def test_pipe_func_execution_mode_defaults_to_direct_without_hub(self, mocker: MockerFixture):+ """Pre-boot PipeFunc validation must default to direct, not crash on the missing hub."""+ mocker.patch.object(PipelexHub, "_instance", None)+ assert get_pipe_func_execution_mode() == DIRECT_PIPE_FUNC_EXECUTION_MODE+ assert is_pipe_func_sandbox_hosted() is Falsediff --git a/tests/unit/pipelex/tools/test_read_py_sources.py b/tests/unit/pipelex/tools/test_read_py_sources.pyindex 010d895a6..25e39e98e 100644--- a/tests/unit/pipelex/tools/test_read_py_sources.py+++ b/tests/unit/pipelex/tools/test_read_py_sources.py@@ -8,7 +8,7 @@ class TestReadPySources:"""read_py_sources captures every .py as text, recursively, WITHOUT ever importing it."""def test_captures_nested_sources_without_importing(self, tmp_path: Path):- """Nested .py files are captured by POSIX relpath, and no file is imported (sys.modules untouched).+ """Nested .py files are captured by POSIX relpath, and no file is imported.Each fixture file imports a module that does not exist: if read_py_sources imported any ofthem, the import would raise ModuleNotFoundError. It must not — it only reads the bytes.@@ -20,18 +20,16 @@ class TestReadPySources:nested_dir.mkdir()(nested_dir / "item.py").write_text(nested_source, encoding="utf-8")- modules_before = set(sys.modules)-sources = FuncRegistryUtils.read_py_sources(folder_path=tmp_path)assert sources == {"top.py": top_source,"structures/item.py": nested_source,}- # No import happened: the phantom modules are absent and sys.modules is unchanged.+ # No import happened: importing either fixture file would have raised on its phantom import,+ # and the phantom module names are absent from sys.modules.assert "this_module_does_not_exist_top" not in sys.modulesassert "this_module_does_not_exist_nested" not in sys.modules- assert set(sys.modules) == modules_beforedef test_empty_folder_returns_empty(self, tmp_path: Path):"""A folder with no Python files yields an empty mapping."""diff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.mdindex ecbae5b83..b2fee5956 100644--- a/wip/drift-contracts/dogfood-log.md+++ b/wip/drift-contracts/dogfood-log.md@@ -5,4 +5,4 @@ One entry per ack. Verdicts: **real-catch** (the review found actual staleness),- **2026-07-10 · keyword-only-convention · real-catch** — the guard gained the subject-grant registry (new violation kinds, literal-subject ban, symmetric staleness); the convention doc was materially stale and was rewritten as part of the same change — exactly the coupling this contract exists to enforce.- **2026-07-10 · cli-docs · clean-pass** — the keyword-only sweep touched many pipelex/cli files (kwonly'd internal signatures, two escape hatches, call-site keywords); reviewed docs/tools/cli/ and the agent-CLI CLAUDE.md — no command, flag, or output changed, both targets stay accurate.- **2026-07-11 · config-docs · clean-pass** — opened by dev's Python-3.10 drop reaching the branch via the Phase-M merge (StrEnum import swap in `img_gen_job_components.py`); reviewed docs/configuration/ — no config field, default, or documented behavior changed. *(Backfilled 2026-07-12: the ack was recorded during the subject-grants regrind without its mandatory log entry — process slip, not a review slip.)*-- **2026-07-16 · config-docs · clean-pass** — opened by comment-only wording fixes in `pipelex.toml` + `pipe_func_config.py` (dropped the stale core-`local_sandbox` mode claim, "our Daytona plugin" naming); reviewed docs/configuration/ — no field, default, or documented behavior changed, and the stale mode was never documented there. Note: the trigger correctly caught a *comment* fix in the shipped defaults file, which is user-readable surface — not friction.+- **2026-07-16 · config-docs · clean-pass** — opened by the pipe_func config wiring in `configs.py` (PipeFuncConfig import + `pipe_func_config` field on the Pipelex model) plus comment-only wording fixes in `pipelex.toml` + `pipe_func_config.py` (dropped the stale core-`local_sandbox` mode claim, "our Daytona plugin" naming); reviewed docs/configuration/ — no default or documented behavior changed, pipe_func_config deliberately has no page, and the stale mode was never documented there. Note: the trigger correctly caught a *comment* fix in the shipped defaults file, which is user-readable surface — not friction. *(Amended 2026-07-17: the ack rationale originally described the trigger diff as comment-only, omitting the `configs.py` field wiring — caught by a PR-review bot on #1052; review conclusion unchanged.)*diff --git a/wip/pr-1052-review-notes.md b/wip/pr-1052-review-notes.mdnew file mode 100644index 000000000..f354fa465--- /dev/null+++ b/wip/pr-1052-review-notes.md@@ -0,0 +1,58 @@+# PR #1052 review notes — deferred items++Triage record for the SWE-agent review threads on [PR #1052](https://github.com/Pipelex/pipelex/pull/1052) (release v0.39.2, carrying the sandbox-hosted PipeFunc transport feature). All threads were verified against the code; confirmed important issues were fixed on a follow-up branch to `dev`. This file captures the items deliberately deferred — each is real (or partially real) but is a design decision or defensive hardening that a PR-review pass should not resolve unilaterally.++## 1. Hosted mode still executes colocated structure-class modules (codex P1 + cubic dup)++- **Reporters:** codex (thread `PRRT_kwDOOwmMFc6Rw8qf`), cubic (thread `PRRT_kwDOOwmMFc6RxFP1`), `pipelex/libraries/library_manager.py` (hosted branch of `load_libraries`).+- **Verdict:** confirmed as a code fact. In sandbox-hosted mode, `ClassRegistryUtils.import_modules_in_folder` still AST-selects files containing a `StructuredContent` subclass and then `exec_module`s the whole file, so module-top-level customer code in a file that colocates a structure class with a `@pipe_func` runs in the host process. The `@pipe_func` body itself never runs on the host (only defined, dispatched out-of-process).+- **Why deferred:** partially intentional — the code comment scopes the hosted invariant to "PipeFunc bodies, not the pydantic structure classes", because concepts declared `structure = "ClassName"` must resolve the real class at load/validate time on the host, and you cannot import a class without executing its module. Closing the residual leak is an isolation-boundary design decision, not a mechanical fix.+- **Recommendation:** decide whether to (a) document + lint a constraint "in hosted mode, structure classes must live in side-effect-free files, separate from `@pipe_func` and other executable code", or (b) build a hosted-safe class-extraction path. Option (a) is the pragmatic move; (b) is heavy machinery.++## 2. Hosted validate-time output-contract gap (cubic P1, remainder)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFPK`), `pipelex/pipe_operators/func/pipe_func.py` (`validate_output_with_library` early return).+- **Verdict:** the P1 claim is largely a false positive — the full return-type/multiplicity cross-check DOES run in-box at library-load time (entrypoint boots in `direct` mode → `load_from_crate` → `validate_library` → `validate_output_with_library` with the real function registered), before the function executes. What remains: at hosted `/validate` (dry-run) time no box is spawned, so a return-type-vs-concept mismatch surfaces only at real execution instead of at pre-flight.+- **Why deferred:** closing the gap means invoking the sandbox during validation — a real design change for a diagnostics-freshness improvement, not a correctness hole.+- **Recommendation:** accept the weaker validate-time feedback as a documented hosted-mode limitation; revisit only if users hit confusing late failures.++## 3. Rehydration primitive: no scoping/teardown on the transported path (cubic ×2)++- **Reporter:** cubic (threads `PRRT_kwDOOwmMFc6RxFPS`, `PRRT_kwDOOwmMFc6RxFPW`), `pipelex/runtime_bridge/primitives/rehydration.py`.+- **Verdict:** confirmed-but-inert. A setup failure leaves the fresh library registered and the current-library ContextVar pointing at it, and the binding is never restored after the run. In the only shipped caller (the one-shot subprocess entrypoint) the process exits right after, and `open_fresh_library` pops-and-tears-down any stale same-id library on the next call, so nothing observable leaks today. The primitive itself must NOT scope-and-restore internally — the caller needs the binding live through `run_pipe_func` and output wrapping.+- **Recommendation if addressed:** in `DirectPipeFuncExecutor.run_pipe_func_transported`, wrap from rehydration through output-wrapping in `scoped_current_library(library_id=_TRANSPORTED_LIBRARY_ID)` plus a `finally` teardown of the library — matching the established pattern in `pipeline_run_setup.py` — so the documented "out-of-tree backends may reuse this" contract becomes safe for long-lived processes.++## 4. `JobMetadata` does not forbid extra fields on the wire (cubic)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFPu`), `pipelex/pipe_operators/func/pipe_func_execution_dtos.py` nesting `pipelex/pipeline/job_metadata.py`.+- **Verdict:** partially confirmed. The request model forbids extras and `PipeRunParams` already forbids extras, but `JobMetadata` is a plain `BaseModel`, so a typoed key inside the `job_metadata` sub-object of a transported request validates silently.+- **Why deferred:** `JobMetadata` is a shared model threaded through the whole runtime (Temporal payloads, tracing, inference jobs). Bolting `extra="forbid"` onto it is a global contract change with wide blast radius, to be taken (and tested) deliberately — not as a transport-DTO tweak.+- **Recommendation:** decide once for all wire-facing shared models; if forbidding, do it in its own change with the full suite run.++## 5. Transport rebind path escapes raw hydration errors (cubic)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFPj`), `pipelex/pipe_operators/func/pipe_func_execution_transport.py` (`pipe_func_execution_result_from_response`).+- **Verdict:** confirmed, minor. `hydrate_working_memory` + `get_main_stuff` on the sandbox response can raise hydration/working-memory errors, while `PipeFuncTransportError`'s docstring claims to cover "rebound from out-of-process execution". Asymmetric with the executor side, which classifies its failures.+- **Why deferred:** the response is produced by our own sandbox code, so a rebind failure is an internal contract bug; the one customer-triggered case (.py-only output class) is already documented as a known deferred limitation. Value is classification consistency, not recovery.+- **Recommendation if addressed:** wrap the two calls, `raise PipeFuncTransportError(...) from exc`, naming the function module/qualname.++## 6. `sys.path` insertion can cross-contaminate same-named bare helpers (cubic)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFPO`), `pipelex/tools/typing/module_inspector.py` (`import_module_from_file`).+- **Verdict:** confirmed mechanism, narrow reach. The insert exists so customer bundle files can import sibling helpers (added with #1036). Two distinct library dirs each shipping a top-level module with the same bare name (`helpers.py`), both imported bare in one long-lived process, would have the second library execute against the first's helper — the poisoning vector is the persistent bare-name `sys.modules` entry, so a "scoped `sys.path` restore" would NOT fix it. The deployed isolated runner path (one-shot box per call) is unaffected.+- **Why deferred:** the correct fix is namespacing bundle imports (or isolating `sys.modules` per bundle), which is real design work; the bots' suggested revert doesn't close the hole.+- **Recommendation:** track as a known local-multi-library footgun; revisit alongside any bundle-import namespacing work.++## 7. `normalize_crate()` drops `python_sources` (cubic)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFPD`), `pipelex/libraries/crate_normalization.py` / `library_crate.py`.+- **Verdict:** confirmed as a code fact, but the "breaks the transport contract" claim is a false positive: no transport path goes through `normalize_crate` — the sandbox/Temporal request is built from `get_crate()` directly, which threads `python_sources`. Normalization feeds the codegen/resolve/build projection pipeline, which has no need for customer `.py` text.+- **Why deferred:** latent inconsistency only; copying sources into the normalized crate would also raise the question of whether they belong in the normalized fingerprint (they deliberately do not today).+- **Recommendation if a normalized crate is ever transported:** pass `python_sources=crate.python_sources` through `normalize_crate` and state explicitly that sources stay outside the normalized fingerprint.++## 8. Crate cache published before the fingerprint idempotency check (cubic)++- **Reporter:** cubic (thread `PRRT_kwDOOwmMFc6RxFP2`), `pipelex/libraries/library_manager.py` (`load_from_crate`).+- **Verdict:** confirmed ordering fact, no exercised bug. A same-fingerprint crate with different/absent sources would overwrite `_crate_cache` and early-return, so `get_crate()` exposes the replacement. No current path produces two same-fingerprint crates with differing sources for one library id (fingerprint excludes sources by design; transported crates for a given structure always carry the same sources).+- **Why deferred:** defensive tightening against a scenario the architecture doesn't generate.+- **Recommendation if addressed:** don't overwrite an existing cache entry on a fingerprint hit, and publish the incoming crate only after `validate_library()` succeeds (next to the `loaded_set.add(fingerprint)`), with a two-load test asserting the first crate's sources survive.