Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Fix PR #1052 review findings: PipeFunc transport hardening + review follow-ups (#1056)

Louis Choquelf6776a439ef0
diff --git a/.badges/tests.json b/.badges/tests.json
index 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 file
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index 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.md
index 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-17
diff --git a/TODOS.md b/TODOS.md
index 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 needed
diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.md
index 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 factory
diff --git a/docs/errors/duplicate-pipe-func-executor-error.md b/docs/errors/duplicate-pipe-func-executor-error.md
new file mode 100644
index 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.md
index 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 error
diff --git a/docs/errors/pipe-func-execution-error.md b/docs/errors/pipe-func-execution-error.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 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_config
from pipelex.system.configuration.configs import MigrationConfig, PipelexConfig
from 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 | None
if isinstance(config, PipelexConfig):
migration_config = config.migration
diff --git a/pipelex/hub.py b/pipelex/hub.py
index 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 None
def get_secrets_provider() -> SecretsProviderAbstract:
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index 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.py
index 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 asyncio
import inspect
+import shutil
import sys
import tempfile
from 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 / relpath
target.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.py
index 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 False
stuff_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).content
output_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.py
index 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.py
new file mode 100644
index 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.py
index 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 bound
must forbid extras (it is a wire contract).
"""
+import pytest
+from pydantic import ValidationError
+
+from pipelex.libraries.library_crate import LibraryCrate
from 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 JobMetadata
class TestPipeFuncExecutionTransport:
@@ -30,4 +37,16 @@ class TestPipeFuncExecutionTransport:
assert "crate" in PipeFuncExecutionRequest.model_fields
assert "working_memory_raw" in PipeFuncExecutionRequest.model_fields
assert 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.py
index 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 pytest
from pydantic import ValidationError
from pytest_mock import MockerFixture
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
+from pipelex.core.stuffs.list_content import ListContent
from pipelex.pipe_operators.func.pipe_func import PipeFunc
from 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.py
new file mode 100644
index 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 False
diff --git a/tests/unit/pipelex/tools/test_read_py_sources.py b/tests/unit/pipelex/tools/test_read_py_sources.py
index 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 of
them, 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.modules
assert "this_module_does_not_exist_nested" not in sys.modules
- assert set(sys.modules) == modules_before
def 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.md
index 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.md
new file mode 100644
index 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.