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(pipe-run): make batch_max_concurrency required, not defaulted (#1097)

Louis Choqueldeb504049465
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1181a4f0..9f45dc5bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
## [Unreleased]
+### Changed
+
+- **`PipeRunParams.batch_max_concurrency` is required (Breaking)**: The fan-out bound has no default any more, joining `run_mode` and `pipe_stack_limit` as a field whose omission fails loud. `None` is not only what a default would give — it is also what an authored `max_concurrency = "unbounded"` resolves to, so a default made "never written" indistinguishable from "authored unbounded", and pointed the omission at the dangerous direction: launch every branch at once. Breaking for code constructing `PipeRunParams` directly or decoding a payload that predates the field; build through `PipeRunParamsFactory.make_run_params`, the single writer of all three fields.
+
### Fixed
- **A `{concept, content}` envelope carrying an empty list is now a value, not an error**: a plural slot is never _absent_ — when nothing is found it is the empty list — and the top-down shaper has always honoured that for a bare `[]` (D2). The bottom-up factory did not: it infers a list's item type from the first item, so an empty list raised _"Cannot create Stuff from empty list in content"_. The two spellings of one input therefore disagreed — a caller with no pictures could send `[]` and run, or send `{"concept": "native.Image", "content": []}` and fail — which made a plural input with nothing in it unrunnable for every caller that wraps its inputs. The envelope names the concept, so there was never anything to infer; it now builds an empty `ListContent`. Case 1.5 (a bare empty `ListContent`, no concept anywhere) still raises, and must: nothing there says what the items would have been.
diff --git a/docs/under-the-hood/pipe-routing-and-execution.md b/docs/under-the-hood/pipe-routing-and-execution.md
index c0e81adf5..91a16e7a8 100644
--- a/docs/under-the-hood/pipe-routing-and-execution.md
+++ b/docs/under-the-hood/pipe-routing-and-execution.md
@@ -51,6 +51,9 @@ The `PipeJob` is the universal unit of execution. It carries everything needed t
`PipeJob` is created by `pipeline_run_setup()`, which handles library loading, pipe resolution, working memory initialization, and telemetry setup. For distributed dispatch, a transport-prep step outside open core moves `working_memory` to `working_memory_raw` (deferred hydration) and ensures the crate is attached.
+!!! warning "Build `PipeRunParams` through its factory"
+ `PipeRunParamsFactory.make_run_params()` is the single writer of the fields that carry a run-scoped invariant: `run_mode`, `pipe_stack_limit` and `batch_max_concurrency`. None of the three has a default — for each, a silently-defaulted value would point at the dangerous direction (real spend, an unbounded pipe stack, a fan-out that launches every branch at once), and for `batch_max_concurrency` the would-be default `None` is *also* the resolved value of an authored `max_concurrency = "unbounded"`, so "never written" and "authored unbounded" would be indistinguishable. Constructing `PipeRunParams` by hand and omitting any of them raises a `ValidationError` — at the constructor and at the wire boundary alike.
+
---
## Library Loading
diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.py
index a9c227e68..baa1f96c9 100644
--- a/pipelex/pipe_run/pipe_run_params.py
+++ b/pipelex/pipe_run/pipe_run_params.py
@@ -152,12 +152,17 @@ class PipeRunParams(BaseModel):
# once at construction (`PipeRunParamsFactory.make_run_params`). `None` means unbounded —
# `gather_bounded`'s own no-bound sentinel, so the field is passed straight through.
#
+ # REQUIRED (no default), for the same reason as `run_mode` above: `None` is *also* the
+ # resolved value of an authored `max_concurrency = "unbounded"`, so a default would make
+ # "never written" indistinguishable from "authored unbounded" — and would point the omission
+ # at the dangerous direction, launching every branch at once. An omission must fail loud.
+ #
# Frozen and payload-borne rather than read live at fan-out time: the bound is PipeBatch's
# chunk size, and chunk size determines where a distributed backend's task boundaries fall
# between branch dispatches. Read from live worker config, a redeploy that changed the
# setting mid-run would make a replay emit a different command grouping than the recorded
# history. Carried in the payload, the fan-out shape is a pure function of the run.
- batch_max_concurrency: int | None = Field(default=None, frozen=True)
+ batch_max_concurrency: int | None = Field(frozen=True)
final_stuff_code: str | None = None
output_multiplicity: VariableMultiplicity | None = None
diff --git a/tests/integration/pipelex/fixtures/pipe_job_helpers.py b/tests/integration/pipelex/fixtures/pipe_job_helpers.py
index eacba7fbd..643a696d1 100644
--- a/tests/integration/pipelex/fixtures/pipe_job_helpers.py
+++ b/tests/integration/pipelex/fixtures/pipe_job_helpers.py
@@ -10,6 +10,7 @@ from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
+from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata, SpecialPipelineId
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -18,6 +19,25 @@ from pipelex.system.telemetry.otel_constants import OTelConstants
PIPE_JOB_HELPERS_PIPELINE_RUN_ID_PREFIX = "pipe_job_helpers_test"
+def make_mode_guarded_run_params(*, pipe_run_mode: PipeRunMode = PipeRunMode.LIVE) -> PipeRunParams:
+ """Run params built through the factory, with the requested run mode guarded.
+
+ A fixture builds through the factory rather than hand-building params because the factory is the
+ single writer of the three fields that carry a run-scoped invariant — `run_mode`,
+ `pipe_stack_limit` and `batch_max_concurrency`. What the factory adds in exchange is the
+ keyless-boot coercion: under `needs_inference=False` a requested LIVE comes back DRY. For a
+ fixture whose whole point is *which controller path* runs, that would swap the path under the
+ test while every assertion still passed, so assert the requested mode survived.
+ """
+ run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode)
+ match pipe_run_mode:
+ case PipeRunMode.LIVE:
+ assert run_params.run_mode.is_live, "This test must run the live path — the boot coerced the run mode to DRY"
+ case PipeRunMode.DRY:
+ assert run_params.run_mode.is_dry, "This test must run the dry path — the boot returned a run mode other than DRY"
+ return run_params
+
+
def build_pipe_job(
pipe: PipeAbstract,
library_crate: LibraryCrate | None,
diff --git a/tests/integration/pipelex/pipeline/test_optional_method_inputs.py b/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
index d2d09f5a8..4892b17ab 100644
--- a/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
+++ b/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
@@ -18,11 +18,11 @@ from pipelex.core.stuffs.text_content import TextContent
from pipelex.pipe_machinery.pipe_factory import PipeFactory
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_params import PipeRunParams
from pipelex.pipeline.execution_seams import prepare_pipe_job
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
def optionals_method_report(working_memory: WorkingMemory) -> TextContent:
@@ -150,7 +150,7 @@ class TestOptionalMethodInputs:
"""
load_empty_library()
pipe = _make_method_pipe()
- run_params = PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ run_params = make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
with pytest.raises(PipeRunInputsError) as exc_info:
await pipe.run_pipe(
diff --git a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
index 6d1c59444..722bb9ee7 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
@@ -26,9 +26,11 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
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_params import PipeRunParams
+from pipelex.pipe_run.pipe_run_params_factory import resolve_batch_max_concurrency
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
_DOMAIN_CODE = "test_optionals_batch"
@@ -41,7 +43,13 @@ _TEST_FUNCS = [optionals_batch_shout_item]
def _make_live_run_params() -> PipeRunParams:
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ """Build through the factory so the batch fans out under the *configured* bound.
+
+ Hand-built params used to omit `batch_max_concurrency` and fan out unbounded, quietly not
+ exercising the setting in the one test suite where the bound changes behavior. The field is
+ required now, so the omission cannot recur silently — the factory is the single writer.
+ """
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
def _build_compacting_batch() -> PipeBatch:
@@ -115,10 +123,15 @@ class TestPipeBatchCompaction:
)
working_memory = WorkingMemoryFactory.make_from_single_stuff(items_stuff)
+ run_params = _make_live_run_params()
+ # Guard the fixture, not the factory: this is the suite where an accidentally-unbounded
+ # fan-out would change behavior without failing anything.
+ assert run_params.batch_max_concurrency == resolve_batch_max_concurrency(get_config().pipelex.pipeline_execution_config.max_concurrency)
+
pipe_output = await batch.run_pipe(
job_metadata=job_metadata,
working_memory=working_memory,
- pipe_run_params=_make_live_run_params(),
+ pipe_run_params=run_params,
)
list_content = pipe_output.main_stuff.content
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
index b2c72d9e5..34ff6642b 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
@@ -11,7 +11,6 @@ from typing import Callable
import pytest
-from pipelex.config import get_config
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.domains.domain import SpecialDomain
@@ -27,6 +26,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
def _make_continue_only_condition() -> PipeCondition:
@@ -55,9 +55,7 @@ def _make_input_text_stuff():
def _make_run_params(run_mode: PipeRunMode) -> PipeRunParams:
- # Constructed directly (not via the factory) so a keyless boot's forced-DRY coercion cannot
- # silently swap which controller code path (live vs dry) the test exercises.
- return PipeRunParams(run_mode=run_mode, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=run_mode)
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
index 47e832476..1712ecf2d 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
@@ -16,7 +16,6 @@ from typing import Callable
import pytest
from pydantic import Field
-from pipelex.config import get_config
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import WorkingMemory
@@ -39,6 +38,7 @@ from pipelex.runtime_hub import get_class_registry
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
_DOMAIN_CODE = "test_optionals_par"
@@ -69,7 +69,7 @@ _TEST_FUNCS = [optionals_par_echo_source, optionals_par_echo_topic]
def _make_live_run_params() -> PipeRunParams:
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
def _build_parallel(*, output_ref: str, structure_class_names: list[str], add_each_output: bool = False) -> PipeParallel:
diff --git a/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py b/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
index 8ac32c4f0..4130554ce 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
@@ -27,6 +27,7 @@ from pipelex.pipeline.execution_seams import prepare_pipe_job
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
_DOMAIN_CODE = "test_optionals_seq"
@@ -51,7 +52,7 @@ _TEST_FUNCS = [optionals_seq_echo_source, optionals_seq_echo_a_out, optionals_se
def _make_live_run_params() -> PipeRunParams:
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
def _build_lift_sequence() -> PipeSequence:
diff --git a/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py b/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
index de6faaf37..ce560f272 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
@@ -10,7 +10,6 @@ from typing import Callable, cast
import pytest
from pytest_mock import MockerFixture
-from pipelex.config import get_config
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
@@ -28,6 +27,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
from tests.unit.pipelex.graph.conftest import make_trace_context
@@ -83,9 +83,7 @@ def _make_seeded_absence() -> AbsenceRecord:
def _make_live_run_params() -> PipeRunParams:
- # Constructed directly (not via the factory) so a keyless boot's forced-DRY coercion cannot
- # silently swap which code path (live vs dry) the test exercises.
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py b/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
index 1b8f368a1..63be0fc1c 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
@@ -8,7 +8,6 @@ from typing import Callable, cast
import pytest
-from pipelex.config import get_config
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
@@ -28,6 +27,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.func_registry import func_registry
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
_DOMAIN_CODE = "test_optionals_companion"
@@ -51,7 +51,7 @@ _TEST_FUNCS = [optionals_comp_find, optionals_comp_find_many, optionals_comp_sin
def _make_live_run_params() -> PipeRunParams:
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
def _build_sequence_with_liftable_parallel() -> PipeSequence:
diff --git a/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py b/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
index 8fd6c8fc3..6b8f725eb 100644
--- a/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
+++ b/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
@@ -9,7 +9,6 @@ from typing import Callable
import pytest
-from pipelex.config import get_config
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_pipe_library
@@ -24,12 +23,13 @@ from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlu
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_params
_DOMAIN_CODE = "test_optionals_gate"
def _make_live_run_params() -> PipeRunParams:
- return PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=get_config().pipelex.pipe_run_config.pipe_stack_limit)
+ return make_mode_guarded_run_params(pipe_run_mode=PipeRunMode.LIVE)
def _register_guarded_compose() -> None:
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
index 3c53a8357..c74f06ae5 100644
--- 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
@@ -64,7 +64,7 @@ class TestDirectExecutorWorkdir:
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),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
)
with scoped_current_library(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID): # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
@@ -89,7 +89,7 @@ class TestDirectExecutorWorkdir:
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),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
)
with scoped_current_library(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID): # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
@@ -139,7 +139,7 @@ class TestDirectExecutorWorkdir:
pipe_code="greet",
function_name="greet_it",
job_metadata=JobMetadata(user_id="user", pipeline_run_id="run"),
- pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
)
with scoped_current_library(library_id=direct_pipe_func_executor._TRANSPORTED_LIBRARY_ID): # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
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 c38ba3f47..0c186f59d 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
@@ -47,6 +47,6 @@ class TestPipeFuncExecutionTransport:
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),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
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 1944e9ce9..b7bf45543 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
@@ -90,7 +90,7 @@ class TestPipeFuncHostedMode:
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),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
)
content = pipe_output.working_memory.get_main_stuff().content
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_prompt_rendering_purity.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_prompt_rendering_purity.py
index dc9580bfd..a908a8677 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_prompt_rendering_purity.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_prompt_rendering_purity.py
@@ -144,7 +144,7 @@ class TestPromptRenderingPurity:
await pipe_llm._dry_run_operator_pipe( # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
job_metadata=JobMetadata(user_id="pytest", pipeline_run_id="test_prompt_rendering_purity"),
working_memory=_make_working_memory(),
- pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10),
+ pipe_run_params=PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=10, batch_max_concurrency=None),
)
assert pipe_llm.model_dump() == snapshot
diff --git a/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py b/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py
index 3ba647611..f8d6d2e9a 100644
--- a/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py
+++ b/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py
@@ -1,16 +1,19 @@
-"""`batch_max_concurrency`: resolved from config once, at run-params construction, then frozen.
+"""`batch_max_concurrency`: required, resolved from config once at run-params construction, then frozen.
The bound is PipeBatch's fan-out chunk size. Read live at fan-out time it would let a config
redeploy reshape an in-flight run's dispatch grouping; carried in the payload it cannot. These
-tests pin the resolution table and the write-once discipline. (The field is `frozen=True`, so a
-post-construction write is a *type* error — no runtime test needed for what the checkers block.)
+tests pin the resolution table, the write-once discipline, and the no-default rule. (The field is
+`frozen=True`, so a post-construction write is a *type* error — no runtime test needed for what the
+checkers block.)
"""
from typing import Literal
import pytest
+from pydantic import ValidationError
from pipelex.config import get_config
+from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory, resolve_batch_max_concurrency
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -37,6 +40,22 @@ class TestBatchMaxConcurrency:
"""
assert resolve_batch_max_concurrency(max_concurrency_setting) == expected_bound
+ def test_omitting_the_bound_fails_loud_on_the_constructor(self) -> None:
+ """No default: `None` also means an authored `max_concurrency = "unbounded"`, so a defaulted
+ field would make "never written" indistinguishable from "authored unbounded" — and would
+ point the omission at the dangerous direction (every branch at once). Same discipline as
+ `run_mode` and `pipe_stack_limit`, which are required for the same reason.
+ """
+ with pytest.raises(ValidationError, match="batch_max_concurrency"):
+ PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=20) # type: ignore[call-arg] # pyright: ignore[reportCallIssue] # the static error is the runtime contract under test
+
+ def test_omitting_the_bound_fails_loud_on_a_decoded_payload(self) -> None:
+ """The wire boundary too: `PipeRunParams` rides a distributed backend's payloads, so a
+ decode that drops the key must raise rather than silently resume unbounded.
+ """
+ with pytest.raises(ValidationError, match="batch_max_concurrency"):
+ PipeRunParams.model_validate({"run_mode": PipeRunMode.DRY, "pipe_stack_limit": 20})
+
def test_factory_freezes_the_live_config_value(self) -> None:
execution_config = get_config().pipelex.pipeline_execution_config
expected = resolve_batch_max_concurrency(execution_config.max_concurrency)
diff --git a/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py b/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
index 3c02e7505..64061f6f8 100644
--- a/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
+++ b/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
@@ -19,7 +19,7 @@ from pipelex.system.pipe_run_mode import PipeRunMode
class TestCogtRunParamsCarrier:
def test_cogt_run_params_derives_from_run_mode_fields(self) -> None:
"""The carrier is minted from the stored fields — one copy of the facts."""
- run_params = PipeRunParams(run_mode=PipeRunMode.DRY, is_mock_usage=True, pipe_stack_limit=20)
+ run_params = PipeRunParams(run_mode=PipeRunMode.DRY, is_mock_usage=True, pipe_stack_limit=20, batch_max_concurrency=None)
cogt_run_params = run_params.cogt_run_params
assert cogt_run_params.run_mode.is_dry
@@ -64,22 +64,23 @@ class TestCogtRunParamsCarrier:
def test_stale_cogt_run_params_kwarg_fails_loudly(self) -> None:
"""cogt_run_params is a derived property, not a field: passing it as a kwarg must raise.
- run_mode is supplied so the ONLY thing that can raise is the forbidden extra — without
- it the test would pass on the missing-required-field error even if extra="forbid" were
- dropped.
+ Every required field is supplied so the ONLY thing that can raise is the forbidden extra —
+ without them the test would pass on a missing-required-field error even if extra="forbid"
+ were dropped.
"""
with pytest.raises(ValidationError, match="cogt_run_params"):
PipeRunParams(
run_mode=PipeRunMode.DRY,
cogt_run_params=CogtRunParams(run_mode=PipeRunMode.DRY), # type: ignore[call-arg] # pyright: ignore[reportCallIssue]
pipe_stack_limit=20,
+ batch_max_concurrency=None,
)
def test_run_mode_fields_are_frozen(self) -> None:
"""A post-construction DRY→LIVE flip (or mock-usage flip) must raise — it would bypass
the construction validator and flow into real provider spend via the derived carrier.
"""
- run_params = PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=20)
+ run_params = PipeRunParams(run_mode=PipeRunMode.DRY, pipe_stack_limit=20, batch_max_concurrency=None)
with pytest.raises(ValidationError, match="frozen"):
run_params.run_mode = PipeRunMode.LIVE # type: ignore[misc] # the static read-only error is the runtime contract under test
@@ -89,7 +90,7 @@ class TestCogtRunParamsCarrier:
def test_mock_usage_requires_dry_on_pipe_run_params(self) -> None:
"""is_mock_usage is a sub-flag of DRY: setting it on a LIVE PipeRunParams is a contract violation."""
with pytest.raises(ValidationError, match="is_mock_usage"):
- PipeRunParams(run_mode=PipeRunMode.LIVE, is_mock_usage=True, pipe_stack_limit=20)
+ PipeRunParams(run_mode=PipeRunMode.LIVE, is_mock_usage=True, pipe_stack_limit=20, batch_max_concurrency=None)
def test_mock_usage_requires_dry_on_carrier(self) -> None:
"""The wire carrier enforces the same rule at its own boundary (assignments cross the wire)."""
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run_params_isolation.py b/tests/unit/pipelex/pipe_run/test_pipe_run_params_isolation.py
index 1ce444a13..e550a9b3a 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_run_params_isolation.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_run_params_isolation.py
@@ -9,7 +9,7 @@ class TestPipeRunParamsIsolation:
def test_make_deep_copy_isolates_pipe_stack(self) -> None:
"""A deep copy's pipe_stack is an independent list — a push on one branch does not leak into the other."""
- original = PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=20, pipe_stack=["root"])
+ original = PipeRunParams(run_mode=PipeRunMode.LIVE, pipe_stack_limit=20, batch_max_concurrency=None, pipe_stack=["root"])
branch = original.make_deep_copy()
assert branch.pipe_stack is not original.pipe_stack, "a deep copy must not share the pipe_stack list object"
diff --git a/wip/pr-1093-review-notes.md b/wip/pr-1093-review-notes.md
index b1025f0a1..836e92e37 100644
--- a/wip/pr-1093-review-notes.md
+++ b/wip/pr-1093-review-notes.md
@@ -8,6 +8,10 @@ Both were verified against the code. **Neither is a live bug** — one is a fals
## Deferred — `batch_max_concurrency` should be required, not defaulted
+> **Status (2026-08-12): done in `pipelex`, on `fix/batch-max-concurrency-required`.** The field is required, the integration fixtures route through `PipeRunParamsFactory.make_run_params`, both omission paths (constructor and `model_validate`) have `ValidationError` coverage, and the mutation check was run — restoring `default=None` turns both new tests red and nothing else. The compaction fixture builds through the factory and asserts the configured bound.
+>
+> **Still open — the cross-repo wire test, and it *is* gated.** Our Temporal plugin's payload-converter test round-trips `PipeRunParams` without the field, so it asserts `None == None` and would not catch the bound being dropped on the wire. It cannot be fixed ahead of the pin: that side pins a `pipelex` version predating the field entirely, and `PipeRunParams` is `extra="forbid"` — passing `batch_max_concurrency` there today fails. When the pin moves to ≥ the release carrying this change, make that test round-trip a real int bound. Path and pin live in the workspace-level private notes.
+
- **Origin:** surfaced while verifying Codex's second P1 on `pipelex/pipe_run/pipe_run_params.py:160`. It is *not* the defect Codex described (see "Not deferred" below for why that one is a false positive) — it is the weakness underneath it.
- **Where:** `pipelex/pipe_run/pipe_run_params.py`, the `batch_max_concurrency: int | None = Field(default=None, frozen=True)` field.
@@ -47,14 +51,14 @@ Keeps `int | None`, so authored `"unbounded"` still resolves to `None`; keeps `f
### Why it was deferred rather than done here
-The source change is one word, but the fixtures are not: ~19 direct constructions in this repo plus one in `pipelex-server` must supply the field. The integration fixtures should route through `PipeRunParamsFactory.make_run_params` instead — a net simplification, since they already hand-duplicate the factory's config read — but that is a ~20-file change with a cross-repo tail, landing on a release branch whose CI is green and which is about to merge to `main`. It belongs on `dev` immediately after the promotion.
+The source change is one word, but the fixtures are not: ~19 direct constructions in this repo plus one on the plugin side must supply the field. The integration fixtures should route through `PipeRunParamsFactory.make_run_params` instead — a net simplification, since they already hand-duplicate the factory's config read — but that is a ~20-file change with a cross-repo tail, landing on a release branch whose CI is green and which is about to merge to `main`. It belongs on `dev` immediately after the promotion.
### Execution notes for the follow-up
- **Tests:** add `pytest.raises(ValidationError)` coverage for both the constructor and `model_validate({...})` with the key absent, mirroring the required-`run_mode` coverage already in `tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py:72-92`.
- **Mutation-check it.** Temporarily restore `default=None` and confirm the new test goes red. A test green on first run proves nothing here.
- **Fix the compaction fixture** to build via the factory and assert the observed bound — that is the one place where an accidentally-unbounded fan-out actually changes behavior.
-- **Cross-repo, gated on the `pipelex` pin moving:** `pipelex-server/temporal/tests/integration/pipelex_temporal/data_converter/test_data_conv_pipe_run_params.py:22` round-trips `None`, so it asserts `None == None` and would not catch the field being dropped on the wire. Make it round-trip a real int bound.
+- **Cross-repo, gated on the `pipelex` pin moving:** our Temporal plugin's payload-converter test round-trips `None`, so it asserts `None == None` and would not catch the field being dropped on the wire. Make it round-trip a real int bound.
- **Honest caveat to keep in view:** making the field required converts a legacy-history decode into a `ValidationError`, and a workflow-task converter exception retries forever — it hangs rather than fails. Both states are non-events while Temporal is pre-production, and neither is fixed by a field default. It reconfirms that deploy discipline, not this field, is the real control over version skew under live histories.
## Not deferred — the two P1s as Codex reported them
@@ -67,7 +71,7 @@ Codex argued that `Pipelex.make` given a router that satisfies `PipeRouterProtoc
The language claim is correct. Everything downstream of it is not:
-- **No such router exists.** Every implementer in the workspace inherits nominally — `PipeRouter` (`pipelex/pipe_run/pipe_router.py`), `TemporalPipeRouter` in `pipelex-server/temporal/`, `MistralWorkflowsPipeRouter`, and every test stub. `pipelex-api` and `pipelex-server/transport/` contain no router at all.
+- **No such router exists.** Every implementer in the workspace inherits nominally — `PipeRouter` (`pipelex/pipe_run/pipe_router.py`), the routers in our Temporal and Mistral Workflows plugins, and every test stub. `pipelex-api` and the transport layer that is not open core contain no router at all.
- **The failure mode is static, not runtime.** The protocol is not `@runtime_checkable`, and injection performs no isinstance check — but pyright rejects a structural non-conformer at the injection boundary with `"run_batch_branch" is not present (reportArgumentType)`. Every consumer in this workspace is type-checked.
- **Structural conformance was never viable here.** `PipeRouterProtocol` declares an attribute, three concrete observer hooks, a concrete template-method `run`, and an `@abstractmethod _run_pipe_job`. Conforming without inheriting would mean reimplementing `run`'s entire error-wrapping template. Inheritance is not one supported pattern — it is the only one.
- **The cited convention says the opposite.** Codex referenced `AGENTS.md:255-258`; that section actually reads *"When extending the `Protocol`, also update every implementation (including no-op / null implementations) so structural typing is satisfied"* — a rule pointing away from the claim it was cited for.
@@ -82,11 +86,11 @@ No test was added either. A test injecting a non-inheriting router would assert
Codex argued that a worker resuming a `PipeRunParams` serialized before `batch_max_concurrency` existed would decode it as `None`, read as unbounded, changing both concurrency and replay grouping mid-flight.
-The mechanism is real: `PipeRunParams` does ride a Temporal workflow argument (`pipelex-server/temporal/pipelex_temporal/tprl_pipe/wf_pipe_router.py:204`), workflow arguments are recorded in history and re-decoded on replay, and `gather_bounded`'s chunk size does determine command grouping — which `pipelex-server/temporal/docs/temporal-replay-determinism.md` places on the replay-unsafe side of its own table.
+The mechanism is real: `PipeRunParams` does ride a Temporal workflow argument in our Temporal plugin's router workflow, workflow arguments are recorded in history and re-decoded on replay, and `gather_bounded`'s chunk size does determine command grouping — which that plugin's own replay-determinism notes place on the replay-unsafe side of their table.
The scenario is not:
-- **The Temporal integration is not in this package.** `pipelex/temporal/**` was removed in *Refactor/plugins 5* (#1006) and lives in the private `pipelex-server/temporal/` plugin; `pyproject.toml` carries no `temporalio` dependency. No OSS consumer of `pipelex` can have an in-flight durable batch.
+- **The Temporal integration is not in this package.** It lives in our Temporal plugin, and `pyproject.toml` carries no `temporalio` dependency. No OSS consumer of `pipelex` can have an in-flight durable batch.
- **The only exposed party is our own hosted plane, which is pre-production.** Temporal has never shipped to prod.
- **A field default cannot fix the general case.** Bumping `pipelex` on a Temporal worker is a workflow-code change, and this same release lands the kernel extraction and the plugin entry-point-group split. There is no `workflow.patched` or worker-versioning machinery. Hot-swapping any pipelex version under live histories is unsafe with or without this field; the control is deploy discipline (drain, build IDs).
- **The remedy is what the workspace rules out.** "No backward compatibility… no deprecation transition period." A legacy-payload sentinel is exactly the speculative back-compat machinery that policy exists to prevent, and the change is already recorded as breaking in the changelog.