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.mdindex 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.mdindex 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 Loadingdiff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.pyindex 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 = Noneoutput_multiplicity: VariableMultiplicity | None = Nonediff --git a/tests/integration/pipelex/fixtures/pipe_job_helpers.py b/tests/integration/pipelex/fixtures/pipe_job_helpers.pyindex 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 MthdsParserfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipe_run.pipe_job import PipeJobfrom pipelex.pipe_run.pipe_job_factory import PipeJobFactory+from pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.system.job_metadata import JobMetadata, SpecialPipelineIdfrom pipelex.system.pipe_run_mode import PipeRunMode@@ -18,6 +19,25 @@ from pipelex.system.telemetry.otel_constants import OTelConstantsPIPE_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.pyindex 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 TextContentfrom pipelex.pipe_machinery.pipe_factory import PipeFactoryfrom pipelex.pipe_operators.func.pipe_func import PipeFuncfrom pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint-from pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.pipeline.execution_seams import prepare_pipe_jobfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.registries.func_registry import func_registry+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_paramsdef 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.pyindex 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 PipeFactoryfrom pipelex.pipe_operators.func.pipe_func import PipeFuncfrom pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprintfrom pipelex.pipe_run.pipe_run_params import PipeRunParams+from pipelex.pipe_run.pipe_run_params_factory import resolve_batch_max_concurrencyfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom 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.contentdiff --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.pyindex 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 Callableimport pytest-from pipelex.config import get_configfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.domains.domain import SpecialDomain@@ -27,6 +26,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactoryfrom pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_paramsdef _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.pyindex 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 Callableimport pytestfrom pydantic import Field-from pipelex.config import get_configfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.memory.absence import AbsenceKind, AbsenceRecordfrom pipelex.core.memory.working_memory import WorkingMemory@@ -39,6 +38,7 @@ from pipelex.runtime_hub import get_class_registryfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom 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.pyindex 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_jobfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom 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_sedef _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.pyindex 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, castimport pytestfrom pytest_mock import MockerFixture-from pipelex.config import get_configfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.absence import AbsenceKind, AbsenceRecord@@ -28,6 +27,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.registries.func_registry import func_registry+from tests.integration.pipelex.fixtures.pipe_job_helpers import make_mode_guarded_run_paramsfrom 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.pyindex 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, castimport pytest-from pipelex.config import get_configfrom pipelex.core.memory.absence import AbsenceKind, AbsenceRecordfrom pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactory@@ -28,6 +27,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom 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_sindef _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.pyindex 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 Callableimport pytest-from pipelex.config import get_configfrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactoryfrom pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.interpreter_hub import get_pipe_library@@ -24,12 +23,13 @@ from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlufrom pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.system.job_metadata import JobMetadatafrom 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.pyindex 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.pyindex 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.pyindex 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().contentdiff --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.pyindex 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() == snapshotdiff --git a/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py b/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.pyindex 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 configredeploy 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 Literalimport pytest+from pydantic import ValidationErrorfrom pipelex.config import get_config+from pipelex.pipe_run.pipe_run_params import PipeRunParamsfrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory, resolve_batch_max_concurrencyfrom 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_configexpected = 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.pyindex 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 PipeRunModeclass 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_paramsassert 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 bypassthe 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.pyindex 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.mdindex 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 `PipeRouterProtocThe 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 assertCodex 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.