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.

1/2 Flat topology — core seam: batch-branch router hook + frozen fan-out bound (#1088)

Louis Choquel747dc1587227
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index de634b02c..d2ae63d64 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:ad647a1d23ee55400c773b372ea72ab805d0b9851f4c1944cf2f17ac219c164a"
+digest = "sha256:447e5b76aca175977a2001577a3499453d659641d94c5807ef1dbe23c46f9909"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-10T06:14:22Z"
-rationale = "Trigger is plugins_cmd.py gaining a Group column and passing the new entry_point_groups argument to build_registrar. Reviewed both targets: docs/tools/cli/ documents init/run/validate/show/fix/update/pkg/build and the agent CLI — it has no page for 'pipelex plugins list' at all, and grep for 'plugin' across docs/tools/cli/ returns zero hits; pipelex/cli/agent_cli/CLAUDE.md's only 'plugin' hits are mthds-plugins skill paths, unrelated to plugin discovery. No option, default, exit code or output contract of any documented command changed. Neither target is stale, so no doc change needed. The docs that ARE now wrong are the SPI pages under docs/under-the-hood/ (they still say to publish under the retired pipelex.plugins entry-point group); those are not this contract's targets and are scheduled with the rest of the Part-A doc sweep."
+reviewed_at = "2026-08-12T12:00:19Z"
+rationale = "Trigger is a docstring-pointer removal across seven CLI modules: each ended with a see-the-spec tail naming a path in a private sibling repo that does not exist in this one, so every line was both a leak and a dead pointer for an OSS reader. They now say 'the codegen spec' and keep the section name, so the reader still learns which concept governs. No option, default, exit code, output contract or behavior changed - the diff is comment-only. Reviewed both targets: docs/tools/cli/ and pipelex/cli/agent_cli/CLAUDE.md carry no reference to that private path, to any private repo, or to any of the removed pointers (grepped), and nothing they document about resolve/codegen/build was touched. Neither target is stale; no doc change needed. (Re-recorded 2026-08-12: the original rationale was written with backticked paths, which the shell command-substituted away, and it quoted the private path verbatim.)"
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -16,7 +16,7 @@ rationale = "Trigger is plugins_cmd.py gaining a Group column and passing the ne
"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0"
"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:1d5a66d03e6fec2d8673959857ace87b78db03ac"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:0f3daa4a3962273c4b347a619dd99bef72f735be"
+"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:56130b89fe9efec5ad3d014ed6bc16bef1bd1645"
"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:bacfda014d158c9a4e9de5f8ca03ba9628b6b102"
"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:256d428cff7738af33ce69281f8e81b538ba7996"
"pipelex/cli/agent_cli/commands/concept_cmd.py" = "blob:518d291b5e74a7f5ffb2da1606aae42ca2c57835"
@@ -73,14 +73,14 @@ rationale = "Trigger is plugins_cmd.py gaining a Group column and passing the ne
"pipelex/cli/commands/build/runner/app.py" = "blob:b5aa321ed93dc2cb9b138e4a26bae9eb75c732b7"
"pipelex/cli/commands/build/runner/bundle_cmd.py" = "blob:5b5ca0628f0595a0c3aae9b539ae4e7e0c92a853"
"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:0f497ffcae50d89483d8cf953c6dc03599bc2a5f"
-"pipelex/cli/commands/build/structures_cmd.py" = "blob:3c0cf372e381e8141fa49f18e261c5047df13e7c"
+"pipelex/cli/commands/build/structures_cmd.py" = "blob:d13ba3b6fc1433f787e1aa97c6c04a67483ec7ed"
"pipelex/cli/commands/bundle_path_resolver.py" = "blob:60c6a2994c9b7c6e0ec212702467d668eecb6d50"
"pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/codegen/app.py" = "blob:9158084a89da23654e122e9df3a0a9c726401642"
-"pipelex/cli/commands/codegen/check_cmd.py" = "blob:d73d0c73e82fa50e072058caf0ca92e52fe17b0f"
-"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:18da266c716b8c58b45ad89f85629adfbbfb67fd"
-"pipelex/cli/commands/codegen/types_cmd.py" = "blob:1cb3b607a0269e12461e85ad1e6f19b2b3aa5584"
-"pipelex/cli/commands/crate_loading.py" = "blob:aaf739abef2b84807483907365455ce2b8179aa6"
+"pipelex/cli/commands/codegen/check_cmd.py" = "blob:329f410bca90eb022fad2abc729e8b5203138c02"
+"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:5e7c2025682d2cfab3b15deb03ef2b468d1e69e3"
+"pipelex/cli/commands/codegen/types_cmd.py" = "blob:b7c9c7a3664c9fbe66f9b4c3c5ebf9ea1322445c"
+"pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"
"pipelex/cli/commands/doctor_cmd.py" = "blob:3cc70c2844c48aa73b91cdf085864589f30bc7f8"
"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:2113f7e7ffd373177a3104ce5b5dfb7f657dd186"
@@ -105,7 +105,7 @@ rationale = "Trigger is plugins_cmd.py gaining a Group column and passing the ne
"pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/login/command.py" = "blob:ace1db9879626cc1722adaac12761aadaa6b24ed"
"pipelex/cli/commands/plugins_cmd.py" = "blob:2980268813f1acf67f0f2cc914ccaff6cae6889b"
-"pipelex/cli/commands/resolve_cmd.py" = "blob:2233ab12b7cd5ef0bce697d9599d13a09e242dde"
+"pipelex/cli/commands/resolve_cmd.py" = "blob:2928a0e26eab7983367a59a78533f6618817feba"
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.toml
index 5f10e9897..8c515e542 100644
--- a/.drift/acks/pipelex-kernel-docs.toml
+++ b/.drift/acks/pipelex-kernel-docs.toml
@@ -1,17 +1,17 @@
contract = "pipelex-kernel-docs"
-digest = "sha256:5caf168f4ee9351e5e24dd1f8e2a836f3038607b1202330e4b2d4c09e39b4273"
+digest = "sha256:6a613fed0ff7873b3e1e61fe9aee1d7b8c033bc2f6f7c886273a66294a0aa944"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-10T12:22:48Z"
-rationale = "Trigger is a docstring-only edit to test_kernel_boot_contract.py: its 'On the deferred orchestrator question' paragraph claimed the remedy for the external-interpreter-orchestrator hole 'remains unbuilt on purpose' and named a proposed HubSlot.is_interpreter_slot property. That became stale when the plugin entry-point group split landed — a kernel-only boot now scopes discovery to KERNEL_ENTRY_POINT_GROUPS, so an interpreter-group orchestrator is never registered and the existing gate rejects its name loudly. Rewrote the paragraph to say the hole is closed and by what, and closed out the wip analysis it cites. Reviewed docs/under-the-hood/pipelex-kernel.md against the trigger: nothing is stale. The trigger changed no kernel entry point, no signature and no behavior, so the module table and the completeness claim the previous ack verified module by module both still hold. The page cites test_kernel_boot_contract.py once, in the Enforcement table, for what the test covers ('every kernel entry point runs on a keyless boot, swept afterwards') — that citation describes the test's coverage, which this edit did not touch, and the cited path still resolves. The page says nothing about orchestrators, boot_orchestrator, plugin groups or entry points, so it has no surface that could contradict the trigger. Reviewed, no doc change needed."
+reviewed_at = "2026-08-12T12:00:30Z"
+rationale = "Trigger is a comment-only pointer removal in compose_ops.py, func_ops.py and test_kernel_boot_contract.py: all three ended a paragraph with a see-also tail naming a wip/ doc that has since moved out of this repo, so the tails were dangling. Each comment already stated its own conclusion, so only the tail was dropped - the compose/func placement rationale and the distributed-orchestrator paragraph read exactly as before. No kernel entry point, signature or behavior changed. Reviewed docs/under-the-hood/pipelex-kernel.md: it cites neither moved doc, carries no private-repo reference, and its module table, completeness claim and Enforcement-table citation of test_kernel_boot_contract.py all still hold (that citation describes the test coverage, which this edit did not touch). Reviewed, no doc change needed. (Re-recorded 2026-08-12: the original rationale was written with backticked paths, which the shell command-substituted away.)"
[trigger_files]
"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"
-"pipelex/kernel/compose_ops.py" = "blob:28e80623d5e454a1b8f0612a27a28a6ddc73c5de"
+"pipelex/kernel/compose_ops.py" = "blob:c824b8cc7e8dd7c3c98b797e326c2709c6ff1cb3"
"pipelex/kernel/compose_results.py" = "blob:a837ae9680c7d4d0eb4dee37d4657c410e5b5cea"
"pipelex/kernel/exceptions.py" = "blob:45e9ad60c2699f7b57cad0a46c13f0b07b4cfbc9"
"pipelex/kernel/extract_ops.py" = "blob:cd596c03e45ab57eccca6fe1bf332e5977d1f2b2"
"pipelex/kernel/extract_results.py" = "blob:79405a56760f3d4b483660d76441fff95f58c64d"
-"pipelex/kernel/func_ops.py" = "blob:8718fb7d05bf57ee7686427dd75c2930ace7aecc"
+"pipelex/kernel/func_ops.py" = "blob:97c68c977ddc260c9b36b7eda5f4c7964e956a27"
"pipelex/kernel/func_results.py" = "blob:a7425a0ddc21571f23c53b92f5d7559ffdd08b71"
"pipelex/kernel/img_gen_ops.py" = "blob:b22869bee7dfbb624e3c406a0631969fc8695b7c"
"pipelex/kernel/img_gen_prompt.py" = "blob:90c33eae95298aa76d036f256ffc7d6523249166"
@@ -24,4 +24,4 @@ rationale = "Trigger is a docstring-only edit to test_kernel_boot_contract.py: i
"pipelex/kernel/prompt_references.py" = "blob:03ec9ef67ae84f141d072ca2d2c3ef888549ccc0"
"pipelex/kernel/search_ops.py" = "blob:01be4bef28f98342678cba16ac8c4b21fadcaae1"
"pipelex/kernel/search_results.py" = "blob:101b70dc96cc5ee1721c9f6b1cb725a5ca78ff70"
-"tests/unit/pipelex/kernel/test_kernel_boot_contract.py" = "blob:78947be625cb143c2a5d76a9761ed637d91a9469"
+"tests/unit/pipelex/kernel/test_kernel_boot_contract.py" = "blob:b33847de92e0bb277e307b7c6bbd7b4d82cb839c"
diff --git a/.github/workflows/package-check.yml b/.github/workflows/package-check.yml
index d9ff7341b..744087546 100644
--- a/.github/workflows/package-check.yml
+++ b/.github/workflows/package-check.yml
@@ -19,8 +19,8 @@ jobs:
run: |
if ! grep -qE "^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*['\"][^'\"]*>=3\.11([^0-9A-Za-z][^'\"]*)?['\"]" pyproject.toml; then
echo "❌ requires-python must start at >=3.11 — pipelex core supports Python 3.11+."
- echo "The Mistral Workflows orchestration integration that needs Python 3.12 ships as the"
- echo "separate pipelex-mistralai-workflows package; do not raise pipelex's own floor for it."
+ echo "The Mistral Workflows orchestration integration that needs Python 3.12 ships as a"
+ echo "separate package — see docs/distributed-execution/ ; do not raise pipelex's own floor for it."
exit 1
fi
echo "✅ requires-python floor is >=3.11"
diff --git a/.test_durations b/.test_durations
index 2078255aa..0ed7a169f 100644
--- a/.test_durations
+++ b/.test_durations
@@ -5881,10 +5881,6 @@
"tests/unit/pipelex/observer/test_local_observer.py::TestLocalObserver::test_observe_writes_one_jsonl_line_with_event_type[observe_before_run-before_run]": 0.0015739160007797182,
"tests/unit/pipelex/observer/test_local_observer.py::TestLocalObserver::test_two_observe_calls_append_two_lines_in_order": 0.0020540419936878607,
"tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_blueprint.py::TestPipeBatchBlueprint::test_pipe_dependencies_correct": 0.8473865840060171,
- "tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py::TestResolveBatchMaxConcurrency::test_setting_translates_to_gather_bounded_argument[1-1]": 0.000396165982238017,
- "tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py::TestResolveBatchMaxConcurrency::test_setting_translates_to_gather_bounded_argument[100-100]": 0.07548241699987557,
- "tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py::TestResolveBatchMaxConcurrency::test_setting_translates_to_gather_bounded_argument[8-8]": 0.0007538750069215894,
- "tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py::TestResolveBatchMaxConcurrency::test_setting_translates_to_gather_bounded_argument[unbounded-None]": 0.7548824160039658,
"tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_input.py::TestPipeBatchValidateInputs::test_validate_inputs_valid_cases[valid_multiple_inputs-blueprint1]": 0.21890241600340232,
"tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_input.py::TestPipeBatchValidateInputs::test_validate_inputs_valid_cases[valid_simple_batch-blueprint0]": 0.8536362920131069,
"tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_validation.py::TestPipeBatchValidation::test_accepts_valid_batch_config": 0.7366558319918113,
diff --git a/.vscode/launch.json b/.vscode/launch.json
index a5d7ec69f..4ac1e598e 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -100,7 +100,7 @@
"args": [
"run",
"bundle",
- "/Users/lchoquel/repos/Pipelex/pipelex-demos/mthds-wip/fashion_moodboard",
+ "${workspaceFolder}/tests/e2e/pipelex/cv_batch_screening/library_crate",
],
"console": "integratedTerminal",
"justMyCode": false
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e567d2ced..07e9924a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,30 +2,41 @@
## [Unreleased]
+### Highlights
+
+**Every operator's execution semantics is now importable without the interpreter.** The new public `pipelex.kernel` subpackage extracts what a step *does* — deck resolution, prompt assembly, generation, memory write-back — into plain functions covering every operator, all servable on a kernel-only boot with zero `.mthds` loaded and pinned by a permanent boot-contract test. The `PipelexKernel` facade gives programmatic callers ergonomic entry points with typed result envelopes. The layer below the interpreter takes the kernel's name, and plugins now declare which side they belong to through their entry-point group, so an interpreter-side plugin is never imported into a kernel-only process. Distributed execution sharpens alongside: a `run_batch_branch` router hook lets a backend isolate each batch branch, and the fan-out bound is frozen onto the run to close a replay hazard. Parity fixes make crate normalization, the `python-structures` projection, and input shaping agree with the runtime. Breaking changes are import-path moves, an error-class unification, a new required `build_registrar` parameter, and stricter failure classification — see below.
+
### Added
-- **Pipelex kernel (`pipelex.kernel`)**: A new public subpackage holding operator-execution semantics as importable functions, so what a step *does* — deck resolution, templating-style derivation, prompt assembly, generation, memory write-back — is no longer reachable only through a fully booted interpreter with a loaded library. Every operator is covered: LLM and structuring, extraction, image generation, search, template composition, and Python function calls. Every one of those calls is servable on a kernel-only boot with zero `.mthds` loaded, and a permanent test pins it by calling each of them on such a boot and then checking that no interpreter module was loaded. Two arms stay with the interpreter, because their inputs are language or deployment artifacts rather than execution semantics — `PipeCompose`'s construct mode, which is driven by an MTHDS blueprint, and `PipeFunc`'s pluggable executor, which selects *where* a function runs.
+- **Pipelex kernel (`pipelex.kernel`)**: New public subpackage holding operator-execution semantics as importable functions — deck resolution, prompt assembly, generation, memory write-back — no longer reachable only through a fully booted interpreter with a loaded library. Every operator is covered (LLM and structuring, extraction, image generation, search, template composition, Python function calls), every call is servable on a kernel-only boot with zero `.mthds` loaded, and a permanent boot-contract test pins it by invoking each one on such a boot and checking that no interpreter module was loaded. Two arms stay with the interpreter because their inputs are language or deployment artifacts rather than execution semantics: `PipeCompose`'s construct mode (driven by an MTHDS blueprint) and `PipeFunc`'s pluggable executor (which selects *where* a function runs). Documented in [Pipelex Kernel](under-the-hood/pipelex-kernel.md), with a drift contract keeping the doc tracking the kernel surface.
+- **`PipelexKernel` facade with typed result envelopes**: A facade class managing per-run state (`JobMetadata`, `CogtRunParams`) with ergonomic entry points such as `llm_text` and `llm_object`. Every kernel operation returns a strongly-typed envelope (`LlmTextResult`, `LlmObjectResult`, `ExtractResult`, `ImgGenResult`, `SearchResult`, `ComposeResult`, `FuncResult`) carrying the produced content, the updated memory, and tracer intermediates. `pipelex.kernel.memory_ops` standardizes the memory boundary with `shape_inputs`, `store_result`, and typed extraction helpers (`extract_main_content`, `extract_named_content`, and their `_as_list` variants).
+- **`run_batch_branch` router hook**: `PipeRouterProtocol` gained a second dispatch entry point, used by `PipeBatch` for each per-item fan-out branch — the only signal a router gets that a dispatch is a batch branch rather than an ordinary step. The default body delegates to `run`, so in-process execution is unchanged and every existing router keeps working untouched; a distributed backend can override it to give each branch its own isolation. Documented on the "Pipe Routing and Execution" page and listed in the Orchestrator SPI.
+- **Exceptions-aggregate layering gate**: A new AST guard bans kernel-layer packages from importing the all-errors aggregate `pipelex.exceptions`, closing the blind spot that let a single convenience import pull the interpreter into the kernel layer. `pipelex.kernel` is declared in the hub-layering guard's kernel-layer packages from its first commit.
### Changed
+- **Interpreter operators delegate to the kernel**: `PipeLLM`, `PipeStructure`, `PipeExtract`, `PipeImgGen`, `PipeSearch`, `PipeCompose`, and `PipeFunc` now delegate their core execution semantics to the kernel functions — a zero-behavior-change refactor. `pipe_operators/llm/helpers.py` is gone, its structure-prompt derivation absorbed by the kernel.
+- **"Runtime layer" is now "kernel layer" (Breaking)**: The layer below the method interpreter — the machinery present at execution time whatever is loaded — takes the name of the package that defines it. `pipelex.providers.builtins` exports `KERNEL_BUILTIN_PLUGINS` and `KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES`; the hub-layering guard declares `KERNEL_LAYER_PACKAGES` and answers `is_kernel_layer`; the layer's prose, docs and closure tests follow. "Runtime" was overloaded three ways in one tree — the whole engine, the orchestration venue, and this layer — so `runtime_bridge`, which means the venue, keeps the word, while `runtime_hub` and `runtime_boot` still carry the layer's former name and are renamed when the layer moves into its own package.
- **Plugins declare their layer through their entry-point group (Breaking)**: The single `pipelex.plugins` entry-point group is replaced by two — `pipelex.plugins.kernel` and `pipelex.plugins.interpreter` — and `PLUGIN_API_VERSION` bumps to 4. A kernel-only boot queries the kernel group alone, so an interpreter-side plugin's module is never imported into a process that only runs kernel operations — previously, merely installing such a plugin dragged the whole interpreter into every boot, because discovery loaded it unconditionally. The declaration is enforced: a kernel-group plugin that registers an orchestrator, a bundle validator, a PipeFunc executor, or one of the three interpreter-layer hub slots fails loud at register time. The restriction is one-directional — an interpreter-group plugin may still contribute kernel-tier capabilities such as an HTTP-error mapper. An installed plugin still published under the retired group is a startup error naming it and the group it should move to, never a silent nondiscovery. Declaring the *same* plugin under both groups is likewise a startup error: a boot reading both would otherwise load it twice and run its `register` twice, which mostly surfaces as a duplicate-contribution error naming the same plugin as both parties to the conflict, and — for a plugin contributing only a teardown callback, the one menu method with neither a key nor a tier guard — does not surface at all. `pipelex plugins list` gains a Group column. Scope worth stating: this governs which plugins are *discovered* and what they may *register*, not what a plugin's module imports — a kernel-group plugin that imports the interpreter at module scope still pulls it in, which only an import-closure rule would prevent.
- **`build_registrar` gained a required `entry_point_groups` parameter (Breaking)**: Every caller must now say which entry-point groups to read; there is no default. This affects any host embedding Pipelex that resolves plugin contributions itself — notably one reading `get_http_error_mappers()` to wire transport-fault handling — and it fails at import rather than at first use when the call sits at module scope. Pass `ENTRY_POINT_GROUPS` from `pipelex.interpreter_plugins.builtins` for a full boot, or `KERNEL_ENTRY_POINT_GROUPS` from `pipelex.providers.builtins` for a kernel-only one.
-- **"Runtime layer" is now "kernel layer" (Breaking)**: The layer below the method interpreter — the machinery present at execution time whatever is loaded — takes the name of the package that defines it. `pipelex.providers.builtins` exports `KERNEL_BUILTIN_PLUGINS` and `KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES`; the hub-layering guard declares `KERNEL_LAYER_PACKAGES` and answers `is_kernel_layer`; the layer's prose, docs and closure tests follow. "Runtime" was overloaded three ways in one tree — the whole engine, the orchestration venue, and this layer — so `runtime_bridge`, which means the venue, keeps the word, while `runtime_hub` and `runtime_boot` still carry the layer's former name and are renamed when the layer moves into its own package.
-- **Prompt reference types moved (Breaking)**: `ImageReference` and `DocumentReference` (with their `*Kind` enums) moved from `pipelex.pipe_operators.shared.image_reference` / `pipelex.pipe_operators.llm.document_reference` to `pipelex.kernel.prompt_references`. They describe how a prompt resolves an image or document out of working memory, which is execution semantics rather than a language artifact.
-- **`LLMPromptBlueprintValueError` and `ImgGenPromptBlueprintValueError` replaced (Breaking)**: The error raised when a prompt's image or document reference cannot be resolved is now `pipelex.kernel.exceptions.PromptContentError`, moved with the code that raises it. Both blueprints keep their fields, their validation, and their `make_*_prompt` signatures.
-- **Image-generation prompts are buildable without the interpreter**: `pipelex.kernel.img_gen_prompt.assemble_img_gen_prompt` is the image counterpart of the kernel's LLM prompt assembly — image-reference resolution, `[Image N]` placeholder numbering, and template rendering. `run_img_gen` takes a ready `ImgGenPrompt`, and until now the only way to build one was an interpreter-layer blueprint, which made image generation the single operator a kernel-only caller could not actually reach. `ImgGenPromptBlueprint` now delegates to it, keeping its parse-and-validate role and the `max_prompt_images` limit whose breach is a pipe-level error.
-- **`StructuredContentComposer` no longer takes `pipe_run_params` (Breaking)**: The constructor parameter and the attribute behind it are gone. They were dead — stored, threaded down to nested composers, and never read — and the docstring's claim that they gated dry-run mode was stale. Dropping them is what leaves the composer importing nothing from `pipelex.pipe_run`.
-- **Keyless-boot forced-DRY rule has one home**: `pipelex.runtime_hub.resolve_run_mode_for_boot` now owns the coercion that a keyless boot (`needs_inference=False`) applies to a requested run mode. Both run-params factories call it — the pipe tier's `PipeRunParamsFactory.make_run_params`, whose behavior is unchanged, and the kernel tier's `PipelexKernel.make`, which previously minted a LIVE `CogtRunParams` on an offline boot. A programmatic kernel caller on a keyless boot now gets the same forced DRY and the same warning as a pipe run.
+- **Prompt reference types moved (Breaking)**: `ImageReference` and `DocumentReference` (with their `*Kind` enums) moved from `pipelex.pipe_operators` to `pipelex.kernel.prompt_references`. They describe how a prompt resolves an image or document out of working memory — execution semantics, not a language artifact.
+- **Prompt resolution errors unified (Breaking)**: `LLMPromptBlueprintValueError` and `ImgGenPromptBlueprintValueError` are replaced by `pipelex.kernel.exceptions.PromptContentError`, moved with the code that raises it. Both blueprints keep their fields, their validation, and their `make_*_prompt` signatures.
+- **Image-generation prompts are buildable without the interpreter**: `pipelex.kernel.img_gen_prompt.assemble_img_gen_prompt` is the image counterpart of the kernel's LLM prompt assembly — image-reference resolution, `[Image N]` placeholder numbering, and template rendering. Until now the only way to build an `ImgGenPrompt` was an interpreter-layer blueprint, which made image generation the single operator a kernel-only caller could not reach; `ImgGenPromptBlueprint` now delegates to it, keeping its parse-and-validate role and the `max_prompt_images` limit.
+- **`StructuredContentComposer` no longer takes `pipe_run_params` (Breaking)**: The constructor parameter and the attribute behind it were dead — stored, threaded down to nested composers, and never read — and the docstring's claim that they gated dry-run mode was stale. Dropping them leaves the composer importing nothing from `pipelex.pipe_run`.
+- **Keyless-boot forced-DRY rule has one home**: `pipelex.runtime_hub.resolve_run_mode_for_boot` now owns the coercion that a keyless boot (`needs_inference=False`) applies to a requested run mode, and both run-params factories call it. The pipe tier's behavior is unchanged; the kernel tier's `PipelexKernel.make` previously minted a LIVE `CogtRunParams` on an offline boot and now gets the same forced DRY and the same warning as a pipe run.
### Fixed
- **`Date` and `Time` could not be produced by a live `PipeLLM`**: A `PipeLLM` whose `output` was `Date`, `Date[]`, or `Time` failed every real run on `date_type` / `time_type` — the structured-output layer validates the model's response in strict mode, where a `mode="before"` validator forfeits pydantic's strict-JSON acceptance of ISO strings. Both natives now parse ISO 8601 themselves and return a real `date`/`time`, so the strict and lax paths agree and the guards (no epoch-seconds, no datetime on a calendar date) still fire in both. `Time` gained the numeric-string guard `Date` already had.
- **One ISO 8601 contract for the `Date` and `Time` natives (Breaking)**: `pipelex.core.stuffs.iso_temporal` now owns what those natives accept — the *extended* forms only (`2026-07-07`, `15:40:00+02:00`), rejecting the basic and week/ordinal spellings that `fromisoformat` would otherwise restate in a calendar the source never used. Both the content models and `StuffContentFactory` parse through it — including the time half of an authored `2026-07-07T15:40:00`, which is split out rather than handed to `datetime.fromisoformat` — so a model-generated value and an authored one are held to the same contract instead of two. It also rejects the end-of-day `24:00` form, which names the *next* day's midnight: Python 3.14 reads it as this day's midnight where 3.11-3.13 raise, so a `Time` (or a `Date`'s time) could silently land a full day early on part of the supported interpreter range. Breaking for authored inputs that used a non-extended spelling: `"15:40:00+0200"`, `"2026-07-07T154000"`, `"24:00:00"`, and surrounding whitespace are now refused where they previously parsed.
-- **Cross-domain pipe refs in normalized crates (Breaking)**: A bare pipe ref calling a pipe declared in another domain was normalized by prefixing the *caller's* domain, naming a pipe the crate does not hold — while the live library resolves the same ref by searching every domain. The crate fingerprinted the wrong content and a crate round-trip broke the method at run time with `PipeNotFoundError`, with nothing raised on the way in. Normalization now resolves a bare pipe ref against the whole crate exactly as `PipeLibrary` does, and raises `CrateNormalizationError` when the ref is ambiguous or matches no pipe instead of emitting a dangling ref.
-- **Structureless concepts in the `python-structures` projection (Breaking)**: A concept declaring only a description was projected as a `StructuredContent` subclass while the runtime promotes the same declaration to a refinement of native `Text`. Since `TextContent` and `StructuredContent` are siblings, the interpreter's text-vs-object dispatch answered differently depending on which class it was handed — and the mismatch raised nothing, because the read-back validated against both. The projection now emits `TextContent` as the base, matching the runtime. A Python-class-backed concept (`structure = "<ClassName>"`) still projects onto the root base: its real shape is not visible to the crate.
-- **Format-stable import blocks in generated Python**: A generated import line whose merged names crossed 88 columns was emitted flat, so the first `ruff format` in a consumer's tree rewrote it — changing the body bytes and making `pipelex codegen check` report the file as hand-edited. The import block now pre-explodes past the threshold like every other emitted construct.
-- **Unimportable `python-structures` module for a concept refining `Anything`**: `Anything` is the one native with no content class of its own, so a concept refining it fell back to the root `StructuredContent` — emitting the class name without registering its import. The generated module then raised `NameError` on the consumer's first import. The fallback now goes through the renderer that registers the import.
-- **Input shaping honors its injected concept provider (Breaking)**: `InputShaper` took a `ConceptProviderAbstract` and consulted it for concept resolution and compatibility, then resolved each value's structure class from the process-global class registry anyway — the ambient lookup the provider parameter exists to replace. It now resolves the class through the provider and hands the resolved type down, so a caller that supplies its own provider can shape inputs without a loaded library. Breaking on one failure path: a declared structure class that does not resolve now raises `ConceptStructureClassNotFoundError` instead of arriving as a `StructureValidationError` about the value, which pointed the author at their input rather than at the concept.
+- **Cross-domain pipe refs in normalized crates (Breaking)**: A bare pipe ref calling a pipe declared in another domain was normalized by prefixing the *caller's* domain, naming a pipe the crate does not hold — nothing raised on the way in, and the crate round-trip broke the method at run time with `PipeNotFoundError`. Normalization now resolves a bare ref against the whole crate exactly as the live library does, and raises `CrateNormalizationError` when the ref is ambiguous or matches no pipe.
+- **Structureless concepts in the `python-structures` projection (Breaking)**: A concept declaring only a description was projected as a `StructuredContent` subclass while the runtime promotes the same declaration to a refinement of native `Text` — so the interpreter's text-vs-object dispatch answered differently depending on which class it was handed, and the mismatch raised nothing. The projection now emits `TextContent` as the base, matching the runtime.
+- **Unimportable `python-structures` module for a concept refining `Anything`**: `Anything` is the one native with no content class of its own, so a refining concept fell back to the root `StructuredContent` — emitting the class name without registering its import, and the generated module raised `NameError` on the consumer's first import. The fallback now goes through the renderer that registers the import.
+- **Format-stable import blocks in generated Python**: A generated import line whose merged names crossed 88 columns was emitted flat, so the first `ruff format` in a consumer's tree rewrote it — changing the body bytes and making `pipelex codegen check` report the file as hand-edited. Import blocks now pre-explode past the threshold like every other emitted construct.
+- **Input shaping honors its injected concept provider (Breaking)**: `InputShaper` consulted its injected `ConceptProviderAbstract` for concept resolution and compatibility, then resolved each value's structure class from the process-global class registry anyway — the ambient lookup the provider parameter exists to replace. It now resolves through the provider, so a caller supplying its own provider can shape inputs without a loaded library. Breaking on one failure path: a declared structure class that does not resolve raises `ConceptStructureClassNotFoundError` instead of a `StructureValidationError` that pointed the author at their input rather than at the concept.
+- **A dry run now identifies the pipe it is running**: `dry_run_pipe` stamps the running pipe onto the `JobMetadata` it hands down, exactly as `live_run_pipe` already did — previously log correlation and the per-step labelling a distributed backend derives saw an anonymous step in DRY and a named one in LIVE. Telemetry stays live-only: the dry copy clears `otel_context` rather than inheriting a live span.
+- **Explicit image-generation seed of `0` respected**: Building image-generation job params swallowed an explicit `seed` of `0` through a truthiness check and fell back to the configured default. `0` is a legal seed and now goes through; the `"auto"` literal still means the backend picks one.
+- **`PipeBatch` fan-out bound is frozen onto the run (Breaking)**: The `[pipelex.pipeline_execution_config] max_concurrency` setting is now read once, when the run's parameters are built, and carried as `PipeRunParams.batch_max_concurrency` instead of being re-read inside every `PipeBatch` — editing the config mid-run no longer reshapes in-flight batches. This closes a durable-execution hazard: the bound decides where a backend's task boundaries fall between branch dispatches, so a worker redeploy mid-run could make a replay group its dispatches differently from the recorded history. Breaking only for code that mutated `max_concurrency` mid-run and expected the change to take effect.
## [v0.42.0] - 2026-08-01
@@ -233,7 +244,7 @@
### Changed
- **Dropped Python 3.10 support (Breaking):** `requires-python` is now `>=3.11,<3.15`. The 3.10 compatibility bridges are gone — `StrEnum`, `Self`, and `Traversable` are imported directly from the stdlib at every call site, the `pipelex.types` re-export module that existed only to paper over 3.10 is deleted, and the `backports.strenum` conditional dependency (and its type stub) is dropped. CI test/lint matrices, the `package-check` `requires-python` floor gate, and the contributor docs now start at 3.11.
-- **Plugin API version bumped to 3 (Breaking):** `PLUGIN_API_VERSION` is now `3` (was `2`) to add the `add_storage_provider` and `add_secrets_provider` registrar menu methods. Plugin discovery version-checks with strict equality, so every external plugin must re-declare `targets_api = 3`. `pipelex-mistralai-workflows` registers no storage or secrets provider, so the `targets_api` bump is its only change. `pipelex-temporal` needs the bump **and** a code migration: its payload-codec factory imports the now-removed `make_storage_provider_from_config` (see Removed) and must switch to resolving the provider via the registry (`get_storage_provider_registry().get_required(method=...)`).
+- **Plugin API version bumped to 3 (Breaking):** `PLUGIN_API_VERSION` is now `3` (was `2`) to add the `add_storage_provider` and `add_secrets_provider` registrar menu methods. Plugin discovery version-checks with strict equality, so every external plugin must re-declare `targets_api = 3`. Our Mistral Workflows plugin registers no storage or secrets provider, so the `targets_api` bump is its only change. Our Temporal plugin needs the bump **and** a code migration: it imports the now-removed `make_storage_provider_from_config` (see Removed) and must switch to resolving the provider via the registry (`get_storage_provider_registry().get_required(method=...)`).
- **`PipeSignature` is not a pipe type (Breaking):** A signature is now declared by **omitting** `type` — a `[pipe.x]` section with no `type` and nothing but the contract (`description`, `output`, optional `inputs`, optional `signature_for`) *is* a `PipeSignature`. Writing `type = "PipeSignature"` explicitly is rejected with a migration error ("`PipeSignature` is no longer a pipe type — delete the `type` line"), and a typeless section declaring any non-contract field is a hard error naming the field. The `pipelex-agent pipe` authoring command mirrors this. **MTHDS JSON Schema shape change:** the signature arm no longer carries a `type` property (an explicit tag now fails schema validation), so the downstream schema copies (`mthds`, `vscode-pipelex`, `mthds-ui`) must be re-synced on the next release via the `mthds-schema-sync` skill.
- **`PipeCondition` `continue` now resolves the output as absent (Breaking):** The `continue` special outcome no longer passes the current main stuff through (and no longer errors when there is none). It records a declared-absent `AbsenceRecord` for the condition's declared output — with the evaluated expression as the reason — and returns success, memory otherwise unchanged. A `continue`-reachable `PipeCondition` must therefore declare its output optional (e.g. `output = "Constraint?"`), or validation rejects it (`optional_output_required`). Dry-run parity holds. Migration: the previous value stays in working memory under its own name, so downstream pipes consume it explicitly by that name (declared `?` when it may be absent); a coalescing operator is the planned ergonomic replacement for pass-through.
- **Controllers combine under absence:** `PipeParallel` no longer crashes when a branch result resolves absent (lifted branch or `continue`): with a `Composite` output the absent component is omitted (ledger note kept), and with a structured output a non-required field absorbs the absence as its default (`None` unless the author declared another), while a required field fed an absent branch raises a typed error naming the branch, the field, and the fixes. `PipeBatch` compacts: absent branch results are dropped from the aggregated list, so batching a "keep or skip" condition over items yields only the kept results.
@@ -254,7 +265,7 @@
### Removed
-- **`make_storage_provider_from_config` (Breaking):** The module-level storage-provider factory (`pipelex/tools/storage/storage_provider_factory.py`) is removed — storage is now resolved through the config-selected `StorageProviderRegistry` at boot. Downstream code that imported this helper (notably `pipelex-temporal`'s payload-codec factory) must select through the registry instead.
+- **`make_storage_provider_from_config` (Breaking):** The module-level storage-provider factory (`pipelex/tools/storage/storage_provider_factory.py`) is removed — storage is now resolved through the config-selected `StorageProviderRegistry` at boot. Downstream code that imported this helper must select through the registry instead.
## [v0.37.0] - 2026-07-04
@@ -388,12 +399,12 @@
### Added
- **`is_valid` on the canonical validation report**: `PipelexValidationReport` gains `is_valid: Literal[True] = True`, the always-true discriminant of the valid arm of the hosted `/validate` response union (mirrored by pipelex-api's `InvalidReport`'s `Literal[False]`). It sits beside `is_runnable`: a sound bundle may still be not-yet-runnable.
-- **Offline CLI unit tests**: Coverage for the pipelex-internal logic behind the CLI commands — `doctor` diagnostics, `run` execution and its sync wrapper, the `build` codegen cores, the readiness gate, `show`/`which`, and the gateway/telemetry/signature error handlers (the spec'd CLI interface stays owned by the conformance suite).
+- **Offline CLI unit tests**: Coverage for the pipelex-internal logic behind the CLI commands — `doctor` diagnostics, `run` execution and its sync wrapper, the `build` codegen cores, the readiness gate, `show`/`which`, and the gateway/telemetry/signature error handlers (the spec'd CLI interface stays owned by our cross-repo spec suite).
- **Offline inference & runtime unit tests**: Coverage for layers that can break without a provider — structured-output↔instructor mode mapping, model-deck reference checks, the image-gen argument and worker-routing factories, gateway request-shaping and extract parsing, the Mistral factory, the local observer sink, the output renderer, builder spec validation / `to_blueprint()`, the pipeline runner's error paths, the TOML config-sync engine, and the storage config validators.
### Changed
-- **[BREAKING] Keyword-only public API**: Top-level public surfaces now require keyword arguments after the first parameter. A caller passing a second-or-later argument positionally must switch to keyword form — affected methods include `Pipelex.make(integration_mode, *, ...)`, `Pipelex.setup(integration_mode, *, ...)`, and `PipelexHub.setup_config(config_cls, *, ...)`. Downstream consumers to check: `pipelex-api`, `pipelex-worker`, `n8n-nodes-pipelex`, cookbook, starter.
+- **[BREAKING] Keyword-only public API**: Top-level public surfaces now require keyword arguments after the first parameter. A caller passing a second-or-later argument positionally must switch to keyword form — affected methods include `Pipelex.make(integration_mode, *, ...)`, `Pipelex.setup(integration_mode, *, ...)`, and `PipelexHub.setup_config(config_cls, *, ...)`. Downstream consumers to check: `pipelex-api`, `n8n-nodes-pipelex`, cookbook, starter, and our hosted services.
- **Codebase-wide keyword-only refactor**: The entire `pipelex/` tree (leaf tools, domain core, inference layer, execution path, framework-sensitive packages) now places a bare `*` after the subject parameter, requiring all later arguments to be named at the call site (e.g. `copy_file(src, target_path=dst, overwrite=False)`).
- **Signature subject corrections**: Reordered parameters so the true semantic subject is the first positional argument, e.g. `parse_pipe_spec(spec_data, *, pipe_type)`, `hydrate_content(raw_content, *, concept)`, and `write_manifest(manifest, *, deck_dir)`. `parse_pipe_spec` is consumed by the hosted runner API (`pipelex-api`), updated in lockstep.
- **[BREAKING] Canonical protocol validation report**: `PipelexValidationReport` is reworked into the canonical typed shape shared by every backend and moved to `pipelex/pipeline/validation_report.py` — a typed `bundle_blueprint` (replacing the untyped single-or-list `blueprint` dump), `pipe_io_contracts` keyed by namespaced `pipe_ref` (new `pipelex/pipeline/pipe_io_contracts.py`), `validated_pipes`, and the `pending_signatures` / `is_runnable` verdict. It is assembled in exactly one place (`build_validation_report`) with a single shared primary-blueprint rule (`select_primary_blueprint`).
@@ -488,7 +499,7 @@ This cycle reworks **cost reporting** so it stops leaking. Cost now rides on the
### Changed
-- **Mistral Workflows integration extracted into a dedicated package.** The optional `pipelex[mistralai-workflows]` extra and the `pipelex.plugins.mistralai_workflows.*` modules have been removed from `pipelex`. The Mistral Workflows integration now ships separately as its own package, `pipelex-mistralai-workflows`. The framework-agnostic runtime-bridge core (boundary types, `run_pipe_via_bridge`, `PipelexExecutionMode`, `ensure_pipelex_booted`) has been promoted from `pipelex.plugins.mistralai_workflows.*` to `pipelex.runtime_bridge.*` so any host runtime — not just Mistral Workflows — can embed Pipelex. No behavior changes; activities, boundary types, and execution modes are identical.
+- **Mistral Workflows integration extracted into a dedicated package.** The optional `pipelex[mistralai-workflows]` extra and the `pipelex.plugins.mistralai_workflows.*` modules have been removed from `pipelex`. The Mistral Workflows integration now ships separately, as our Mistral Workflows plugin. The framework-agnostic runtime-bridge core (boundary types, `run_pipe_via_bridge`, `PipelexExecutionMode`, `ensure_pipelex_booted`) has been promoted from `pipelex.plugins.mistralai_workflows.*` to `pipelex.runtime_bridge.*` so any host runtime — not just Mistral Workflows — can embed Pipelex. No behavior changes; activities, boundary types, and execution modes are identical.
- **`--cost-report` removed, folded into `--costs`.** Breaking: `--cost-report/--no-cost-report` is gone from `run pipe|method|bundle`. Use `--costs` (default on) instead.
@@ -615,7 +626,7 @@ This release hardens Pipelex at its edges. The headliners: a full **error-handli
- **Bounded fan-out concurrency for `PipeBatch`.** A `PipeBatch` over many items no longer spawns every branch — every coroutine, every deep-copied working memory, every inference call — at once. Branches now run in bounded chunks driven by the new `[pipelex.pipeline_execution_config]` setting `max_concurrency` (default `8`; set to the literal `"unbounded"` for unbounded fan-out, the previous behavior). It keeps a large workload (one pipe over thousands of documents) from overwhelming asyncio, memory, and provider rate limits. Results still preserve input order, and a branch failure still propagates (first error by input index wins). `PipeParallel`, which fans over a fixed pipe-defined branch set, is unchanged.
-- **Authoritative `error_domain` → HTTP-status mapping.** `pipelex/base_exceptions.py` now owns the mapping that downstream HTTP APIs (`pipelex-relay`, `pipelex-back-office`) need to render an `ErrorReport` as an HTTP response: `error_domain_to_http_status()` (the pure domain table — `INPUT` → 422, `CONFIG`/`RUNTIME`/unknown → 500) and the `ErrorReport.http_status` property, which adds a provider-429 passthrough so the API can emit a `Retry-After` header from `provider_metadata.retry_after_seconds`. The library stays HTTP-agnostic — no web-framework dependency, just the mapping table; downstream FastAPI handlers call the helper instead of reinventing the contract.
+- **Authoritative `error_domain` → HTTP-status mapping.** `pipelex/base_exceptions.py` now owns the mapping that downstream HTTP APIs need to render an `ErrorReport` as an HTTP response: `error_domain_to_http_status()` (the pure domain table — `INPUT` → 422, `CONFIG`/`RUNTIME`/unknown → 500) and the `ErrorReport.http_status` property, which adds a provider-429 passthrough so the API can emit a `Retry-After` header from `provider_metadata.retry_after_seconds`. The library stays HTTP-agnostic — no web-framework dependency, just the mapping table; downstream FastAPI handlers call the helper instead of reinventing the contract.
- **`AMBIGUOUS` inference-error category for outcome-uncertain failures.** New `InferenceErrorCategory.AMBIGUOUS` for failures where the error type is known but the outcome is not — the operation may or may not have committed (e.g. a connection dropped mid-request). It is non-retryable, like `CONFIGURATION` / `CONTENT` / `CAPACITY`, but semantically distinct from `UNKNOWN`, which means the error could not be classified at all. The `azure_rest` image-generation worker now raises `AMBIGUOUS` for mid-request transport failures — `ReadError` / `WriteError` / `RemoteProtocolError` and `ReadTimeout` / `WriteTimeout` — so an automatic-retry layer won't re-fire a non-idempotent, billable image submit whose outcome is unknown; pre-request failures (`ConnectError` / `ConnectTimeout` / `PoolTimeout`) stay `TRANSIENT` and retryable.
diff --git a/docs/building-methods/pipes/pipe-controllers/PipeBatch.md b/docs/building-methods/pipes/pipe-controllers/PipeBatch.md
index c773ecf78..0cf3b83f9 100644
--- a/docs/building-methods/pipes/pipe-controllers/PipeBatch.md
+++ b/docs/building-methods/pipes/pipe-controllers/PipeBatch.md
@@ -24,6 +24,8 @@ This is the ideal controller for processing collections of documents, images, or
To restore unbounded fan-out (every branch started at once), set `max_concurrency = "unbounded"`.
+The setting is read **once, when the run's parameters are built**, and then frozen onto the run (`PipeRunParams.batch_max_concurrency`) — every `PipeBatch` in that run, at any depth, uses the value that was in effect when the run started. Editing the config while a run is in flight does not reshape it. This matters most on a durable-execution backend, where the bound is also the chunk size that decides where the backend's task boundaries fall between branch dispatches: a value re-read mid-run could make a replay group its dispatches differently from the recorded history.
+
Results always preserve input order regardless of the concurrency bound. If a branch fails, the failure propagates and the first error by input index wins.
For durable, rate-limited execution of very large batches, run the pipeline on the Temporal track.
diff --git a/docs/contribute/drift-contracts.md b/docs/contribute/drift-contracts.md
index ea52cc1bb..1f8e0a734 100644
--- a/docs/contribute/drift-contracts.md
+++ b/docs/contribute/drift-contracts.md
@@ -9,7 +9,7 @@ Not every code↔doc relationship deserves a review contract. This repo distingu
| Tier | Mechanism | Judgment needed |
|---|---|---|
| **Derived** | Regenerate and diff: `check-config-sync`, `check-mthds-schema`, `check-gateway-models`, `generate-error-pages`, `generate-error-identity` | None — the output is a pure function of its sources |
-| **Linkage** | Referential integrity of declared cross-references (the spec/conformance `check-spec-links` pair) | None — links either resolve or they don't |
+| **Linkage** | Referential integrity of declared cross-references (the spec ↔ verifying-test back-link pair) | None — links either resolve or they don't |
| **Review** | Drift contracts: "this changed → that must be looked at, and the look recorded" | Yes — someone must judge whether the prose still holds |
The standing rule: **anything mechanizable becomes a derived check.** If a review contract keeps opening and the review is always the same mechanical comparison, delete the contract and write a derived check instead — it needs no judgment and can't be rubber-stamped. The best review contract is one you eventually mechanize out of existence. Corollary: generated artifacts (`docs/errors/`, `derived/`, `tests/data/errors/error_identity.txt`, gateway model docs) must never appear in a contract's `review` list — reviewing generator *output* is how you end up editing generated files.
diff --git a/docs/under-the-hood/distributed-content-generation.md b/docs/under-the-hood/distributed-content-generation.md
index 3d16d7111..0d165400e 100644
--- a/docs/under-the-hood/distributed-content-generation.md
+++ b/docs/under-the-hood/distributed-content-generation.md
@@ -165,7 +165,7 @@ What gets stored vs. what crosses the boundary, by content type:
| Search sourced answer | Nothing (answer + source refs are small) | `SearchResultContent` (answer + `DocumentContent` sources) |
| Search structured | Nothing (JSON is small) | Raw `dict`, re-validated against the output class on the submitter |
-Each host-runtime plugin dispatches these through its own activities and queue routing; for the Temporal realization (the `act_*` activity set, per-activity task queues), see the `pipelex-temporal` plugin's docs.
+Each host-runtime plugin dispatches these through its own activities and queue routing; for the Temporal realization (the `act_*` activity set, per-activity task queues), see our Temporal plugin's own docs.
---
diff --git a/docs/under-the-hood/orchestrator-plugins.md b/docs/under-the-hood/orchestrator-plugins.md
index dc126ca96..0dd039264 100644
--- a/docs/under-the-hood/orchestrator-plugins.md
+++ b/docs/under-the-hood/orchestrator-plugins.md
@@ -1,23 +1,23 @@
---
title: "Orchestrator Plugins"
-description: "How Pipelex dispatches a pipe run by orchestration mode through the orchestrator seam, the Orchestrator SPI a host-runtime plugin compiles against, and how the external pipelex-temporal plugin rides it."
+description: "How Pipelex dispatches a pipe run by orchestration mode through the orchestrator seam, the Orchestrator SPI a host-runtime plugin compiles against, and how our external Temporal plugin rides it."
---
# Orchestrator Plugins
A pipe a host runtime invokes through the runtime bridge runs along **two orthogonal axes**:
-- **`orchestration_mode`** — *which* orchestrator runs the pipe. An **open string token**, not a closed enum: core owns only `"direct"` (in-process); every other token is contributed by the plugin that owns its orchestrator — [`"temporal"`](https://pipelex.com/products#temporal) (durable, on a Temporal worker fleet) by `pipelex-temporal`, [`"mistral-workflows"`](https://pipelex.com/products#mistral-workflows) (decomposed into Mistral Workflows primitives) by `pipelex-mistralai-workflows`. Neither is built into the open-source `pipelex` core: both ship as external, closed-source host-runtime backends, distributed privately rather than on PyPI as part of Pipelex's [workflow-orchestration offer](https://pipelex.com/products#durable-execution).
+- **`orchestration_mode`** — *which* orchestrator runs the pipe. An **open string token**, not a closed enum: core owns only `"direct"` (in-process); every other token is contributed by the plugin that owns its orchestrator — [`"temporal"`](https://pipelex.com/products#temporal) (durable, on a Temporal worker fleet) by our Temporal plugin, [`"mistral-workflows"`](https://pipelex.com/products#mistral-workflows) (decomposed into Mistral Workflows primitives) by our Mistral Workflows plugin. Neither is built into the open-source `pipelex` core: both ship as external, closed-source host-runtime backends, distributed privately rather than on PyPI as part of Pipelex's [workflow-orchestration offer](https://pipelex.com/products#durable-execution).
- **`delivery`** — *whether the caller waits*. A **closed** core `DeliveryMode` enum (`BLOCKING` / `FIRE_AND_FORGET`) on the wire input, set by the endpoint, never received from a caller. On the SPI it is expressed as *which method* the endpoint calls — `execute` (blocking) or `start` (fire-and-forget) — so each return type is truthful on its own; `supports_fire_and_forget` advertises whether an orchestrator can do genuine async.
-An **orchestrator** is what knows how to run a pipe under one token. Core names no orchestrator by import or by string. The bridge resolves the orchestrator for the requested token from a registry (keyed by the token `str`) and calls its `execute` — `"direct"` is contributed by a core plugin, `"temporal"` by the Temporal plugin, `"mistral-workflows"` by the external `pipelex-mistralai-workflows` plugin. A lookup miss raises a generic `MissingOrchestratorError` that names no orchestrator. This page documents that seam, the **Orchestrator SPI** a host-runtime plugin compiles against, and how the Temporal plugin is wired.
+An **orchestrator** is what knows how to run a pipe under one token. Core names no orchestrator by import or by string. The bridge resolves the orchestrator for the requested token from a registry (keyed by the token `str`) and calls its `execute` — `"direct"` is contributed by a core plugin, `"temporal"` by our Temporal plugin, `"mistral-workflows"` by our external Mistral Workflows plugin. A lookup miss raises a generic `MissingOrchestratorError` that names no orchestrator. This page documents that seam, the **Orchestrator SPI** a host-runtime plugin compiles against, and how the Temporal plugin is wired.
---
## The seam in one view
```
-<host-side bridge entry>(input_payload) # closed pipelex-transport library
+<host-side bridge entry>(input_payload) # not open core
→ build the PipeJob (boundary decode + library scope + trace_context)
→ orchestrator = get_orchestrator_registry().get_optional(mode=orchestration_mode)
→ if orchestrator is None: raise MissingOrchestratorError(mode) # generic, names no orchestrator
@@ -29,7 +29,7 @@ The registry is built once at boot from whatever the discovered plugins contribu
The *port* — `OrchestratorProtocol` and its registry — is kernel-layer, and the registry is set on the `RuntimeHub`. An orchestrator *adapter* is not: constructing one names the method interpreter, so the built-in `direct` one lives in `pipelex/interpreter_plugins/` rather than beside the inference plugins. An out-of-tree plugin makes the same split explicit instead of by directory: it declares its layer through the entry-point group it publishes under, and an orchestrator plugin therefore belongs in `pipelex.plugins.interpreter` ([below](#shipping-it-as-an-out-of-tree-plugin)). See [Hub layering](../contribute/hub-layering.md#where-the-built-in-plugins-split).
!!! note "Open seam, closed host-side entry"
- The host-side entry — the bridge entry point and `PipeJob` builder, plus the dispatch primitives that decode the boundary payload, scope the per-call library, and deliver results — lives in the **closed `pipelex-transport` library**. Embedding Pipelex into a host runtime (Temporal, Mistral, Airflow, your own) is a Pipelex [commercial capability](https://pipelex.com/products#durable-execution), not an open extension point. What stays **open** is the seam a third-party orchestrator extends: the orchestrator registry, `OrchestratorProtocol`, and the `pipelex.runtime_bridge` modules listed in [The Orchestrator SPI](#the-orchestrator-spi) below.
+ Pipelex's own host-side entry — the bridge entry point and `PipeJob` builder, plus the dispatch primitives that decode the boundary payload, scope the per-call library, and deliver results — is **not part of open core**: it backs a Pipelex [commercial capability](https://pipelex.com/products#durable-execution). What stays **open** is the seam you extend to run pipes on an orchestrator of your own: the orchestrator registry, `OrchestratorProtocol`, and the `pipelex.runtime_bridge` modules listed in [The Orchestrator SPI](#the-orchestrator-spi) below.
---
@@ -58,7 +58,7 @@ Constructing the orchestrator instance must be **import-light** — it must not
### A missing orchestrator is a generic, plugin-decoupled error
-A token with no registered orchestrator (its plugin is not installed) raises `MissingOrchestratorError(mode=...)` (`pipelex/runtime_bridge/exceptions.py`). The message names the token but **no orchestrator** — *"No orchestrator is registered for orchestration mode '{mode}'; is its plugin installed?"* — so core stays fully decoupled from its plugins (it never spells out `pipelex-temporal` / `pipelex-mistralai-workflows`). The one special case is the core `"direct"` token: its orchestrator is always present, so a miss there reports a boot/discovery fault. The message survives STRICT error disclosure.
+A token with no registered orchestrator (its plugin is not installed) raises `MissingOrchestratorError(mode=...)` (`pipelex/runtime_bridge/exceptions.py`). The message names the token but **no orchestrator** — *"No orchestrator is registered for orchestration mode '{mode}'; is its plugin installed?"* — so core stays fully decoupled from its plugins (it never spells out the Temporal or Mistral Workflows backend). The one special case is the core `"direct"` token: its orchestrator is always present, so a miss there reports a boot/discovery fault. The message survives STRICT error disclosure.
---
@@ -129,7 +129,7 @@ This is what lets the public `pipelex-api` base be orchestrator-agnostic and sti
Some orchestrators don't just serve a per-call mode — they reconfigure the whole process to run *as* that runtime (a Temporal worker). Such a plugin **claims process-global hub slots**, but only when the core-owned boot gate names it. `plugins.boot_orchestrator == self.name` means "boot this process as a Temporal-default runtime", not "the Temporal plugin is on". The gate is a backend-agnostic name-match — core names no orchestrator, and `register` reads no config file (the rich orchestrator config self-loads inside the thunks):
-Not every orchestrator goes this far. A per-call-only plugin — `pipelex-mistralai-workflows` is the minimal example — contributes just its `"mistral-workflows"` orchestrator and claims **no** hub slots: its router is installed per workflow invocation by the workflow body itself, so there is no process-global boot slot to claim and it never participates in the boot gate below. The boot-orchestrator machinery in this section applies only to a plugin that boots the process as its runtime (today, `pipelex-temporal`).
+Not every orchestrator goes this far. A per-call-only plugin — our Mistral Workflows plugin is the minimal example — contributes just its `"mistral-workflows"` orchestrator and claims **no** hub slots: its router is installed per workflow invocation by the workflow body itself, so there is no process-global boot slot to claim and it never participates in the boot gate below. The boot-orchestrator machinery in this section applies only to a plugin that boots the process as its runtime (today, our Temporal plugin).
```python
if registrar.config.plugins.boot_orchestrator == self.name:
@@ -147,7 +147,7 @@ Each `claim_*` takes a **thunk** (a zero-arg factory), never a constructed insta
The first four slots swap in the runtime's implementations of core execution services. The fifth, `claim_isolated_execution_probe`, is different in kind: its thunk resolves not a service but an **ambient predicate** (`Callable[[], bool]`) reporting whether the current call runs inside an isolated sub-execution — a Temporal activity — whose side-effecting emissions must not be written into the parent run's replay-deterministic buffer. `ReportingManager` consults it (`hub.is_in_isolated_execution()`) to route an activity-side usage emission to the per-process log instead of the workflow's registered buffer. It exists as a hub slot for the same reason the others do: only a boot-orchestrator plugin whose runtime has a replay/activity split knows how to answer, and core names no such runtime. Unclaimed (any in-process boot), the hub's core default answers "never isolated" — the in-process orchestrator has no such split.
-Because the gate is a name-match, `plugins.boot_orchestrator` must name a plugin that actually registered. After discovery, `Pipelex.setup` rejects a `boot_orchestrator` that no registered plugin carries — a typo or a missing plugin (e.g. `--orchestrator temporal` without `pipelex-temporal` installed) raises `UnknownBootOrchestratorError` instead of silently running in-process: nothing would claim the hub slots, so the process would otherwise fall through to the core defaults and execute on the wrong runtime. The check matches against **plugin names** (the same namespace the gate uses), not the `orchestration_mode` registry — a plugin's name and the token(s) it serves are separate namespaces that *may* differ, even where a shipped plugin keeps them identical (`pipelex-temporal` is named `temporal` and serves `temporal`). The error names no specific plugin, keeping core decoupled.
+Because the gate is a name-match, `plugins.boot_orchestrator` must name a plugin that actually registered. After discovery, `Pipelex.setup` rejects a `boot_orchestrator` that no registered plugin carries — a typo or a missing plugin (e.g. `--orchestrator temporal` without the Temporal plugin installed) raises `UnknownBootOrchestratorError` instead of silently running in-process: nothing would claim the hub slots, so the process would otherwise fall through to the core defaults and execute on the wrong runtime. The check matches against **plugin names** (the same namespace the gate uses), not the `orchestration_mode` registry — a plugin's name and the token(s) it serves are separate namespaces that *may* differ, even where a shipped plugin keeps them identical (our Temporal plugin is named `temporal` and serves `temporal`). The error names no specific plugin, keeping core decoupled.
### Injection precedence
@@ -165,47 +165,47 @@ A slot claim must never silently override an explicit injection. Only the conten
The plugin seam does **not** contribute commands to the host `pipelex` CLI. An operational command — a worker daemon, a one-time namespace bootstrap — is a daemon/utility, not a way a pipe *runs*, so a plugin that needs one ships its own `[project.scripts]` console script, which pip materializes into a standalone executable. Nothing is harvested onto `pipelex` at import time, so a broken or colliding plugin can never brick `pipelex --help` / `doctor` / `init`.
-The `pipelex-temporal` plugin follows this rule: its `worker` and `setup-namespace` commands ship as the `pipelex-temporal` console script (`pipelex-temporal worker`, `pipelex-temporal setup-namespace`), declared in the plugin distribution's `pyproject.toml`:
+Our Temporal plugin follows this rule: its `worker` and `setup-namespace` commands ship as that plugin's own console script, declared in the plugin distribution's `pyproject.toml`:
```toml
[project.scripts]
-pipelex-temporal = "pipelex_temporal.temporal_cli:app"
+my-runtime = "my_package.my_cli:app"
```
-Because the script is declared by the `pipelex-temporal` distribution itself, it travels with that dist — nothing in core to harvest or move.
+Because the script is declared by the plugin distribution itself, it travels with that dist — nothing in core to harvest or move.
---
## The Orchestrator SPI
-What an out-of-tree orchestrator imports *is* a contract. The SPI is a documented, versioned set of modules and symbols (gated by `PLUGIN_API_VERSION` in `pipelex/plugins/contract.py`) — not an `__init__.py` re-export shim. It is sized to what a real orchestrator (`pipelex-mistralai-workflows`) actually imports, not guessed. Anything an orchestrator needs that is *outside* this surface is a design bug — promote it into the SPI or remove the need.
+What an out-of-tree orchestrator imports *is* a contract. The SPI is a documented, versioned set of modules and symbols (gated by `PLUGIN_API_VERSION` in `pipelex/plugins/contract.py`) — not an `__init__.py` re-export shim. It is sized to what a real orchestrator (our Mistral Workflows plugin) actually imports, not guessed. Anything an orchestrator needs that is *outside* this surface is a design bug — promote it into the SPI or remove the need.
| Area | Modules / symbols |
|---|---|
| Boundary serialization + boot | `pipelex.runtime_bridge.serialization` (`serialize_pipe_output`, `serialize_completed_output`, `PIPE_DISPATCH_ERRORS`), `pipelex.runtime_bridge.payloads` (`PipelexPipeRunInput`, `PipelexPipeRunOutput`, `PipelexPipeDispatchAck`), `pipelex.runtime_bridge.bootstrap` (`ensure_pipelex_booted`) |
| Mode + delivery + errors | `pipelex.runtime_bridge.orchestration_mode` (`OrchestrationMode`, `DIRECT_ORCHESTRATION_MODE`), `pipelex.runtime_bridge.delivery_mode` (`DeliveryMode`), `pipelex.runtime_bridge.exceptions` (`MissingOrchestratorError`, `PipelexBridgeDispatchError`) |
-| Working-memory hydration | `pipelex.runtime_bridge.primitives.hydration` (re-hydrate `working_memory_raw` → typed `WorkingMemory`; stayed open because it is host-agnostic — used by core delivery and the open `pipelex-api` runner, and re-used across the boundary by `pipelex-transport`) |
+| Working-memory hydration | `pipelex.runtime_bridge.primitives.hydration` (re-hydrate `working_memory_raw` → typed `WorkingMemory`; stayed open because it is host-agnostic — used by core delivery and the open `pipelex-api` runner, and re-used across the boundary by the commercial plugins) |
| Plugin contract | `pipelex.plugins.contract` (`PipelexPlugin`, `PLUGIN_API_VERSION`), `pipelex.plugins.registrar` (`PluginRegistrar` menu: `add_orchestrator`, `add_bundle_validator`, `add_http_error_mapper`, `claim_*`, `add_teardown`; read accessor: `get_http_error_mappers`), `pipelex.plugins.orchestrator_registry` (`OrchestratorProtocol`), `pipelex.plugins.bundle_validator_registry` (`BundleValidatorProtocol`, `BundleValidationVerdict`) |
-| Execution protocols | `PipeRouterProtocol`, `PipeRunProtocol`, `ContentGeneratorProtocol`, the task-manager protocol |
+| Execution protocols | `PipeRouterProtocol` (incl. the [`run_batch_branch`](./pipe-routing-and-execution.md#the-batch-branch-hook) fan-out hook — concrete default, override it only to isolate batch branches), `PipeRunProtocol`, `ContentGeneratorProtocol`, the task-manager protocol |
| Payload / core types | `PipeJob`, `PipeOutput`, `DeliveryAssignment`, `WorkingMemory` (+ factory, `dump_for_transport`), `JobMetadata`, `LibraryCrate` |
| Library + hub scoping | `set_current_library` / `get_current_library`, `scoped_pipe_router`, `get_class_registry` (per-call library hydration via `library_crate_dump`) |
| Tracing / graph hooks | `trace_events`, `graph_tracer_manager`, `tracing_assembly` (per-step trace/usage events across the boundary) |
-!!! warning "Not in the open SPI — the closed `pipelex-transport` layer"
- The host-side bridge entry point, the cross-process dispatch primitives (boundary delivery, pipe classification, submitter-side hydration, trace flush, scoped-library, and the submit-arg envelope), and the transport-prep helpers were extracted out of open core into the **closed `pipelex-transport` library**. Embedding Pipelex into a host runtime is a Pipelex commercial capability — Pipelex's own host-runtime plugins (`pipelex-temporal`, `pipelex-mistralai-workflows`) compile against `pipelex-transport`; a third-party out-of-tree orchestrator compiles against the **open** rows above only.
+!!! warning "Not in the open SPI"
+ The host-side bridge entry point, the cross-process dispatch primitives (boundary delivery, pipe classification, submitter-side hydration, trace flush, scoped-library, and the submit-arg envelope), and the transport-prep helpers were all extracted **out of open core**. Pipelex's own host-runtime embedding is a commercial capability — our Temporal and Mistral Workflows plugins build on that closed side; a third-party out-of-tree orchestrator compiles against the **open** rows above only.
---
-## Worked example: the `pipelex-temporal` plugin
+## Worked example: our Temporal plugin
-`pipelex_temporal/temporal_plugin.py` (in the external `pipelex-temporal` distribution) is the reference orchestrator plugin. Its `register`:
+Our Temporal plugin — external, closed-source, shipped as its own distribution — is the reference orchestrator plugin. Its `register`:
- **always** (regardless of the boot gate): contributes a single `TemporalOrchestrator` registered once under the `"temporal"` token (import-light; `temporalio` is pulled lazily inside `execute`/`start`), the matching `TemporalBundleValidator` under the same token (the worker-dispatched `/validate` arm), and an HTTP error mapper classifying Temporal transport faults. The orchestrator advertises `supports_fire_and_forget = True`; its `execute` awaits completion and reports `make_workflow_id(...)`, its `start` enqueues the workflow and returns a `PipelexPipeDispatchAck` carrying the workflow id;
- **only when `plugins.boot_orchestrator == "temporal"`**: claims the content-generator / task-manager / pipe-router / pipe-run / isolated-execution-probe hub slots with thunks and registers the teardown callback — booting this process as a Temporal-default runtime.
-The orchestrator itself (`pipelex_temporal/temporal_orchestrators.py`) keeps the `WorkflowExecutionError` catch and the `make_workflow_id` recompute in the blocking `execute` arm. It serializes its `PipeOutput` through `pipelex.runtime_bridge.serialization`, shared with the core DIRECT orchestrator so the boundary shape cannot drift.
+The orchestrator itself keeps the `WorkflowExecutionError` catch and the `make_workflow_id` recompute in the blocking `execute` arm. It serializes its `PipeOutput` through `pipelex.runtime_bridge.serialization`, shared with the core DIRECT orchestrator so the boundary shape cannot drift.
-The Temporal plugin is **external** — it ships as the `pipelex-temporal` distribution and is discovered through a `pipelex.plugins.interpreter` entry point in that dist's `pyproject.toml`, not through `BUILTIN_PLUGINS`. Core's built-ins hold only the always-shipped inference and `direct` plugins and explicitly exclude Temporal — split by layer across `pipelex/providers/builtins.py` (the kernel adapters) and `pipelex/interpreter_plugins/builtins.py` (the interpreter-touching `direct` and `pipe_func` plugins, which is also where the two halves are composed); installing `pipelex-temporal` is all it takes to make the `"temporal"` orchestrator available — zero config, no core import of `temporalio`. Its operational `worker` / `setup-namespace` commands ship as the standalone `pipelex-temporal` console script, so they travel with that dist.
+The Temporal plugin is **external** — it ships as its own distribution and is discovered through a `pipelex.plugins.interpreter` entry point in that dist's `pyproject.toml`, not through `BUILTIN_PLUGINS`. Core's built-ins hold only the always-shipped inference and `direct` plugins and explicitly exclude Temporal — split by layer across `pipelex/providers/builtins.py` (the kernel adapters) and `pipelex/interpreter_plugins/builtins.py` (the interpreter-touching `direct` and `pipe_func` plugins, which is also where the two halves are composed); installing the plugin is all it takes to make the `"temporal"` orchestrator available — zero config, no core import of `temporalio`. Its operational `worker` / `setup-namespace` commands ship as that dist's own standalone console script, so they travel with it.
---
diff --git a/docs/under-the-hood/pipe-routing-and-execution.md b/docs/under-the-hood/pipe-routing-and-execution.md
index 4b2343a7f..c0e81adf5 100644
--- a/docs/under-the-hood/pipe-routing-and-execution.md
+++ b/docs/under-the-hood/pipe-routing-and-execution.md
@@ -19,7 +19,7 @@ Pipelex runs pipes either **direct** (single-process) or **distributed** on a ho
---
!!! note "The runtime bridge"
- Both distributed paths reach pipe execution through the framework-agnostic runtime bridge. The open `pipelex/runtime_bridge/` keeps the boot, serialization, mode/delivery, and worker-side hydration (`primitives/hydration.py`) pieces; the cross-process **dispatch** primitives — classifying controller pipes as child workflows and leaf operators as activities (`pipe_classification`), flushing trace events (`trace_flush`), and delivering results (`delivery`) — were extracted into the closed `pipelex-transport` library, which both commercial host-runtime plugins import. Graph and token-usage assembly is not a bridge primitive — it lives in `pipelex/pipe_run/tracing_assembly.py` and runs the same way for local and distributed runs.
+ Both distributed paths reach pipe execution through the framework-agnostic runtime bridge. The open `pipelex/runtime_bridge/` keeps the boot, serialization, mode/delivery, and worker-side hydration (`primitives/hydration.py`) pieces; the cross-process **dispatch** primitives — classifying controller pipes as child workflows and leaf operators as activities (`pipe_classification`), flushing trace events (`trace_flush`), and delivering results (`delivery`) — were extracted out of open core, and both commercial host-runtime plugins get them from the closed side. Graph and token-usage assembly is not a bridge primitive — it lives in `pipelex/pipe_run/tracing_assembly.py` and runs the same way for local and distributed runs.
---
@@ -49,7 +49,7 @@ The `PipeJob` is the universal unit of execution. It carries everything needed t
| `output_name` | `str \| None` | Override for the output variable name |
| `library_crate` | `LibraryCrate \| None` | Serializable library snapshot for distributed execution |
-`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 in the closed `pipelex-transport` library moves `working_memory` to `working_memory_raw` (deferred hydration) and ensures the crate is attached.
+`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.
---
@@ -109,7 +109,7 @@ PipeRouter.run(pipe_job)
### Router Selection
-The router is selected during `Pipelex.setup()` by resolving the hub's `PIPE_ROUTER` slot. A boot-orchestrator plugin (e.g. the closed `pipelex-temporal` plugin) claims that slot in its `register()` when `plugins.boot_orchestrator` names it; otherwise the default in-process router is used:
+The router is selected during `Pipelex.setup()` by resolving the hub's `PIPE_ROUTER` slot. A boot-orchestrator plugin (e.g. our closed Temporal plugin) claims that slot in its `register()` when `plugins.boot_orchestrator` names it; otherwise the default in-process router is used:
```python
# A boot-orchestrator plugin swaps in its distributed router when
@@ -137,6 +137,19 @@ async def _run_pipe_job(self, pipe_job: PipeJob) -> PipeOutput:
The router does not route by pipe type — it delegates to the pipe itself. Controllers handle their own orchestration internally.
+### The batch-branch hook
+
+`PipeRouterProtocol` carries one more entry point beside `run`:
+
+```python
+async def run_batch_branch(self, pipe_job: PipeJob) -> PipeOutput:
+ return await self.run(pipe_job)
+```
+
+`PipeBatch` calls it instead of `run` for each per-item fan-out dispatch. That is the only place in the pipe tree where the *dispatch* carries semantics its `PipeJob` cannot express: a branch job holds the branch pipe and the item's memory, which is byte-for-byte the shape of any other dispatch. The hook is how a router learns "this one is a fan-out branch".
+
+The default body IS the behavior for in-process routers — a branch is just a run, so `PipeRouter` deliberately does not override it and nothing about direct execution changed. A **distributed** router may override it to give each branch its own isolation (own retry, own history partition) while every other dispatch it receives runs inline. Because the default delegates to `run` and not to `_run_pipe_job`, batch branches still pass through the observer hooks.
+
---
## Pipe Controllers
@@ -153,7 +166,7 @@ Controllers are pipes that orchestrate the execution of other pipes. They resolv
All controllers follow the same pattern:
1. Call `get_required_pipe(child_pipe_code)` to resolve the child pipe from the library
-2. Route through `get_pipe_router().run(PipeJob(...))` — the hub auto-selects the right router
+2. Route through `get_pipe_router().run(PipeJob(...))` — the hub auto-selects the right router. `PipeBatch` is the one exception: its per-item branch dispatches go through [`run_batch_branch`](#the-batch-branch-hook) instead, so a distributed router can isolate them.
3. Aggregate results into working memory or output
### Auto-Switching Router
@@ -161,9 +174,9 @@ All controllers follow the same pattern:
The hub (`get_pipe_router()`) returns the router for whichever orchestrator the process is booted under:
- **Direct execution**: the in-process `PipeRouter` — child pipes run in the same process.
-- **Distributed execution**: the booted host-runtime orchestrator's router, which has claimed the hub's `PIPE_ROUTER` slot. That router auto-detects whether it is dispatching from the **submitter** (start a top-level workflow) or from **inside a running workflow** (start a child workflow). Pipelex's Temporal backend realizes this as `TemporalPipeRouter`, which picks `execute_workflow` vs `execute_child_workflow` accordingly.
+- **Distributed execution**: the booted host-runtime orchestrator's router, which has claimed the hub's `PIPE_ROUTER` slot. That router auto-detects whether it is dispatching from the **submitter** (start a unit of durable work) or from **inside a running one** (continue within it, or spawn a nested unit).
-This means each child pipe in a controller gets its own workflow boundary in distributed mode — enabling independent retries, separate worker assignment, and per-pipe visibility in the host runtime's UI.
+How much of a controller tree a distributed backend spreads across separate durable units is that backend's call, not core's — core's contract is only that every dispatch reaches the router, and that batch branches are *labelled* as such via `run_batch_branch`. See the backend's own documentation for the topology it chooses.
!!! note "Library Dependency"
Controllers depend on the library being loaded in the current process. `get_required_pipe()` queries the library scoped to the current run via `ContextVar`, which must have been populated by loading a `LibraryCrate`. In distributed execution, each worker-side job loads the crate from the `PipeJob` into a per-run `Library` instance before resolving child pipes. (Temporal-specific detail: the backend disables the Temporal sandbox via `--no-sandbox` because library loading is a side effect incompatible with replay semantics.) See [Runtime Bridge & Transport](./runtime-bridge-and-transport.md) for how the crate and working memory cross the boundary.
@@ -189,10 +202,10 @@ sequenceDiagram
Note over S: TemporalPipeRouter.run() (submitter side)
S->>S: transport prep (closed)<br/>(WM → working_memory_raw)
- S->>T: Submit WfPipeRouter(PipeJob)
+ S->>T: Submit run workflow(PipeJob)
T->>W: Dispatch workflow
- Note over W: WfPipeRouter.run()
+ Note over W: run workflow
W->>W: Create per-workflow ClassRegistry
W->>W: Load LibraryCrate (register classes)
W->>W: Hydrate working_memory_raw → WM
@@ -200,7 +213,7 @@ sequenceDiagram
alt Concrete pipe
W->>W: Execute via Activity
- else Controller pipe
+ else Dispatch the backend chooses to isolate
W->>T: Child workflow (crate propagates)
T->>W: Child result
end
@@ -218,13 +231,13 @@ A host-runtime orchestrator supplies the pieces that turn this generic shape int
- a **router** implementing `PipeRouterProtocol` (`TemporalPipeRouter`) that dispatches via Temporal instead of running in-process;
- a **worker-side job** (a Temporal workflow) that receives a deserialized `PipeJob`, loads the crate, hydrates working memory, and calls `pipe.run_pipe()` — exactly like the direct router;
- a **data converter** that uses Kajson to (de)serialize Pydantic models with subclass types preserved — critical because `PipeJob.pipe` is a `PipeAbstract` subclass and `WorkingMemory` holds `Stuff` objects with concept-specific content classes;
-- a **worker entry point** that calls `Pipelex.make(boot_orchestrator="temporal")` and starts the worker with its registered workflows and activities (shipped as the `pipelex-temporal worker` console command).
+- a **worker entry point** that calls `Pipelex.make(boot_orchestrator="temporal")` and starts the worker with its registered workflows and activities (shipped as the plugin's own `worker` console command).
-The concrete modules live in the closed `pipelex-temporal` plugin (`pipelex_temporal/...`), documented in that repo. The open contracts they satisfy — `PipeRouterProtocol`, the boundary DTOs, serialization — are listed in the [Orchestrator SPI](./orchestrator-plugins.md#the-orchestrator-spi).
+The concrete modules live in our closed Temporal plugin and are documented with it. The open contracts they satisfy — `PipeRouterProtocol`, the boundary DTOs, serialization — are listed in the [Orchestrator SPI](./orchestrator-plugins.md#the-orchestrator-spi).
### Content generation activities
-Concrete pipe operators (PipeLLM, PipeCompose, PipeExtract, PipeImgGen) dispatch their actual leaf work as host-runtime activities, invoked from inside the worker-side job via the runtime's in-workflow content generator — no intermediate child workflow per content-generation call. A backend can route those activities to different task queues per activity (and, where applicable, per handle); in the Temporal backend that routing is configured under the plugin's own `[worker_config.activity_queues]` config (in the plugin's `temporal.toml`, not core config), falling back to the job's own task queue when unset. The concrete activity set and queue-routing reference live in the `pipelex-temporal` plugin's docs; see also [Content Generation Across Boundaries](./distributed-content-generation.md) for the backend-neutral serialization mechanism.
+Concrete pipe operators (PipeLLM, PipeCompose, PipeExtract, PipeImgGen) dispatch their actual leaf work as host-runtime activities, invoked from inside the worker-side job via the runtime's in-workflow content generator — no intermediate child workflow per content-generation call. A backend can route those activities to different task queues per activity (and, where applicable, per handle); in the Temporal backend that routing is configured under the plugin's own `[worker_config.activity_queues]` config (in the plugin's `temporal.toml`, not core config), falling back to the job's own task queue when unset. The concrete activity set and queue-routing reference live in our Temporal plugin's own docs; see also [Content Generation Across Boundaries](./distributed-content-generation.md) for the backend-neutral serialization mechanism.
!!! note "Future Improvement: Per-Pipe Routing"
Router selection is currently global and binary: either all pipes go through the distributed backend, or none do. A simple `PipeCompose` (microseconds of Jinja2 rendering) gets the same dispatch overhead as a `PipeLLM` (minutes of API call time). Per-pipe or per-type routing decisions could improve efficiency.
@@ -236,11 +249,11 @@ Concrete pipe operators (PipeLLM, PipeCompose, PipeExtract, PipeImgGen) dispatch
Distributed execution introduces three mechanisms that don't exist in direct mode, because the worker is a separate process that shares none of the submitter's library, class registry, or working-memory state. They are backend-neutral; for the full walkthrough see [Runtime Bridge & Transport](./runtime-bridge-and-transport.md). In short:
- **LibraryCrate propagation** — the submitter attaches a serializable snapshot of all pipes and concepts to the `PipeJob`; every worker-side job loads it (idempotently, by fingerprint) so `get_required_pipe()` resolves at every level.
-- **Deferred hydration** — `WorkingMemory` crosses as a raw JSON dict (`working_memory_raw`) on both `PipeJob` inputs and `PipeOutput` return values, avoiding deserialization failures when a receiving process hasn't registered the bundle's dynamic concept classes. The transport-prep helpers live in the closed `pipelex-transport` library; the raw field and the hydration helper stay in open core.
+- **Deferred hydration** — `WorkingMemory` crosses as a raw JSON dict (`working_memory_raw`) on both `PipeJob` inputs and `PipeOutput` return values, avoiding deserialization failures when a receiving process hasn't registered the bundle's dynamic concept classes. The transport-prep helpers are not part of open core; the raw field and the hydration helper are.
- **Per-call isolation** — each job gets its own `ClassRegistry` (pre-seeded from the global registry) and its own `Library`, scoped via `ContextVar`, so concurrent jobs with conflicting concept names (e.g., two bundles that both define `Result` with different fields) don't cross-contaminate.
!!! warning "Known backend limitation: StuffArtefact in dry-run"
- On a host runtime whose data converter serializes working memory for internal templating activities (Temporal's `act_jinja2_gen_text`, dispatched by PipeCondition and PipeCompose), dry-run mode can fail: working memory then holds `StuffArtefact` debug objects that are not JSON-serializable. PipeSequence and PipeParallel are unaffected — they dispatch child pipes without internal templating activities. This is a backend-specific concern; see the `pipelex-temporal` plugin docs for details and fix direction.
+ On a host runtime whose data converter serializes working memory for internal templating activities (Temporal's `act_jinja2_gen_text`, dispatched by PipeCondition and PipeCompose), dry-run mode can fail: working memory then holds `StuffArtefact` debug objects that are not JSON-serializable. PipeSequence and PipeParallel are unaffected — they dispatch child pipes without internal templating activities. This is a backend-specific concern; see our Temporal plugin's own docs for details and fix direction.
---
@@ -297,7 +310,7 @@ flowchart TB
| Pipeline setup | `pipelex/pipeline/pipeline_run_setup.py` |
| PipeRouter (direct) | `pipelex/pipe_run/pipe_router.py` |
| PipeRouterProtocol | `pipelex/pipe_run/pipe_router_protocol.py` |
-| Distributed router / worker job / data converter / worker CLI | backend-specific — in the host-runtime plugin (e.g. `pipelex_temporal/...`), not open core |
+| Distributed router / worker job / data converter / worker CLI | backend-specific — in the host-runtime plugin (e.g. our Temporal plugin), not open core |
| Library manager | `pipelex/libraries/library_manager.py` |
| ConceptFactory | `pipelex/core/concepts/concept_factory.py` |
| StructureGenerator | `pipelex/core/concepts/structure_generation/generator.py` |
diff --git a/docs/under-the-hood/runtime-bridge-and-transport.md b/docs/under-the-hood/runtime-bridge-and-transport.md
index 1a5804651..8dc925d6c 100644
--- a/docs/under-the-hood/runtime-bridge-and-transport.md
+++ b/docs/under-the-hood/runtime-bridge-and-transport.md
@@ -1,6 +1,6 @@
---
title: "Runtime Bridge & Transport"
-description: "The backend-neutral seam that carries a pipe run across process boundaries — boundary DTOs, LibraryCrate propagation, deferred hydration, and per-call registry/library isolation — and where open core ends and the closed pipelex-transport layer begins."
+description: "The backend-neutral seam that carries a pipe run across process boundaries — boundary DTOs, LibraryCrate propagation, deferred hydration, and per-call registry/library isolation — and where open core ends."
---
# Runtime Bridge & Transport
@@ -10,7 +10,7 @@ This page is for contributors working on Pipelex internals. For the capability o
Pipelex runs a pipe either **direct** (everything in one Python process) or **distributed** on a host runtime (a separate worker process, potentially on another machine). Both paths reach pipe execution through the same framework-agnostic **runtime bridge**. This page documents that bridge backend-neutrally: the boundary data types, how a library snapshot and working memory cross a process boundary, and how concurrent runs stay isolated. The concrete realizations — Temporal-backed durable execution and the Mistral Workflows integration — are commercial Pipelex platform capabilities; their backend-specific topology lives in their own plugin repos.
!!! info "A commercial capability rides on this seam"
- Embedding a Pipelex pipe run into a host runtime — so it executes as durable, distributed workflows — is part of Pipelex's [workflow-orchestration offer](https://pipelex.com/products#durable-execution). This page documents the **open seam** and the **open boundary types**; the cross-process plumbing that drives them lives in the closed `pipelex-transport` library (see [Where open core ends](#where-open-core-ends-and-pipelex-transport-begins) below). For the orchestrator extension point a third-party backend compiles against, see [Orchestrator Plugins](./orchestrator-plugins.md).
+ Pipelex's own host-runtime embedding — running a pipe as durable, distributed workflows — is part of Pipelex's [workflow-orchestration offer](https://pipelex.com/products#durable-execution). This page documents the **open seam** and the **open boundary types**; the cross-process plumbing that drives them is not part of open core (see [Where open core ends](#where-open-core-ends) below). For the orchestrator extension point a third-party backend compiles against, see [Orchestrator Plugins](./orchestrator-plugins.md).
---
@@ -110,7 +110,7 @@ The worker-side hydration helper (`pipelex/runtime_bridge/primitives/hydration.p
Because delivery renders from the raw dict (`pipelex/pipe_run/delivery_executor.py` branches on which field is populated), a delivery worker never needs the crate loaded — which is the precondition for true distributed execution. Dynamic concepts lose typed rendering on the delivery worker (a generic field-walking fallback still produces readable JSON/HTML), but the worker stays crate-free.
!!! note "Where the transport prep lives"
- Moving working memory into `working_memory_raw` for a job, dehydrating a result before return, and the submitter-side rehydration are part of the **closed `pipelex-transport`** library — they are the cross-process plumbing. The *raw field itself*, `dump_for_transport`, and the worker-side hydration helper stay **open core**, because they are host-agnostic and are also exercised by the open `pipelex-api` runner.
+ Moving working memory into `working_memory_raw` for a job, dehydrating a result before return, and the submitter-side rehydration are cross-process plumbing, and are **not** part of open core. The *raw field itself*, `dump_for_transport`, and the worker-side hydration helper stay **open core**, because they are host-agnostic and are also exercised by the open `pipelex-api` runner.
---
@@ -127,7 +127,7 @@ The class-registry accessor and its library scoping (`pipelex/runtime_hub.py`, `
---
-## Where open core ends and `pipelex-transport` begins
+## Where open core ends
The boundary types and the host-agnostic helpers are **open** (MIT, in the `pipelex` distribution):
@@ -139,9 +139,9 @@ The boundary types and the host-agnostic helpers are **open** (MIT, in the `pipe
| Working-memory raw + dump | `working_memory_raw`, `WorkingMemory.dump_for_transport` |
| Worker-side hydration | `runtime_bridge/primitives/hydration.py` |
-The cross-process *plumbing* that drives a pipe run across the boundary — the host-side bridge entry point, the transport-prep step, and the dispatch primitives (submitter rehydration, delivery, trace flush, scoped-library, pipe classification, and the submit-arg envelope) — is **closed** (the proprietary `pipelex-transport` library, installed via git+ssh, pinned to an exact core rev). Embedding Pipelex into a host runtime is a commercial capability, not an open extension seam.
+The cross-process *plumbing* that drives a pipe run across the boundary — the host-side bridge entry point, the transport-prep step, and the dispatch primitives (submitter rehydration, delivery, trace flush, scoped-library, pipe classification, and the submit-arg envelope) — is **not open core**. Pipelex's own host-runtime embedding is a commercial capability.
-A third-party orchestrator compiles against the **open** surface only (the [Orchestrator SPI](./orchestrator-plugins.md#the-orchestrator-spi)); Pipelex's own host-runtime plugins (`pipelex-temporal`, `pipelex-mistralai-workflows`) additionally compile against `pipelex-transport`.
+A third-party orchestrator compiles against the **open** surface only (the [Orchestrator SPI](./orchestrator-plugins.md#the-orchestrator-spi)); Pipelex's own host-runtime plugins (Temporal, Mistral Workflows) additionally build on the closed side.
---
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index 0db7efe96..6b74cf706 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -196,8 +196,8 @@ class ErrorDomain(StrEnum):
def error_domain_to_http_status(error_domain: ErrorDomain | str | None) -> int:
"""Map an error domain to an HTTP status code.
- Domain-level building block for downstream HTTP APIs (``pipelex-relay``,
- ``pipelex-back-office``). When you have a full :class:`ErrorReport`, prefer
+ Domain-level building block for downstream HTTP APIs that render an
+ :class:`ErrorReport` as a response. When you have a full report, prefer
:attr:`ErrorReport.http_status` — it layers the provider 429 (rate-limit)
passthrough on top of this mapping. The library itself stays HTTP-agnostic —
no web-framework import lives here, only the mapping table.
diff --git a/pipelex/builder/pipe/pipe_signature_spec.py b/pipelex/builder/pipe/pipe_signature_spec.py
index deb277ddd..08c02aea1 100644
--- a/pipelex/builder/pipe/pipe_signature_spec.py
+++ b/pipelex/builder/pipe/pipe_signature_spec.py
@@ -51,7 +51,7 @@ class PipeSignatureSpec(PipeSpec):
type: SkipJsonSchema[Literal["PipeSignature"]] = Field(default="PipeSignature", exclude=True)
# Spec-layer authoring tag only: NOT propagated by `to_blueprint()`, which leaves the blueprint
# (and runtime) at `pipe_category = None` because a signature is outside the executable taxonomy.
- # Retained per the scope decision in wip/recursivity/signature-taxonomy-refactor.md; no longer
+ # Retained per the signature-taxonomy scope decision; no longer
# surfaced in `rendered_pretty` (a signature now renders as "Signature (contract only)", with no
# type/category line). `exclude=True` (like `type`) keeps it out of `model_dump()` so it is not a
# stray key on a round-trip.
diff --git a/pipelex/cli/agent_cli/commands/codegen/app.py b/pipelex/cli/agent_cli/commands/codegen/app.py
index 0f3daa4a3..56130b89f 100644
--- a/pipelex/cli/agent_cli/commands/codegen/app.py
+++ b/pipelex/cli/agent_cli/commands/codegen/app.py
@@ -1,6 +1,6 @@
"""Agent CLI codegen subcommand group.
-The agent-CLI mirror of the bare `pipelex codegen` family (see `docs/specs/pipelex-codegen.md` →
+The agent-CLI mirror of the bare `pipelex codegen` family (see the codegen spec →
"CLI: codegen"): the same engine, presented through the agent CLI's two-stream envelopes
(`--format` / `--error-format`, markdown default). `inputs` has no mirror here — the existing
`pipelex-agent inputs` group already surfaces that projection.
diff --git a/pipelex/cli/commands/build/structures_cmd.py b/pipelex/cli/commands/build/structures_cmd.py
index 3c0cf372e..d13ba3b6f 100644
--- a/pipelex/cli/commands/build/structures_cmd.py
+++ b/pipelex/cli/commands/build/structures_cmd.py
@@ -3,7 +3,7 @@
The legacy per-file generator (one always-qualified class file per concept) was deleted when the
codegen engine landed (D9): this command now delegates verbatim to the engine, which emits a single
stamped `structures.py` (bare-when-unique class names, declared imprecision, `codegen.lock` beside
-it). See `docs/specs/pipelex-codegen.md` -> "CLI: codegen".
+it). See the codegen spec -> "CLI: codegen".
"""
from pathlib import Path
diff --git a/pipelex/cli/commands/codegen/check_cmd.py b/pipelex/cli/commands/codegen/check_cmd.py
index d73d0c73e..329f410bc 100644
--- a/pipelex/cli/commands/codegen/check_cmd.py
+++ b/pipelex/cli/commands/codegen/check_cmd.py
@@ -6,7 +6,7 @@ action). The verdict rides the structured `CodegenCheckReport`; the exit code mi
`validate`/`resolve` group — `0` current, `1` drift present (a negative verdict), `2` no lock found (no
verdict).
-See `docs/specs/pipelex-codegen.md` → "Offline check algorithm".
+See the codegen spec → "Offline check algorithm".
"""
from pathlib import Path
diff --git a/pipelex/cli/commands/codegen/inputs_cmd.py b/pipelex/cli/commands/codegen/inputs_cmd.py
index 18da266c7..5e7c20256 100644
--- a/pipelex/cli/commands/codegen/inputs_cmd.py
+++ b/pipelex/cli/commands/codegen/inputs_cmd.py
@@ -5,7 +5,7 @@ Inputs light shape by default, `--explicit` for the ceremonial `{concept, conten
is selected by qualified `--pipe` ref and defaults to the closure's declared `main_pipe`. The crate
loader leaves the library open and current, so the live pipe is rendered directly.
-See `docs/specs/pipelex-codegen.md` -> "CLI: codegen".
+See the codegen spec -> "CLI: codegen".
"""
from pathlib import Path
diff --git a/pipelex/cli/commands/codegen/types_cmd.py b/pipelex/cli/commands/codegen/types_cmd.py
index 1cb3b607a..b7c9c7a36 100644
--- a/pipelex/cli/commands/codegen/types_cmd.py
+++ b/pipelex/cli/commands/codegen/types_cmd.py
@@ -5,7 +5,7 @@ normalize the closure into a crate, project its concept set for the chosen `--ta
emitted file under the output root. The verdict (resolved / invalid library) rides the resolve exit
codes via `load_normalized_crate_or_exit`; the success stream is the list of written files.
-See `docs/specs/pipelex-codegen.md` -> "CLI: codegen" and "Two axes".
+See the codegen spec -> "CLI: codegen" and "Two axes".
"""
from pathlib import Path
diff --git a/pipelex/cli/commands/crate_loading.py b/pipelex/cli/commands/crate_loading.py
index aaf739abe..3d7d65193 100644
--- a/pipelex/cli/commands/crate_loading.py
+++ b/pipelex/cli/commands/crate_loading.py
@@ -9,7 +9,7 @@ verdict. `load_normalized_crate` is the presentation-free core (typed exceptions
wrapper `load_normalized_crate_or_exit` maps them to the 1/2 exit codes, and the agent CLI maps the
same exceptions to its structured error envelope.
-See `docs/specs/pipelex-codegen.md` → "CLI: resolve" and the standard's `library-crate.md`.
+See the codegen spec → "CLI: resolve" and the standard's `library-crate.md`.
"""
from pathlib import Path
diff --git a/pipelex/cli/commands/resolve_cmd.py b/pipelex/cli/commands/resolve_cmd.py
index 2233ab12b..2928a0e26 100644
--- a/pipelex/cli/commands/resolve_cmd.py
+++ b/pipelex/cli/commands/resolve_cmd.py
@@ -6,7 +6,7 @@ emits the normalized crate to stdout in the selected encoding. The success strea
verdict rides the exit code, mirroring the bare `validate` group — `0` resolved, `1` produced a negative
verdict (the library is invalid), `2` no verdict could be produced (nothing to resolve / load failure).
-See `docs/specs/pipelex-codegen.md` → "CLI: resolve" and the standard's `library-crate.md`.
+See the codegen spec → "CLI: resolve" and the standard's `library-crate.md`.
"""
from pathlib import Path
diff --git a/pipelex/codegen/check.py b/pipelex/codegen/check.py
index 8cf67d6a5..530fefebc 100644
--- a/pipelex/codegen/check.py
+++ b/pipelex/codegen/check.py
@@ -5,7 +5,7 @@
(this CLI, an SDK, a short CI script) implements it identically, and template improvements never redden
a consumer's CI: regeneration is a dev action, the check is the CI action.
-The algorithm (see `docs/specs/pipelex-codegen.md` → "Offline check algorithm"):
+The algorithm (see the codegen spec → "Offline check algorithm"):
1. For each artifact in the lock, locate the file and recompute its body content hash; a mismatch or a
missing file is a drift.
diff --git a/pipelex/codegen/emitters/naming.py b/pipelex/codegen/emitters/naming.py
index 954efa68f..8134eaff8 100644
--- a/pipelex/codegen/emitters/naming.py
+++ b/pipelex/codegen/emitters/naming.py
@@ -1,4 +1,4 @@
-"""Name-derivation rules shared by every types emitter (see `docs/specs/pipelex-codegen.md`).
+"""Name-derivation rules shared by every types emitter (see the codegen spec).
A qualified concept `domain.Code` yields a type named from `Code` (already PascalCase) when that
code is unique across the crate; when the code collides across domains, the domain disambiguates.
diff --git a/pipelex/codegen/emitters/target.py b/pipelex/codegen/emitters/target.py
index 81a2867d4..cfa0b6e16 100644
--- a/pipelex/codegen/emitters/target.py
+++ b/pipelex/codegen/emitters/target.py
@@ -1,6 +1,6 @@
"""The two codegen axes (`kind` and `target`) and the emitted-file unit shared by every emitter.
-Codegen has exactly two explicit axes (see `docs/specs/pipelex-codegen.md` → "Two axes"): `kind` is
+Codegen has exactly two explicit axes (see the codegen spec → "Two axes"): `kind` is
*what* to project (`types`, over the crate's concept set), `target` is *for whom* (a language / idiom
flavor). An emitter returns one or more `EmittedFile`s — a filename relative to the output root plus
its content — so a single projection can span more than one file (the ts-zod purity split: a pure
@@ -29,7 +29,7 @@ class CodegenKind(StrEnum):
class CodegenTarget(StrEnum):
"""A codegen target flavor. All targets are Pipelex projections — the MTHDS standard specifies no
- type projection (see `docs/specs/pipelex-codegen.md` → "Ownership"). They differ in audience:
+ type projection (see the codegen spec → "Ownership"). They differ in audience:
`ts-zod` and `python-pydantic` emit idiom-neutral types any consumer can use; `python-structures`
emits StructuredContent classes for a Pipelex runtime host.
"""
diff --git a/pipelex/codegen/emitters/ts_zod.py b/pipelex/codegen/emitters/ts_zod.py
index 9cdb6e128..a6bcbc058 100644
--- a/pipelex/codegen/emitters/ts_zod.py
+++ b/pipelex/codegen/emitters/ts_zod.py
@@ -12,7 +12,7 @@ corrupt arbitrary keys inside a `z.record()` / `z.unknown()` value (a camelCase
tell a schema-declared field key from arbitrary data — e.g. `native.JSON`'s `json_obj` map). The
inferred `z.infer` types therefore carry snake_case keys. (This departs from a camelCase-TS convention;
if camelCase ergonomics are later wanted they must ride a *schema-aware* transform, not a blind deep
-key remap — see D10 in `_codegen/TODOS.md`.) Concept references use `z.lazy(() => XSchema)` so schema
+key remap.) Concept references use `z.lazy(() => XSchema)` so schema
declaration order is irrelevant and reference cycles are handled.
TypeScript customization is by declaration merging (augment the generated `interface`/module from a
diff --git a/pipelex/codegen/lock.py b/pipelex/codegen/lock.py
index 6a1c64933..1795ef789 100644
--- a/pipelex/codegen/lock.py
+++ b/pipelex/codegen/lock.py
@@ -8,7 +8,7 @@ the set was generated against, so the offline check can spot a file on disk that
`codegen.lock` is Pipelex-owned and distinct from the standard's `methods.lock` (which pins remote
dependency versions): different owner, location, content, and lifecycle — see
-`docs/specs/pipelex-codegen.md` → "Lock format". It is encoded as human-diffable TOML, artifacts
+the codegen spec → "Lock format". It is encoded as human-diffable TOML, artifacts
sorted by path so version-control diffs stay minimal.
"""
# tomlkit is not fully typed (`tomlkit.dumps`), so its member access reads as unknown here.
diff --git a/pipelex/codegen/stamp.py b/pipelex/codegen/stamp.py
index cb4ee1b02..b865f9c00 100644
--- a/pipelex/codegen/stamp.py
+++ b/pipelex/codegen/stamp.py
@@ -1,7 +1,7 @@
"""Stamp headers: every generated file self-describes so a lone file can testify about itself.
A stamp is a small, machine-parseable comment block prepended to a generated file (see the Stamp
-header format in `docs/specs/pipelex-codegen.md`). It records the source crate fingerprint, the engine
+header format in the codegen spec). It records the source crate fingerprint, the engine
version that produced the file, the projection (`kind` / `target`, plus `pipe_ref` for per-pipe
artifacts), any output-affecting options, and a **content hash of the body below the stamp** — so a
hand edit anywhere under the stamp is detectable without the engine, the network, or the lock.
diff --git a/pipelex/kernel/compose_ops.py b/pipelex/kernel/compose_ops.py
index 28e80623d..c824b8cc7 100644
--- a/pipelex/kernel/compose_ops.py
+++ b/pipelex/kernel/compose_ops.py
@@ -8,8 +8,7 @@ text is pure rendering over the memory it is handed.
Its semantics are `StructuredContentComposer` over a `ConstructBlueprint`, and the blueprint is a
language artifact that `.mthds` parses into — moving both into the kernel would relocate the MTHDS
field-composition model and its error family for a caller shape that has no programmatic use (a caller
-holding real Python would build the object, not describe it in a blueprint). See
-`wip/kernel/deferred-follow-ups.md`.
+holding real Python would build the object, not describe it in a blueprint).
"""
from typing import Any
diff --git a/pipelex/kernel/func_ops.py b/pipelex/kernel/func_ops.py
index 8718fb7d0..97c68c977 100644
--- a/pipelex/kernel/func_ops.py
+++ b/pipelex/kernel/func_ops.py
@@ -13,8 +13,7 @@ the write-back; `run_func` is the in-process composition of the two, and the ent
programmatic caller wants.
One seam is deliberately *not* here: **choosing where the function runs.** Executor selection is
-configured deployment machinery, and its protocol is typed on interpreter models — see
-`wip/kernel/deferred-follow-ups.md`.
+configured deployment machinery, and its protocol is typed on interpreter models.
"""
import asyncio
diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 2e9d9773f..df9ace0e3 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -5,7 +5,6 @@ from typing_extensions import override
from pipelex import log
from pipelex.cogt.content_generation.dry_mock import stamp_mock_main_coordination
-from pipelex.config import get_config
from pipelex.core.memory.absence import AbsenceRecord
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.exceptions import PipeRunError
@@ -34,17 +33,6 @@ if TYPE_CHECKING:
LARGE_BATCH_ADVISORY_THRESHOLD = 100
-def resolve_batch_max_concurrency(max_concurrency_setting: int | str) -> int | None:
- """Translate the ``pipeline_execution_config.max_concurrency`` setting into a ``gather_bounded`` bound.
-
- The config exposes the explicit literal ``"unbounded"``; ``gather_bounded`` takes ``None`` for no
- bound. Any int value is passed through unchanged. Centralizing this guards against passing the
- raw ``"unbounded"`` string into ``gather_bounded``, which would raise ``TypeError`` on its
- ``max_concurrency < 1`` check.
- """
- return None if isinstance(max_concurrency_setting, str) else max_concurrency_setting
-
-
class PipeBatch(PipeController):
type: Literal["PipeBatch"] = "PipeBatch"
@@ -142,13 +130,16 @@ class PipeBatch(PipeController):
batch_output_stuff_code = StuffFactory.make_stuff_code()
item_count = len(input_content.items)
- max_concurrency_setting = get_config().pipelex.pipeline_execution_config.max_concurrency
- max_concurrency = resolve_batch_max_concurrency(max_concurrency_setting)
+ # Read off the payload, never off live config: the bound was frozen into the run params at
+ # submit time precisely so the fan-out shape stays a pure function of the run. See
+ # `PipeRunParams.batch_max_concurrency`.
+ max_concurrency = pipe_run_params.batch_max_concurrency
if item_count > LARGE_BATCH_ADVISORY_THRESHOLD:
log.warning(
f"PipeBatch '{self.code}' is fanning out over {item_count} items. Bounded fan-out "
- f"(max_concurrency={max_concurrency_setting}) is a basic backpressure effort, not durable execution — "
- f"for a workload this size, consider a durable execution backend for rate-limited, resumable runs: {URLs.durable_execution}"
+ f"(max_concurrency={max_concurrency if max_concurrency is not None else 'unbounded'}) is a basic backpressure "
+ f"effort, not durable execution — for a workload this size, consider a durable execution backend for "
+ f"rate-limited, resumable runs: {URLs.durable_execution}"
)
async def _run_branch(item_input_stuff: "Stuff", *, branch_output_item_code: str) -> PipeOutput:
@@ -167,7 +158,10 @@ class PipeBatch(PipeController):
"output_multiplicity": None,
},
)
- return await get_pipe_router().run(
+ # `run_batch_branch`, not `run`: this is the one dispatch in the pipe tree whose
+ # semantics are "a per-item fan-out branch". In-process routers treat it as a plain
+ # run (the protocol's default body); a distributed router may isolate it.
+ return await get_pipe_router().run_batch_branch(
pipe_job=PipeJobFactory.make_pipe_job(
pipe=sub_pipe,
job_metadata=job_metadata,
diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.py
index f63ade5b1..4daa9d796 100644
--- a/pipelex/pipe_machinery/pipe_abstract.py
+++ b/pipelex/pipe_machinery/pipe_abstract.py
@@ -1000,8 +1000,17 @@ class PipeAbstract(ABC, BaseModel):
) -> PipeOutput:
log.verbose(f"Dry run of {self.type}: '{self.code}'")
assert pipe_run_params.run_mode.is_dry, f"Dry run of {self.type} '{self.code}' called with run_mode = {pipe_run_params.run_mode}"
+ # Stamp the running pipe onto the metadata handed down, exactly as `live_run_pipe` does.
+ # Without it a dry run's `job_metadata.pipe_code` stays whatever the caller passed — usually
+ # unset — so everything downstream that identifies a step by it (leaf-activity labelling in a
+ # distributed backend, log correlation) sees an anonymous step in DRY and a named one in LIVE.
+ # Telemetry stays live-only on purpose: `pipe_run_id` and `otel_context` belong to a real run.
+ # `otel_context=None` matches what `live_run_pipe` itself computes in dry mode, and clearing
+ # it explicitly is the point of that parameter being required — inheriting the parent's would
+ # attach a dry step to a live span.
+ child_metadata = job_metadata.copy_with_update(otel_context=None, pipe_code=self.code)
return await self._dry_run_pipe(
- job_metadata=job_metadata,
+ job_metadata=child_metadata,
working_memory=working_memory,
pipe_run_params=pipe_run_params,
output_name=output_name,
diff --git a/pipelex/pipe_run/pipe_router_protocol.py b/pipelex/pipe_run/pipe_router_protocol.py
index 91512feee..33bbe890d 100644
--- a/pipelex/pipe_run/pipe_router_protocol.py
+++ b/pipelex/pipe_run/pipe_router_protocol.py
@@ -78,6 +78,23 @@ class PipeRouterProtocol(Protocol):
return pipe_output
+ async def run_batch_branch(
+ self,
+ pipe_job: PipeJob,
+ ) -> PipeOutput:
+ """Run ``pipe_job`` as one fan-out branch of a ``PipeBatch``.
+
+ This is the ONE dispatch site in the pipe tree that carries "this dispatch is a
+ per-item fan-out branch" as semantics rather than as a data shape: the branch job
+ carries the branch pipe and the per-item memory, which is indistinguishable from any
+ other dispatch. A distributed router MAY use that signal to isolate the branch (own
+ retry, own history partition); every other dispatch it receives runs inline.
+
+ The default body IS the behavior for in-process routers: a branch is just a run.
+ Implementations only override this when isolation is something they can offer.
+ """
+ return await self.run(pipe_job)
+
@abstractmethod
async def _run_pipe_job(
self,
diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.py
index f29c2fc19..a9c227e68 100644
--- a/pipelex/pipe_run/pipe_run_params.py
+++ b/pipelex/pipe_run/pipe_run_params.py
@@ -148,6 +148,17 @@ class PipeRunParams(BaseModel):
# frozen for the same reason as `run_mode`.
is_mock_usage: bool = Field(default=False, frozen=True)
+ # Bounded fan-out for PipeBatch, resolved from `pipeline_execution_config.max_concurrency`
+ # once at construction (`PipeRunParamsFactory.make_run_params`). `None` means unbounded —
+ # `gather_bounded`'s own no-bound sentinel, so the field is passed straight through.
+ #
+ # 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)
+
final_stuff_code: str | None = None
output_multiplicity: VariableMultiplicity | None = None
dynamic_output_concept_ref: str | None = None
diff --git a/pipelex/pipe_run/pipe_run_params_factory.py b/pipelex/pipe_run/pipe_run_params_factory.py
index 7c8efa137..c3a12e0cd 100644
--- a/pipelex/pipe_run/pipe_run_params_factory.py
+++ b/pipelex/pipe_run/pipe_run_params_factory.py
@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Literal
from pipelex.cogt.content_generation.cogt_run_params import check_mock_usage_requires_dry
from pipelex.config import get_config
@@ -8,6 +8,20 @@ from pipelex.runtime_hub import resolve_run_mode_for_boot
from pipelex.system.pipe_run_mode import PipeRunMode
+def resolve_batch_max_concurrency(max_concurrency_setting: int | Literal["unbounded"]) -> int | None:
+ """Translate the ``pipeline_execution_config.max_concurrency`` setting into a ``gather_bounded`` bound.
+
+ The config exposes the explicit literal ``"unbounded"``; ``gather_bounded`` takes ``None`` for no
+ bound. Any int value is passed through unchanged. Centralizing this guards against passing the
+ raw ``"unbounded"`` string into ``gather_bounded``, which would raise ``TypeError`` on its
+ ``max_concurrency < 1`` check.
+
+ Lives next to the factory because the factory is where the setting is read: the resolved bound is
+ frozen into ``PipeRunParams.batch_max_concurrency`` at construction, never re-read at fan-out time.
+ """
+ return None if isinstance(max_concurrency_setting, str) else max_concurrency_setting
+
+
class PipeRunParamsFactory:
@classmethod
def make_run_params(
@@ -21,7 +35,7 @@ class PipeRunParamsFactory:
batch_params: BatchParams | None = None,
params: dict[str, Any] | None = None,
) -> PipeRunParams:
- """Single writer of ``run_mode`` and ``is_mock_usage`` — direct fields on ``PipeRunParams``.
+ """Single writer of ``run_mode``, ``is_mock_usage`` and ``batch_max_concurrency`` — direct fields on ``PipeRunParams``.
The keyless-boot forced-DRY flag (eng review D4) is applied HERE — at the single writer of
those fields — so every pipe-tier execution entry point is covered (``prepare_pipe_job``,
@@ -32,14 +46,19 @@ class PipeRunParamsFactory:
The REQUESTED mode is validated before the forced-DRY coercion, so a contract violation
(``is_mock_usage`` on a LIVE request) fails loud on every boot — the keyless coercion must
not silently turn an illegal request into a legal one.
+
+ ``batch_max_concurrency`` is resolved here for the same single-writer reason and because the
+ read must happen ONCE, at submit time: see the field's docstring on ``PipeRunParams``.
"""
check_mock_usage_requires_dry(run_mode=pipe_run_mode, is_mock_usage=is_mock_usage)
pipe_run_mode = resolve_run_mode_for_boot(requested=pipe_run_mode)
- pipe_stack_limit = pipe_stack_limit or get_config().pipelex.pipe_run_config.pipe_stack_limit
+ config = get_config().pipelex
+ pipe_stack_limit = pipe_stack_limit or config.pipe_run_config.pipe_stack_limit
return PipeRunParams(
run_mode=pipe_run_mode,
is_mock_usage=is_mock_usage,
pipe_stack_limit=pipe_stack_limit,
+ batch_max_concurrency=resolve_batch_max_concurrency(config.pipeline_execution_config.max_concurrency),
output_multiplicity=output_multiplicity,
dynamic_output_concept_ref=dynamic_output_concept_ref,
batch_params=batch_params,
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index 902d43382..3f81620e6 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -299,7 +299,7 @@ class Pipelex(RuntimeBoot):
inference files — backends, routing profiles and the model deck — still resolve through
the layered paths, and the gateway consent/onboarding state is read from the global
config dir outright. So this does not fully isolate a boot from the surrounding
- project. See ``wip/boot-split/config-dir-does-not-scope-inference-paths.md``.
+ project.
config_overrides: Optional dict deep-merged on top of all TOML config layers
as the highest-priority override. Useful for tests that need specific
config without editing TOML files.
diff --git a/pipelex/pipeline/pipe_io_contracts.py b/pipelex/pipeline/pipe_io_contracts.py
index 5cceeded0..c143e94c7 100644
--- a/pipelex/pipeline/pipe_io_contracts.py
+++ b/pipelex/pipeline/pipe_io_contracts.py
@@ -16,8 +16,7 @@ That silent-stale reading used to be the hazard this note warned about: bundle-d
structure classes are registered in the process-global registry during library load and
are never unregistered (the registry has no unregister mechanism), so the classes outlive
the library that defined them. They still do — what changed is that this builder no longer
-reaches them behind the library's back. (Registry teardown hygiene is tracked in the
-workspace-root `wip/library-lifecycle-hygiene.md`.)
+reaches them behind the library's back. (Registry teardown hygiene is tracked separately.)
"""
from enum import StrEnum
diff --git a/pipelex/providers/gateway/gateway_search_worker.py b/pipelex/providers/gateway/gateway_search_worker.py
index 15a9cb4ce..f89ca53ce 100644
--- a/pipelex/providers/gateway/gateway_search_worker.py
+++ b/pipelex/providers/gateway/gateway_search_worker.py
@@ -27,7 +27,7 @@ from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
class GatewaySearchWorker(SearchWorkerAbstract):
- """Search worker that routes through Portkey to the pipelex-relay LinkUp endpoints."""
+ """Search worker that routes through Portkey to the relay's LinkUp endpoints."""
def __init__(
self,
diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.py
index 68bdeeca5..f7fe4ab13 100644
--- a/pipelex/runtime_boot.py
+++ b/pipelex/runtime_boot.py
@@ -389,7 +389,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# while silently never applying the interpreter ones (``PIPE_ROUTER`` / ``PIPE_RUN`` /
# ``PIPE_FUNC_EXECUTOR``, all applied in ``Pipelex.setup``). What closed it is the entry-point
# group split: the layer signal that remedy needed is now carried by the plugin's own
- # declaration. Analysed in ``wip/boot-split/runtime-boot-external-interpreter-orchestrator.md``.
+ # declaration.
requested_boot_orchestrator = get_config().plugins.boot_orchestrator
if requested_boot_orchestrator is not None and requested_boot_orchestrator not in plugin_registrar.registered_plugin_names:
raise UnknownBootOrchestratorError(requested=requested_boot_orchestrator)
@@ -467,8 +467,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# properties, because pinning them requires the path overrides that exist on the *concrete*
# ``ModelManager`` and not on ``ModelManagerAbstract`` — which is what this attribute is
# typed as, and which is a public injection point. Widening that interface is a decision of
- # its own, so the gap is documented rather than half-closed:
- # ``wip/boot-split/config-dir-does-not-scope-inference-paths.md``. The docstrings say exactly
+ # its own, so the gap is documented rather than half-closed. The docstrings say exactly
# this; do not read ``config_dir`` as "only this directory is read" for inference.
self.models_manager.setup(
secrets_provider=secrets_provider,
@@ -665,8 +664,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
reporting buffer unflushed, the previous boot's ``func_registry`` entries carried forward.
Everything that would instead **poison** the next boot moved into the ``finally``, so the two
release paths guarantee the same set. Closing the dangling half means collapsing this path and
- ``_release_after_failed_boot`` into one list —
- ``wip/boot-split/failed-boot-does-not-release-every-resource.md``.
+ ``_release_after_failed_boot`` into one list.
"""
try:
if self.telemetry_manager:
@@ -748,7 +746,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
``setup()`` may not have assigned, which is the reason this path exists at all. Adding any of
them here would widen a second hand-maintained copy of the teardown list that is bound to
drift from the real one. Collapsing the two paths is the right fix and is a lifecycle decision of
- its own — ``wip/boot-split/failed-boot-does-not-release-every-resource.md``.
+ its own.
Without this, the next boot raises "LogConfig is already set" and serves a stale, half-populated
class registry (the ``KajsonManager`` singleton ignores a fresh registry once created).
diff --git a/pipelex/system/pipelex_service/remote_config_cache.py b/pipelex/system/pipelex_service/remote_config_cache.py
index 2278cdd5c..67e5bbf50 100644
--- a/pipelex/system/pipelex_service/remote_config_cache.py
+++ b/pipelex/system/pipelex_service/remote_config_cache.py
@@ -7,7 +7,7 @@ optimisation. Layout::
The on-disk payload is the raw JSON returned by the remote endpoint (not a re-serialised
Pydantic dump), so the cache is stable across minor schema drift. Schema-breaking changes
-require bumping both the remote-config URL version (in ``pipelex-back-office``) and
+require bumping both the remote-config URL version (server-side) and
``CACHE_SCHEMA_VERSION`` here; older caches are then rejected on load and re-primed on the
next successful fetch.
"""
diff --git a/pipelex/tracing/dynamodb_event_log.py b/pipelex/tracing/dynamodb_event_log.py
index 3dcca945a..8c1e50e81 100644
--- a/pipelex/tracing/dynamodb_event_log.py
+++ b/pipelex/tracing/dynamodb_event_log.py
@@ -7,7 +7,7 @@ Stores trace events in a DynamoDB table with the schema:
Legacy emissions write writer_id="primary" so existing rows remain valid.
-Compatible with the pipelex-api-infra TraceEventDynamoDBAdapter schema.
+Compatible with the hosted trace-event DynamoDB adapter schema.
Requires: pip install "pipelex[dynamodb]"
"""
diff --git a/subject_grants.toml b/subject_grants.toml
index cdf84a516..181acbb02 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -3984,10 +3984,6 @@ rationale = "Verb-object: scans the pipe for taint triggers; slot_taints is cont
param = "item_input_stuff"
rationale = "Verb-object: runs the branch for the item stuff; invoked positionally via functools.partial."
-["pipelex/pipe_controllers/batch/pipe_batch.py::resolve_batch_max_concurrency"]
-param = "max_concurrency_setting"
-rationale = "Verb-object: resolves the config setting value; single operand, callers pass a labelled config read."
-
["pipelex/pipe_controllers/condition/special_outcome.py::SpecialOutcome.is_continue"]
param = "outcome"
rationale = "Predicate on the outcome string; single operand."
@@ -4312,6 +4308,10 @@ rationale = "Protocol hook: runs the pipe job; single operand."
param = "pipe_job"
rationale = "Protocol method: runs the pipe job; single operand across implementations."
+["pipelex/pipe_run/pipe_router_protocol.py::PipeRouterProtocol.run_batch_branch"]
+param = "pipe_job"
+rationale = "Protocol hook: the pipe job being dispatched as a fan-out branch; single operand."
+
["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.copy_by_injecting_multiplicity"]
param = "pipe_run_params"
rationale = "Verb-object: copies the given run params; multiplicity stays keyword."
@@ -4328,6 +4328,10 @@ rationale = "Verb-object: pushes the pipe named by the code; single operand."
param = "pipe_code"
rationale = "Verb-object: pushes the pipe named by the code; single operand."
+["pipelex/pipe_run/pipe_run_params_factory.py::resolve_batch_max_concurrency"]
+param = "max_concurrency_setting"
+rationale = "Verb-object: resolves the config setting value; single operand, callers pass a labelled config read."
+
["pipelex/pipe_run/pipe_run_protocol.py::PipeRunProtocol.run"]
param = "pipe_job"
rationale = "Protocol method: runs the pipe job; single operand across implementations."
diff --git a/tests/e2e/pipelex/cv_batch_screening/library_crate/cv_batch_screening.mthds b/tests/e2e/pipelex/cv_batch_screening/library_crate/cv_batch_screening.mthds
index 839eb434f..44b3f468d 100644
--- a/tests/e2e/pipelex/cv_batch_screening/library_crate/cv_batch_screening.mthds
+++ b/tests/e2e/pipelex/cv_batch_screening/library_crate/cv_batch_screening.mthds
@@ -1,5 +1,5 @@
domain = "cv_batch_screening"
-description = "Analyzing CV and job offer compatibility — sourced from pipelex-demos example 21, used as a deeply-nested controller test (PipeSequence -> PipeSequence -> PipeBatch + PipeExtract + PipeLLM)."
+description = "Analyzing CV and job offer compatibility — used as a deeply-nested controller test (PipeSequence -> PipeSequence -> PipeBatch + PipeExtract + PipeLLM)."
system_prompt = "None"
main_pipe = "batch_analyze_cvs_for_job_offer"
diff --git a/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py b/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py
index 300f58028..f00a39a68 100644
--- a/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py
+++ b/tests/e2e/pipelex/cv_batch_screening/test_cv_batch_screening.py
@@ -1,9 +1,8 @@
"""Direct-mode e2e test for the CV batch screening pipeline.
-Runs the pipelex-demos example 21 pipeline through ``PipelexMTHDSProtocol`` without any
-Temporal layer. The same bundle is also exercised by the temporal in-process test in the
-``pipelex-temporal`` package and by the ``/temporal-e2e-validate`` skill (distributed
-3-process validation). Each repo keeps its own copy of the crate (see ``test_data.py``).
+Runs the CV batch screening pipeline through ``PipelexMTHDSProtocol`` without any
+Temporal layer. The same bundle is also exercised by the in-process Temporal test in
+our Temporal plugin and by our distributed 3-process validation harness. Each repo keeps its own copy of the crate (see ``test_data.py``).
"""
from pathlib import Path
diff --git a/tests/e2e/pipelex/cv_batch_screening/test_data.py b/tests/e2e/pipelex/cv_batch_screening/test_data.py
index 4d6c49fdc..fba9378c3 100644
--- a/tests/e2e/pipelex/cv_batch_screening/test_data.py
+++ b/tests/e2e/pipelex/cv_batch_screening/test_data.py
@@ -1,14 +1,14 @@
from typing import ClassVar
# The CV batch screening bundle is shared test data: the direct-mode e2e here, the
-# Temporal integration suite (in pipelex-temporal), and the /temporal-e2e-validate skill
-# all exercise the same .mthds. Each repo keeps its own copy of the crate so neither
+# Temporal integration suite (in our Temporal plugin), and our distributed validation
+# harness all exercise the same .mthds. Each repo keeps its own copy of the crate so neither
# depends on the other's test tree.
_CRATE_DIR: str = "tests/e2e/pipelex/cv_batch_screening/library_crate"
class CvBatchScreeningTemporalTestData:
- """Nested-controller CV batch screening pipeline sourced from pipelex-demos example 21.
+ """Nested-controller CV batch screening pipeline.
Exercises PipeSequence -> PipeSequence -> PipeBatch -> PipeSequence with PipeExtract +
PipeLLM operators in both the inner job-offer branch and the per-CV batch branch.
diff --git a/tests/integration/pipelex/codegen/test_emitted_python_typechecks.py b/tests/integration/pipelex/codegen/test_emitted_python_typechecks.py
index b3de11940..2ec571cc7 100644
--- a/tests/integration/pipelex/codegen/test_emitted_python_typechecks.py
+++ b/tests/integration/pipelex/codegen/test_emitted_python_typechecks.py
@@ -1,8 +1,8 @@
"""The D7 quality gate: emitted Python passes strict pyright and execs into real classes.
-Per decision D7 (see `_codegen/TODOS.md`), the pyright gate on emitted Python lives in pipelex (the
-toolchain is already present); the `tsc --strict` gate on emitted TypeScript lives in the
-`conformance/` cross-repo harness. This module projects a rich crate — one exercising every
+Per decision D7, the pyright gate on emitted Python lives in pipelex (the toolchain is already
+present); the `tsc --strict` gate on emitted TypeScript lives in our cross-repo spec suite. This
+module projects a rich crate — one exercising every
`ResolvedType` kind, a literal-with-default, an optional, a native reference, and a refines-native
concept — into `python-structures` and `python-pydantic`, then (1) runs strict pyright over the
generated files and asserts zero errors, and (2) imports them so the classes are actually built.
diff --git a/tests/integration/pipelex/error_handling/test_data.py b/tests/integration/pipelex/error_handling/test_data.py
index b3ecf356f..a08e42e72 100644
--- a/tests/integration/pipelex/error_handling/test_data.py
+++ b/tests/integration/pipelex/error_handling/test_data.py
@@ -2,9 +2,9 @@
The parity-invariant fixtures (the injected failure + its expected classification) and the error
factories are the single shared source of truth in ``pipelex.test_extras.error_report_parity`` —
-shipped in the open-core wheel so this repo's local arm and the closed ``pipelex-temporal``
-plugin's Temporal arm import the *same* data and cannot silently diverge. Only the ``.mthds``
-bundle each repo ships is genuinely per-repo, so that is all these subclasses add.
+shipped in the open-core wheel so this repo's local arm and our Temporal plugin's distributed
+arm import the *same* data and cannot silently diverge. Only the ``.mthds`` bundle each repo
+ships is genuinely per-repo, so that is all these subclasses add.
"""
from typing import ClassVar
diff --git a/tests/integration/pipelex/kernel/test_usage_parity.py b/tests/integration/pipelex/kernel/test_usage_parity.py
index d28e86b59..3ef1bb02e 100644
--- a/tests/integration/pipelex/kernel/test_usage_parity.py
+++ b/tests/integration/pipelex/kernel/test_usage_parity.py
@@ -12,13 +12,12 @@ So this measures rather than asserts. Both sides run the same step (one LLM text
shape ``/execute`` returns on ``pipe_output.tokens_usages`` and durable runs persist as
``tokens_usages.json`` — are then compared field by field.
-``pipe_code`` is the one field that would legitimately differ — a kernel call has no pipe to name —
-and this measurement cannot see it: the interpreter stamps it in ``live_run_pipe``, which a DRY run
-never reaches, so both sides report ``None``. That is asserted rather than excluded quietly, because
-it is the honest scope of what the comparison proves, and it is a pre-existing interpreter gap in its
-own right (a ``--dry-run --mock-usage`` cost report has no pipe attribution — see KF-13 in
-``wip/kernel/deferred-follow-ups.md``). Timestamps differ because the two runs happen at different
-times.
+``pipe_code`` is the one field that legitimately differs: the interpreter names the pipe it ran, and a
+kernel call has no pipe to name. Both halves are asserted rather than excluded quietly, because that
+difference is the honest scope of what the comparison proves. It only reads that way because
+``dry_run_pipe`` stamps the running pipe onto the metadata it hands down — until it did, the field was
+``None`` on both sides and this measurement could not observe it at all (KF-13). Timestamps differ
+because the two runs happen at different times.
Transport ownership is visible in the setup itself. The interpreter half needs NDJSON tracing enabled
because its run machinery builds the event log off the config; the kernel half hands its own
@@ -60,15 +59,16 @@ output = "Text"
prompt = "{_USER_PROMPT}"
"""
-#: The record fields that carry the run's identity or its wall-clock, which two separate runs cannot
-#: share. Everything else is the shape parity is measured on.
-_RUN_SPECIFIC_FIELDS = ("pipe_code", "started_at", "completed_at")
+#: The fields two separate runs cannot share — the wall-clock ones — plus ``pipe_code``, which the two
+#: callers fill differently by design rather than by accident. Everything else is the shape parity is
+#: measured on, and each excluded field is asserted on its own below.
+_UNCOMPARABLE_FIELDS = ("pipe_code", "started_at", "completed_at")
@pytest.mark.asyncio(loop_scope="class")
class TestKernelUsageParity:
def _comparable(self, record: TokensUsageRecord) -> dict[str, Any]:
- return {key: value for key, value in record.model_dump().items() if key not in _RUN_SPECIFIC_FIELDS}
+ return {key: value for key, value in record.model_dump().items() if key not in _UNCOMPARABLE_FIELDS}
def _records(self, tokens_usages: list[AnyTokensUsage]) -> list[TokensUsageRecord]:
return [make_tokens_usage_record(tokens_usage) for tokens_usage in tokens_usages]
@@ -138,8 +138,8 @@ class TestKernelUsageParity:
assert record.inference_model_name == MOCK_USAGE_MODEL_NAME
assert sum(record.nb_tokens_by_category.values()) > 0
- # The scope of what was measured, pinned rather than left implicit: the field a kernel run
- # could never fill is also unfilled on the interpreter's DRY path, so parity here does not
- # cover it (KF-13).
- assert interpreter_records[0].pipe_code is None
+ # The scope of what was measured, pinned rather than left implicit: the one field excluded
+ # from the comparison above is excluded because the two callers fill it differently — the
+ # interpreter names the pipe it ran, a kernel call has no pipe to name.
+ assert interpreter_records[0].pipe_code == _PIPE_CODE
assert kernel_records[0].pipe_code is None
diff --git a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_branch_dispatch.py b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_branch_dispatch.py
new file mode 100644
index 000000000..9ba0ce58a
--- /dev/null
+++ b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_branch_dispatch.py
@@ -0,0 +1,172 @@
+"""PipeBatch's branch dispatch: it goes through the `run_batch_branch` hook, and its fan-out bound
+comes off the payload rather than live config.
+
+Both are the core half of the flat-topology seam. The hook is the ONLY signal a distributed router
+gets that a dispatch is a per-item fan-out branch (the branch job is otherwise indistinguishable
+from a sequence step); the frozen bound is what keeps the fan-out grouping a pure function of the
+run, so a config redeploy cannot reshape an in-flight batch.
+"""
+
+from collections.abc import Awaitable, Callable, Sequence
+
+import pytest
+from typing_extensions import override
+
+from pipelex.config import get_config
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.interpreter_hub import get_pipe_library, scoped_pipe_router
+from pipelex.pipe_controllers.batch import pipe_batch as pipe_batch_module
+from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
+from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
+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_job import PipeJob
+from pipelex.pipe_run.pipe_router import PipeRouter
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.system.registries.func_registry import func_registry
+
+_DOMAIN_CODE = "test_batch_branch_dispatch"
+
+
+def batch_branch_dispatch_shout_item(working_memory: WorkingMemory) -> TextContent:
+ return TextContent(text=working_memory.get_stuff_as_str(name="item").upper())
+
+
+class _HookCountingRouter(PipeRouter):
+ """Real in-process router that records which dispatch door each job came through."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.branch_dispatched_pipe_codes: list[str] = []
+ self.plain_run_pipe_codes: list[str] = []
+
+ @override
+ async def run(self, pipe_job: PipeJob) -> PipeOutput:
+ self.plain_run_pipe_codes.append(pipe_job.pipe.code)
+ return await super().run(pipe_job)
+
+ @override
+ async def run_batch_branch(self, pipe_job: PipeJob) -> PipeOutput:
+ self.branch_dispatched_pipe_codes.append(pipe_job.pipe.code)
+ return await super().run_batch_branch(pipe_job)
+
+
+def _build_batch() -> PipeBatch:
+ """A batch over Text items whose branch just uppercases each item."""
+ shout_pipe = PipeFactory[PipeFunc].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="branch_dispatch_shout",
+ blueprint=PipeFuncBlueprint(
+ description="Uppercase the batch item",
+ inputs={"item": "Text"},
+ output="Text",
+ function_name="batch_branch_dispatch_shout_item",
+ ),
+ )
+ pipe_library = get_pipe_library()
+ pipe_library.add_new_pipe(pipe=shout_pipe)
+
+ batch = PipeFactory[PipeBatch].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="branch_dispatch_batch",
+ blueprint=PipeBatchBlueprint(
+ description="Batch the shout over the items",
+ branch_pipe_code="branch_dispatch_shout",
+ output="Text",
+ input_list_name="items",
+ input_item_name="item",
+ inputs={"items": "Text"},
+ ),
+ )
+ pipe_library.add_new_pipe(pipe=batch)
+ return batch
+
+
+def _make_items_memory(batch: PipeBatch, texts: list[str]):
+ items_stuff = StuffFactory.make_stuff(
+ concept=batch.inputs.get_required_stuff_spec("items").concept,
+ content=ListContent[TextContent](items=[TextContent(text=text) for text in texts]),
+ name="items",
+ )
+ return WorkingMemoryFactory.make_from_single_stuff(items_stuff)
+
+
[email protected](loop_scope="class")
+class TestPipeBatchBranchDispatch:
+ @classmethod
+ def setup_class(cls):
+ func_registry.register_function(batch_branch_dispatch_shout_item)
+
+ @classmethod
+ def teardown_class(cls):
+ if func_registry.has_function(batch_branch_dispatch_shout_item.__name__):
+ func_registry.unregister_function_by_name(batch_branch_dispatch_shout_item.__name__)
+
+ async def test_branches_dispatch_through_the_hook(self, job_metadata: JobMetadata, load_empty_library: Callable[[], str]):
+ """One `run_batch_branch` call per item, and the batch itself never enters through the hook."""
+ load_empty_library()
+ batch = _build_batch()
+ router = _HookCountingRouter()
+
+ with scoped_pipe_router(router):
+ await batch.run_pipe(
+ job_metadata=job_metadata,
+ working_memory=_make_items_memory(batch, ["alpha", "beta", "gamma"]),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE),
+ )
+
+ assert router.branch_dispatched_pipe_codes == ["branch_dispatch_shout"] * 3
+ assert "branch_dispatch_batch" not in router.branch_dispatched_pipe_codes
+
+ async def test_fan_out_bound_comes_off_the_payload_not_live_config(
+ self,
+ job_metadata: JobMetadata,
+ load_empty_library: Callable[[], str],
+ monkeypatch: pytest.MonkeyPatch,
+ ):
+ """Params built under `max_concurrency = 2` keep that bound after the config flips to 5.
+
+ This is the replay hazard the freeze exists for: the bound is `gather_bounded`'s chunk size,
+ so a live read here would let a mid-run worker redeploy regroup the branch dispatches.
+ """
+ load_empty_library()
+ batch = _build_batch()
+
+ captured_bounds: list[int | None] = []
+ real_gather_bounded = pipe_batch_module.gather_bounded
+
+ async def _spying_gather_bounded(
+ task_factories: "Sequence[Callable[[], Awaitable[PipeOutput]]]",
+ *,
+ max_concurrency: int | None,
+ ) -> list[PipeOutput]:
+ captured_bounds.append(max_concurrency)
+ return await real_gather_bounded(task_factories, max_concurrency=max_concurrency)
+
+ monkeypatch.setattr(pipe_batch_module, "gather_bounded", _spying_gather_bounded)
+
+ execution_config = get_config().pipelex.pipeline_execution_config
+ original_setting = execution_config.max_concurrency
+ try:
+ execution_config.max_concurrency = 2
+ run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE)
+ execution_config.max_concurrency = 5
+
+ with scoped_pipe_router(_HookCountingRouter()):
+ await batch.run_pipe(
+ job_metadata=job_metadata,
+ working_memory=_make_items_memory(batch, ["alpha", "beta", "gamma"]),
+ pipe_run_params=run_params,
+ )
+ finally:
+ execution_config.max_concurrency = original_setting
+
+ assert captured_bounds == [2]
diff --git a/tests/unit/pipelex/cli/test_codegen_cli.py b/tests/unit/pipelex/cli/test_codegen_cli.py
index d1d4e1d02..4fa08a12b 100644
--- a/tests/unit/pipelex/cli/test_codegen_cli.py
+++ b/tests/unit/pipelex/cli/test_codegen_cli.py
@@ -3,7 +3,7 @@
Boot/teardown and the crate loader are mocked out so no real Pipelex is made; the emitter and the
input renderer are stubbed so these tests pin the CLI wiring (targets, output paths, main_pipe
defaulting, and the resolve-verdict exit codes), not the projection engines (covered by their own
-unit tests). End-to-end behavior against the binary is pinned by the conformance suite.
+unit tests). End-to-end behavior against the binary is pinned by our cross-repo spec suite.
"""
from __future__ import annotations
diff --git a/tests/unit/pipelex/cli/test_mock_usage_cli_guard.py b/tests/unit/pipelex/cli/test_mock_usage_cli_guard.py
index 03d3f0ac6..ff40a5105 100644
--- a/tests/unit/pipelex/cli/test_mock_usage_cli_guard.py
+++ b/tests/unit/pipelex/cli/test_mock_usage_cli_guard.py
@@ -1,7 +1,7 @@
"""Unit tests for the hidden ``--mock-usage`` CLI surface on the run subcommands.
Two cheap, no-boot checks: every run subcommand declares the option (hidden — for the
-``temporal-e2e-validate`` Mode-2 scripts, not for ``--help``), and each rejects ``--mock-usage``
+distributed-execution validation scripts, not for ``--help``), and each rejects ``--mock-usage``
without ``--dry-run`` (it is a sub-flag of the dry run). The guard runs at the top of each command,
before any filesystem access or Pipelex boot, so calling the command function directly is enough.
"""
diff --git a/tests/unit/pipelex/cli/test_resolve_exit_codes.py b/tests/unit/pipelex/cli/test_resolve_exit_codes.py
index fef030fcc..aeb8c0d64 100644
--- a/tests/unit/pipelex/cli/test_resolve_exit_codes.py
+++ b/tests/unit/pipelex/cli/test_resolve_exit_codes.py
@@ -3,7 +3,7 @@
Policy: exit 0 = resolved (crate emitted); exit 1 = a produced NEGATIVE VERDICT (the library is
invalid, so no crate can be produced); exit 2 = NO VERDICT (empty closure, file-not-found). The
verdict cases mock the resolve internals — boot/teardown are neutralized so no real Pipelex is made.
-The real end-to-end exit codes against the binary are pinned by the conformance suite.
+The real end-to-end exit codes against the binary are pinned by our cross-repo spec suite.
"""
from __future__ import annotations
diff --git a/tests/unit/pipelex/cli/test_show_cmd.py b/tests/unit/pipelex/cli/test_show_cmd.py
index ab8069e49..7cfb09c56 100644
--- a/tests/unit/pipelex/cli/test_show_cmd.py
+++ b/tests/unit/pipelex/cli/test_show_cmd.py
@@ -1,7 +1,7 @@
"""Unit tests for the `pipelex show` report logic (pipelex/cli/commands/show_cmd.py).
Covers the do_* functions directly with mocked hub getters — the Typer wrappers
-(arg parsing, --help) are owned by the conformance suite.
+(arg parsing, --help) are owned by our cross-repo spec suite.
"""
from __future__ import annotations
diff --git a/tests/unit/pipelex/cli/test_validate_exit_codes.py b/tests/unit/pipelex/cli/test_validate_exit_codes.py
index 30356a7e4..d6159f9f4 100644
--- a/tests/unit/pipelex/cli/test_validate_exit_codes.py
+++ b/tests/unit/pipelex/cli/test_validate_exit_codes.py
@@ -2,14 +2,14 @@
Policy: exit 0 = valid; exit 1 = a produced NEGATIVE VERDICT (invalid bundle, or
valid-but-not-runnable without ``--allow-signatures``); exit 2 = NO VERDICT (bad
-args, unresolvable target, file-not-found, unexpected). See
-``docs/specs/pipelex-validation-api.md`` (CLI exit-code policy) and
-``docs/specs/pipelex-mthds-protocol.md`` (Agent-CLI validate envelope).
+args, unresolvable target, file-not-found, unexpected). See the
+validation-API spec (CLI exit-code policy) and the MTHDS protocol spec
+(Agent-CLI validate envelope).
The pre-boot argument/target-resolution cases are pure (they raise before any
Pipelex boot); the negative-verdict / no-verdict / signature-gate cases mock the
validate core (mirroring ``test_agent_validate_cmd.py``). The real end-to-end
-exit codes against the binary are pinned by the conformance suite.
+exit codes against the binary are pinned by our cross-repo spec suite.
"""
from __future__ import annotations
diff --git a/tests/unit/pipelex/codegen/test_naming.py b/tests/unit/pipelex/codegen/test_naming.py
index ef36f023f..3b0a43178 100644
--- a/tests/unit/pipelex/codegen/test_naming.py
+++ b/tests/unit/pipelex/codegen/test_naming.py
@@ -26,7 +26,7 @@ def _resolved_concept(
class TestNaming:
- """Unit tests for the shared name-derivation rules (see docs/specs/pipelex-codegen.md)."""
+ """Unit tests for the shared name-derivation rules (see the codegen spec)."""
def test_snake_to_pascal(self):
assert snake_to_pascal("value") == "Value"
diff --git a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py b/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
index 15e072e1d..24e8fffec 100644
--- a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
+++ b/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
@@ -8,7 +8,7 @@ from pipelex.libraries.library_crate import LibraryCrate
class TestTsZodEmitter:
"""Unit tests for the ts-zod pure types-file emitter.
- The `tsc --strict` compile gate on emitted TS lives in the `conformance/` cross-repo harness (D7);
+ The `tsc --strict` compile gate on emitted TS lives in our cross-repo spec suite (D7);
here we assert the structural contract of the pure types file.
"""
diff --git a/tests/unit/pipelex/cogt/img_gen/test_img_gen_worker_factory.py b/tests/unit/pipelex/cogt/img_gen/test_img_gen_worker_factory.py
index 6ee3fac1a..4329bd18d 100644
--- a/tests/unit/pipelex/cogt/img_gen/test_img_gen_worker_factory.py
+++ b/tests/unit/pipelex/cogt/img_gen/test_img_gen_worker_factory.py
@@ -41,7 +41,7 @@ def build_builtin_inference_backend_registry() -> InferenceBackendRegistry:
plugin closures through the real registry lookup.
"""
# No builtin's register() reads config: Temporal — the only plugin that did, via
- # ``temporal.is_enabled`` — now ships as the external pipelex-temporal dist. A bare
+ # ``temporal.is_enabled`` — now ships as our external Temporal plugin. A bare
# stub config suffices.
stub_config = cast("PipelexConfig", SimpleNamespace())
registrar = PluginRegistrar(config=stub_config)
diff --git a/tests/unit/pipelex/cogt/llm/test_llm_worker_factory.py b/tests/unit/pipelex/cogt/llm/test_llm_worker_factory.py
index 8572970bd..e21dae6f1 100644
--- a/tests/unit/pipelex/cogt/llm/test_llm_worker_factory.py
+++ b/tests/unit/pipelex/cogt/llm/test_llm_worker_factory.py
@@ -44,7 +44,7 @@ def build_builtin_inference_backend_registry() -> InferenceBackendRegistry:
plugin closures through the real registry lookup.
"""
# No builtin's register() reads config: Temporal — the only plugin that did, via
- # ``temporal.is_enabled`` — now ships as the external pipelex-temporal dist. A bare
+ # ``temporal.is_enabled`` — now ships as our external Temporal plugin. A bare
# stub config suffices.
stub_config = cast("PipelexConfig", SimpleNamespace())
registrar = PluginRegistrar(config=stub_config)
diff --git a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py
index 78947be62..b33847de9 100644
--- a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py
+++ b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py
@@ -44,8 +44,7 @@ to defer the external-interpreter-orchestrator half-application hole to "the fir
kernel-only boot", which is this test. That hole is now closed, and not by this test: the plugin
entry-point group split scopes a kernel-only boot's discovery to `KERNEL_ENTRY_POINT_GROUPS`, so an
interpreter-group orchestrator is never registered and the existing gate rejects its name loudly.
-Neither remedy the analysis proposed was built. Recorded in
-`wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`.
+Neither remedy the earlier analysis proposed was built.
"""
import subprocess # noqa: S404
diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py
deleted file mode 100644
index 069169fc7..000000000
--- a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_concurrency.py
+++ /dev/null
@@ -1,26 +0,0 @@
-import pytest
-
-from pipelex.pipe_controllers.batch.pipe_batch import resolve_batch_max_concurrency
-
-
-class TestResolveBatchMaxConcurrency:
- @pytest.mark.parametrize(
- ("max_concurrency_setting", "expected_bound"),
- [
- ("unbounded", None),
- (1, 1),
- (8, 8),
- (100, 100),
- ],
- )
- def test_setting_translates_to_gather_bounded_argument(
- self,
- max_concurrency_setting: int | str,
- expected_bound: int | None,
- ) -> None:
- """The literal "unbounded" config maps to None (gather_bounded's no-bound sentinel); an int passes through.
-
- Guards the PipeBatch fan-out wiring against regressing to passing the raw "unbounded"
- string straight into gather_bounded, which would raise TypeError on its `max_concurrency < 1` check.
- """
- assert resolve_batch_max_concurrency(max_concurrency_setting) == expected_bound
diff --git a/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py b/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py
new file mode 100644
index 000000000..3ba647611
--- /dev/null
+++ b/tests/unit/pipelex/pipe_run/test_batch_max_concurrency.py
@@ -0,0 +1,60 @@
+"""`batch_max_concurrency`: 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.)
+"""
+
+from typing import Literal
+
+import pytest
+
+from pipelex.config import get_config
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory, resolve_batch_max_concurrency
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class TestBatchMaxConcurrency:
+ @pytest.mark.parametrize(
+ ("max_concurrency_setting", "expected_bound"),
+ [
+ ("unbounded", None),
+ (1, 1),
+ (8, 8),
+ (100, 100),
+ ],
+ )
+ def test_setting_translates_to_gather_bounded_argument(
+ self,
+ max_concurrency_setting: int | Literal["unbounded"],
+ expected_bound: int | None,
+ ) -> None:
+ """The literal "unbounded" config maps to None (gather_bounded's no-bound sentinel); an int passes through.
+
+ Guards the PipeBatch fan-out wiring against regressing to passing the raw "unbounded"
+ string straight into gather_bounded, which would raise TypeError on its `max_concurrency < 1` check.
+ """
+ assert resolve_batch_max_concurrency(max_concurrency_setting) == expected_bound
+
+ 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)
+
+ run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY)
+
+ assert run_params.batch_max_concurrency == expected
+
+ def test_later_config_change_does_not_reach_existing_run_params(self) -> None:
+ """The whole point: params built before a config edit keep the bound they were born with."""
+ execution_config = get_config().pipelex.pipeline_execution_config
+ original_setting = execution_config.max_concurrency
+ try:
+ execution_config.max_concurrency = 3
+ run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY)
+ assert run_params.batch_max_concurrency == 3
+
+ execution_config.max_concurrency = 7
+ assert run_params.batch_max_concurrency == 3
+ finally:
+ execution_config.max_concurrency = original_setting
diff --git a/tests/unit/pipelex/pipe_run/test_run_batch_branch_hook.py b/tests/unit/pipelex/pipe_run/test_run_batch_branch_hook.py
new file mode 100644
index 000000000..2424a8e55
--- /dev/null
+++ b/tests/unit/pipelex/pipe_run/test_run_batch_branch_hook.py
@@ -0,0 +1,94 @@
+"""The `run_batch_branch` router hook: its default body IS the behavior for in-process routers.
+
+`PipeBatch` marks its per-item fan-out dispatches by calling this hook instead of `run`. Every
+router that has no isolation to offer inherits the concrete default, which delegates straight to
+`run` — so adding the hook changed no in-process behavior. These tests pin that delegation, because
+a distributed router's override is only correct if the un-overridden case stays a plain run.
+"""
+
+from typing import TYPE_CHECKING, cast
+
+import pytest
+from typing_extensions import override
+
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.observer.observer_protocol import ObserverNoOp
+from pipelex.pipe_run.pipe_job import PipeJob
+from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+if TYPE_CHECKING:
+ from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
+
+
+class _StubPipe:
+ """Minimal pipe stand-in: the router only reads `.code` off it."""
+
+ code = "stub_pipe"
+
+
+class _RecordingRouter(PipeRouterProtocol):
+ """Router that records the jobs reaching `_run_pipe_job` and never touches a real pipe."""
+
+ def __init__(self) -> None:
+ self.observer = ObserverNoOp()
+ self.dispatched_jobs: list[PipeJob] = []
+
+ @override
+ async def _run_pipe_job(self, pipe_job: PipeJob) -> PipeOutput:
+ self.dispatched_jobs.append(pipe_job)
+ return PipeOutput(
+ working_memory=WorkingMemoryFactory.make_empty(),
+ pipeline_run_id=pipe_job.job_metadata.pipeline_run_id,
+ )
+
+
+def _make_pipe_job() -> PipeJob:
+ return PipeJob.model_construct(
+ pipe=cast("PipeAbstract", _StubPipe()),
+ working_memory=None,
+ working_memory_raw=None,
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE),
+ job_metadata=JobMetadata(user_id="test-user", pipeline_run_id="test-run"),
+ output_name=None,
+ library_crate=None,
+ )
+
+
[email protected](loop_scope="class")
+class TestRunBatchBranchHook:
+ async def test_default_delegates_to_run(self) -> None:
+ """The un-overridden hook reaches `_run_pipe_job` with the very job it was handed."""
+ router = _RecordingRouter()
+ pipe_job = _make_pipe_job()
+
+ await router.run_batch_branch(pipe_job)
+
+ assert router.dispatched_jobs == [pipe_job]
+
+ async def test_default_runs_the_observer_hooks_like_run(self) -> None:
+ """Delegation goes through `run`, not around it — so observers still see the branch.
+
+ Pins the "delegate to `run`" contract rather than "delegate to `_run_pipe_job`": a hook that
+ short-circuited to the private dispatch would silently drop every batch branch out of the
+ observer stream.
+ """
+ observed: list[str] = []
+
+ class _ObservingRouter(_RecordingRouter):
+ @override
+ async def _before_run(self, pipe_job: PipeJob) -> None:
+ observed.append("before")
+
+ @override
+ async def _after_successful_run(self, pipe_job: PipeJob, *, pipe_output: PipeOutput) -> None:
+ observed.append("after")
+
+ router = _ObservingRouter()
+
+ await router.run_batch_branch(_make_pipe_job())
+
+ assert observed == ["before", "after"]
diff --git a/tests/unit/pipelex/plugins/test_inference_backend_coverage.py b/tests/unit/pipelex/plugins/test_inference_backend_coverage.py
index 2c30c39de..70c45f853 100644
--- a/tests/unit/pipelex/plugins/test_inference_backend_coverage.py
+++ b/tests/unit/pipelex/plugins/test_inference_backend_coverage.py
@@ -21,7 +21,7 @@ if TYPE_CHECKING:
def _build_registry() -> InferenceBackendRegistry:
# No builtin's register() reads config: Temporal — the only plugin that did, via
- # ``temporal.is_enabled`` — now ships as the external pipelex-temporal dist. A bare
+ # ``temporal.is_enabled`` — now ships as our external Temporal plugin. A bare
# stub config suffices.
stub_config = cast("PipelexConfig", SimpleNamespace())
registrar = PluginRegistrar(config=stub_config)
diff --git a/tests/unit/pipelex/plugins/test_model_lister_coverage.py b/tests/unit/pipelex/plugins/test_model_lister_coverage.py
index fdd4aad23..a1ca22e98 100644
--- a/tests/unit/pipelex/plugins/test_model_lister_coverage.py
+++ b/tests/unit/pipelex/plugins/test_model_lister_coverage.py
@@ -21,7 +21,7 @@ if TYPE_CHECKING:
def _build_registry() -> ModelListerRegistry:
# No builtin's register() reads config: Temporal — the only plugin that did, via
- # ``temporal.is_enabled`` — now ships as the external pipelex-temporal dist. A bare
+ # ``temporal.is_enabled`` — now ships as our external Temporal plugin. A bare
# stub config suffices.
stub_config = cast("PipelexConfig", SimpleNamespace())
registrar = PluginRegistrar(config=stub_config)
diff --git a/tests/unit/pipelex/plugins/test_plugin_discovery.py b/tests/unit/pipelex/plugins/test_plugin_discovery.py
index 370b6b227..305637b8a 100644
--- a/tests/unit/pipelex/plugins/test_plugin_discovery.py
+++ b/tests/unit/pipelex/plugins/test_plugin_discovery.py
@@ -51,7 +51,7 @@ def _noop_make_worker(**_kwargs: object) -> InferenceWorkerAbstract:
def _fake_config(disabled: list[str]) -> PipelexConfig:
# Discovery reads ``config.plugins.disabled`` to apply the denylist. No builtin's
# register() reads config: Temporal — the only plugin that did, via ``temporal.is_enabled``
- # — now ships as the external pipelex-temporal dist.
+ # — now ships as our external Temporal plugin.
return cast("PipelexConfig", SimpleNamespace(plugins=SimpleNamespace(disabled=disabled)))
diff --git a/tests/unit/pipelex/test_runtime_boot_config_dir.py b/tests/unit/pipelex/test_runtime_boot_config_dir.py
index b1f82dd15..559edfb44 100644
--- a/tests/unit/pipelex/test_runtime_boot_config_dir.py
+++ b/tests/unit/pipelex/test_runtime_boot_config_dir.py
@@ -11,7 +11,7 @@ two apart without writing a whole valid config tree.
Scope note: `config_dir` scopes the main TOML load only — the inference file paths still resolve
through the layered `config_manager.*` properties, because pinning them needs overrides that live on
the concrete `ModelManager` rather than on the `ModelManagerAbstract` this boot is typed against. That
-gap is deliberate and documented (`wip/boot-split/config-dir-does-not-scope-inference-paths.md`), which is
+gap is deliberate and documented in the boot docstrings, which is
why this module asserts the main-config leaf and nothing about backends or decks.
"""
diff --git a/wip/autofix/README.md b/wip/autofix/README.md
index 480c91cc6..b67887d61 100644
--- a/wip/autofix/README.md
+++ b/wip/autofix/README.md
@@ -7,10 +7,10 @@ Deterministic auto-fixing of `.mthds` validation errors — fixes attached to va
| [master-plan.md](master-plan.md) | Executive step ladder: spike → wave 1 → protocol/API/MCP/editor waves | **CURRENT — steps 1–5 DONE (steps 3+4 merged as PR #1035; step 5 on `feature/Autofix-step5`, PR-ready); step 6 (release train) next** |
| [suggested-fixes-design.md](suggested-fixes-design.md) | The live design: architecture, fix rules, phases | **CURRENT — steps 1 + 2 DONE; per-checkpoint findings + the step-2 abstraction verdict recorded inside** |
| [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md) | Detailed design + working plan for step 5 (`pipelex fix bundle` + the `💡 Suggested fix:` line in `pipelex validate`) | **DONE — all phases incl. `--diff`; CHECKPOINT B cleared (5 bugs fixed, 5 deferred); PR-ready** |
-| [validation-error-reporting-plan.md](validation-error-reporting-plan.md) | Follow-on quality track (dogfooded on `pipelex-demos/bad_bundles`): author-syntax messages at the raise sites, prose agent `validate`/`fix` surfaces, and one clean summary `message` on every surface | **DONE — all phases complete 2026-07-09; conformance corpus regen release-gated to step 6; archived from the worktree-root `TODOS.md`** |
+| [validation-error-reporting-plan.md](validation-error-reporting-plan.md) | Follow-on quality track (dogfooded on the internal bad-bundles playground): author-syntax messages at the raise sites, prose agent `validate`/`fix` surfaces, and one clean summary `message` on every surface | **DONE — all phases complete 2026-07-09; the cross-repo error-QA corpus regen is release-gated to step 6; archived from the worktree-root `TODOS.md`** |
| [step3-step4-hardened-loop-and-agent-apply.md](step3-step4-hardened-loop-and-agent-apply.md) | Detailed design + working plan for steps 3 (multi-file targeting) and 4 (`pipelex-agent fix bundle`) | **DONE — merged as PR #1035; review triage in [pr-1035-review-notes.md](pr-1035-review-notes.md)** |
| [pr-1035-review-notes.md](pr-1035-review-notes.md) | PR #1035 review triage — one real-but-inert finding deferred (intra-round cross-file collision) | **CURRENT** |
-| `deferred-checkpoint-{0,a,a-prime,b,c,d,e}-review-items.md` | Real-but-deferred items from each checkpoint's code review (multi-file targeting, conformance fixture sync, upstream `pipelex-tools-py` follow-ups, rename convergence cap, the step-5 exit triage in `-e`, …) | **CURRENT** |
+| `deferred-checkpoint-{0,a,a-prime,b,c,d,e}-review-items.md` | Real-but-deferred items from each checkpoint's code review (multi-file targeting, cross-repo fixture sync, upstream `pipelex-tools-py` follow-ups, rename convergence cap, the step-5 exit triage in `-e`, …) | **CURRENT** |
| [spike-reviewers-guide.md](spike-reviewers-guide.md) | Reviewer's guide for the step-1 spike PR (#1027) — the chain, invariants, test map | **DONE — Checkpoint 0 cleared 2026-07-07; archived from the worktree-root `TODOS.md`** |
| [step2-reviewers-guide.md](step2-reviewers-guide.md) | Reviewer's guide for the step-2 PR (#1031) — the chain, invariants, test map | **DONE — Checkpoint 1 cleared 2026-07-08; archived from the worktree-root `TODOS.md`** |
| [old-plan-to-auto-fix.md](old-plan-to-auto-fix.md) | The original `feature/Bundle-fixer` plan (standalone fix engine) | Superseded — kept as reference; its "Legacy reference" citations point at code that no longer exists |
diff --git a/wip/autofix/deferred-checkpoint-0-review-items.md b/wip/autofix/deferred-checkpoint-0-review-items.md
index 03148d352..3b3cc496b 100644
--- a/wip/autofix/deferred-checkpoint-0-review-items.md
+++ b/wip/autofix/deferred-checkpoint-0-review-items.md
@@ -20,9 +20,9 @@ gstack pre-landing review finding, deferred. The no-progress fingerprint in `fix
Once released, `suggested_fix` surfaces in `/validate` API payloads (additive, `exclude_none`). The master-plan step 3 changelog entry should call out the new optional field so API consumers know about it.
-## 2. Conformance fixture regeneration (cross-repo sync wave)
+## 2. Cross-repo fixture regeneration (sync wave)
-`conformance/validate-error-qa/generated/invalid_inadequate_output_multiplicity.json` pins the exact JSON body of an `INADEQUATE_OUTPUT_MULTIPLICITY` error from a live `pipelex-api`. Once this enrichment (`suggested_fix` on `ValidationErrorItem`, `expected_output_ref`) reaches the runner API via a pipelex release + pin bump, that fixture needs regeneration. Belongs to the already-tracked cross-repo schema-sync step (master plan) — nothing to do in this repo now.
+A fixture in our cross-repo spec suite pins the exact JSON body of an `INADEQUATE_OUTPUT_MULTIPLICITY` error from a live `pipelex-api`. Once this enrichment (`suggested_fix` on `ValidationErrorItem`, `expected_output_ref`) reaches the runner API via a pipelex release + pin bump, that fixture needs regeneration. Belongs to the already-tracked cross-repo schema-sync step (master plan) — nothing to do in this repo now.
## 3. Accepted as-is: unconditional `expected_output_ref` computation
diff --git a/wip/autofix/master-plan.md b/wip/autofix/master-plan.md
index 8739f3ffb..39526d12a 100644
--- a/wip/autofix/master-plan.md
+++ b/wip/autofix/master-plan.md
@@ -12,7 +12,7 @@ Deterministic auto-fixing of `.mthds` validation errors. Full rationale and arch
**Steps 3 (hardened loop) and 4 (agent apply surface) are DONE** — merged together as PR #1035 (`feature/Autofix-step4-Agnt-Apply`). Step 3 replaced the spike's drop-everything scoping guard with real multi-file targeting (source backfill at the translate funnel, resolved-dirs single-file gate, write-scope policy, per-file apply with `files_written`); step 4 shipped `pipelex-agent fix bundle` with the CLI-free markdown renderer and full test coverage. The PR review triage fixed two confirmed bugs and deferred one inert finding to [pr-1035-review-notes.md](pr-1035-review-notes.md).
-**Step 5 (human CLI surfacing) is DONE** — `pipelex fix bundle` (including the `--diff` preview), the `💡 Suggested fix:` lines + actionable footer in `pipelex validate`, docs, and changelog all landed on branch `feature/Autofix-step5`; detailed plan + decisions: [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md). The CHECKPOINT B exit review fixed five confirmed bugs on the branch and deferred five tradeoffs — triage in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md). The branch is PR-ready; **step 6 (release train) is next**, and its CHANGELOG must still name the additive `suggested_fix` wire field in `/validate` payloads (deferred item 1c) plus regenerate the conformance fixture (deferred item 2).
+**Step 5 (human CLI surfacing) is DONE** — `pipelex fix bundle` (including the `--diff` preview), the `💡 Suggested fix:` lines + actionable footer in `pipelex validate`, docs, and changelog all landed on branch `feature/Autofix-step5`; detailed plan + decisions: [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md). The CHECKPOINT B exit review fixed five confirmed bugs on the branch and deferred five tradeoffs — triage in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md). The branch is PR-ready; **step 6 (release train) is next**, and its CHANGELOG must still name the additive `suggested_fix` wire field in `/validate` payloads (deferred item 1c) plus regenerate the cross-repo error-QA fixture (deferred item 2).
## Sequencing doctrine (decided 2026-07-07)
@@ -71,7 +71,7 @@ Exit: a human can see the suggestion in `validate` and apply it with `fix`, with
### 6. Ship wave 1
-Release train: CHANGELOG entry (must mention the **additive `suggested_fix` wire field** now surfacing in `/validate` API payloads — deferred item 1c — plus the new commands), docs page in `docs/`, cut the pipelex release. Post-release follow-through: regenerate the conformance fixture that pins the `/validate` error body (deferred item 2, sibling `conformance/` repo) and bump the pipelex-api pin when the runner picks the version up. Exit (**CHECKPOINT 2**): released; hand-off list for wave 2 recorded.
+Release train: CHANGELOG entry (must mention the **additive `suggested_fix` wire field** now surfacing in `/validate` API payloads — deferred item 1c — plus the new commands), docs page in `docs/`, cut the pipelex release. Post-release follow-through: regenerate the fixture in our cross-repo spec suite that pins the `/validate` error body (deferred item 2) and bump the pipelex-api pin when the runner picks the version up. Exit (**CHECKPOINT 2**): released; hand-off list for wave 2 recorded.
### 7. Skills uptake
@@ -79,7 +79,7 @@ Update the `mthds-fix` skill (and the pipelex-plugins equivalent) to run determi
### 8–10. Wave 2 (each gets its own plan when it starts)
-- **Protocol promotion**: `suggested_fix` becomes a formal MTHDS protocol surface — spec sections in `docs/specs/`, conformance arm, schema sync to downstream copies (mthds, mthds-js, mthds-python).
+- **Protocol promotion**: `suggested_fix` becomes a formal MTHDS protocol surface — protocol-spec sections, a cross-repo spec-suite arm, schema sync to downstream copies (mthds, mthds-js, mthds-python).
- **Remote surfaces**: API `POST /fix` on pipelex-api, MCP `mthds_fix` tool — thin wrappers over the same engine/report; the markdown renderer already lives CLI-free for this reason.
- **Editor**: VS Code `CodeActionProvider` (first code action in the extension), quick fixes keyed on `diag.code = error_type` with fix payloads riding the existing validation backends.
diff --git a/wip/autofix/spike-reviewers-guide.md b/wip/autofix/spike-reviewers-guide.md
index 9d8bdbfce..e4ef958d7 100644
--- a/wip/autofix/spike-reviewers-guide.md
+++ b/wip/autofix/spike-reviewers-guide.md
@@ -30,7 +30,7 @@ This branch delivers **step 1 of the autofix master plan**: the whole suggested-
## Known deferrals (deliberate, not gaps)
-See `wip/autofix/deferred-checkpoint-0-review-items.md`: real multi-file fix targeting (thread `file_path` from raise sites — Phase 1); conformance fixture regeneration in the sibling `conformance/` repo (cross-repo sync wave, after a release reaches `pipelex-api`); `expected_output_ref` computed on the happy validation path too (accepted: trivial cost, laziness would duplicate code). One deleted surface: the empty, unreferenced `PipelexBundleBlueprintFixableErrorType` stub enum. Changelog entry is deferred to master-plan step 3 (ship wave) — the spike introduces no user-facing surface.
+See `wip/autofix/deferred-checkpoint-0-review-items.md`: real multi-file fix targeting (thread `file_path` from raise sites — Phase 1); fixture regeneration in our cross-repo spec suite (cross-repo sync wave, after a release reaches `pipelex-api`); `expected_output_ref` computed on the happy validation path too (accepted: trivial cost, laziness would duplicate code). One deleted surface: the empty, unreferenced `PipelexBundleBlueprintFixableErrorType` stub enum. Changelog entry is deferred to master-plan step 3 (ship wave) — the spike introduces no user-facing surface.
## Next steps (not in this PR)
diff --git a/wip/autofix/step5-human-cli-surfacing.md b/wip/autofix/step5-human-cli-surfacing.md
index 025964e2b..2f8721dc8 100644
--- a/wip/autofix/step5-human-cli-surfacing.md
+++ b/wip/autofix/step5-human-cli-surfacing.md
@@ -32,7 +32,7 @@ Two pieces, landed together for symmetry (per the master plan):
- **`💡 Suggested fix:` line** — per fixable error in `pipelex validate`'s error rendering, showing `SuggestedFix.description` only (ops stay machine-facing), plus an actionable footer naming the `pipelex fix` command.
- **`--diff` preview** (show, don't write) — listed in the design doc's wave-1 CLI surface and explicitly deferred from step 4 to here ("preview belongs to the human command"). Scoped as the last phase and **cuttable**: the step-5 exit criteria don't require it, so if it fights back it becomes a deferred item rather than blocking the step.
-**Out of scope:** the step-6 release train (user-facing docs page, conformance fixture regen, release cut); wave-2 surfaces (API `POST /fix`, MCP, editor); `--unsafe` (no UNSAFE rule exists in wave 1); richer still-invalid *markdown* for the agent command (only if Phase B's item renderer makes it free — see D5.5).
+**Out of scope:** the step-6 release train (user-facing docs page, cross-repo fixture regen, release cut); wave-2 surfaces (API `POST /fix`, MCP, editor); `--unsafe` (no UNSAFE rule exists in wave 1); richer still-invalid *markdown* for the agent command (only if Phase B's item renderer makes it free — see D5.5).
## What step 5 builds on (verified inventory)
@@ -164,7 +164,7 @@ Gates: `make agent-check` 0 errors; targeted CLI unit + integration suites and t
Step 6 is the release train (see [master-plan.md](master-plan.md) step 6). Two things this step deliberately did **not** absorb — they belong to the release cut, not to step 5:
- **The release CHANGELOG entry must name the additive `suggested_fix` wire field** now surfacing in `/validate` API payloads (deferred item 1c in the design doc). Step 5's `[Unreleased]` entries cover the human/agent CLI surfaces; the API wire-field mention is a release-train line.
-- **Regenerate the conformance fixture** that pins the `/validate` error body (deferred item 2, sibling `conformance/` repo), then bump the pipelex-api pin when the runner picks up the version.
+- **Regenerate the fixture in our cross-repo spec suite** that pins the `/validate` error body (deferred item 2), then bump the pipelex-api pin when the runner picks up the version.
Carry-in from Checkpoint B (in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md)) — not release blockers, fold into wave 2 unless they surface sooner: the validate footer over-count (item A) and the `--diff` `-L` dedup (item B) are the two with user-visible edge cases; the cross-CLI resolver/filter duplications (items C, D) are the natural next shared-abstraction refactor.
diff --git a/wip/autofix/suggested-fixes-design.md b/wip/autofix/suggested-fixes-design.md
index a854e3579..bd45d7117 100644
--- a/wip/autofix/suggested-fixes-design.md
+++ b/wip/autofix/suggested-fixes-design.md
@@ -5,7 +5,7 @@ Design for deterministic auto-fixing of `.mthds` bundles. Supersedes [old-plan-t
## Decisions taken (2026-07-07, with Louis)
- **D1 — Fixes attach to diagnostics.** Each fixable `ValidationErrorItem` carries a structured `suggested_fix`. The `fix` command is just "apply what validate found", in a loop. No standalone fix engine that re-derives problems.
-- **D2 — Runtime-only wire first.** `suggested_fix` is an additive, optional, pipelex-owned field. Formal promotion into the MTHDS protocol (spec + conformance + downstream schema copies in mthds / mthds-js / mthds-python) is a later wave, once the shape is proven.
+- **D2 — Runtime-only wire first.** `suggested_fix` is an additive, optional, pipelex-owned field. Formal promotion into the MTHDS protocol (spec + cross-repo spec suite + downstream schema copies in mthds / mthds-js / mthds-python) is a later wave, once the shape is proven.
- **D3 — Wave 1 consumer = agent CLI + skills.** `pipelex-agent fix` with the convergence loop, consumed by the `mthds-fix` skill and hooks. API `POST /fix`, MCP `mthds_fix` tool, and VS Code quick fixes are later waves.
- **D4 — Pruning rules cut from wave 1.** `prune-unreachable` / `prune-unused-concepts` are cleanups, not fixes — nothing is broken when they'd fire. Salvage the graph-walk logic later as opt-in lint warnings with attached fixes. Wave 1 is purely "make invalid bundles valid".
@@ -15,7 +15,7 @@ The old branch built a separate fix engine that re-implemented the validation pi
The decisive observation: **the validator already knows the correct value at detection time.** `PipeSequence.validate_output_with_library` (`pipelex/pipe_controllers/sequence/pipe_sequence.py:63-115`) compares the declared output against the last step's output and already ships the correct concept in the error (`provided_concept_code`). `generic_validate_inputs_with_library` (`pipelex/core/pipes/pipe_abstract.py:264`) compares declared inputs against `needed_inputs()`. So fixability comes from **richer typed errors**, not from a smarter fixer: enrich the error to carry the expected value, and fix construction becomes a mechanical translation that cannot drift from the validator.
-This also matches the workspace's presentation-vs-contract principle (`docs/specs/pipelex-mthds-protocol.md`): the fix ops are contract data on the structured report; any rendered diff is presentation. One validation engine keeps feeding every surface.
+This also matches the workspace's presentation-vs-contract principle (the MTHDS protocol spec): the fix ops are contract data on the structured report; any rendered diff is presentation. One validation engine keeps feeding every surface.
## Architecture
@@ -51,7 +51,7 @@ class SuggestedFix(BaseModel):
`ValidationErrorItem` gains `suggested_fix: SuggestedFix | None = None`. Serialization stays `exclude_none`, so nothing changes for non-fixable errors. Naming is brand-neutral (language-level concept — no `pipelex_` prefixes in field names).
-Note `ValidationErrorItem` flows through the hosted API's `InvalidReport` too, so the field will *appear* on the API wire as soon as it exists — that's fine and additive; what D2 defers is the formal contract work (spec sections, conformance tests, downstream schema mirrors), not hiding the field.
+Note `ValidationErrorItem` flows through the hosted API's `InvalidReport` too, so the field will *appear* on the API wire as soon as it exists — that's fine and additive; what D2 defers is the formal contract work (spec sections, spec-suite tests, downstream schema mirrors), not hiding the field.
### The applier
@@ -209,7 +209,7 @@ So the human-CLI gate (master-plan step 5, bar 1 — "the abstraction has been s
### Wave 2 (separate plan, not scoped here)
-Protocol promotion (spec sections in `docs/specs/`, conformance arm, schema sync to mthds / mthds-js / mthds-python), API `POST /fix`, MCP `mthds_fix` tool, VS Code `CodeActionProvider` (first code action in the LSP — keyed on `diag.code = error_type`, fix payloads already ride the validation backends), `mthds-fix` / pipelex-plugins skill updates, pruning rules as lint warnings with attached fixes.
+Protocol promotion (protocol-spec sections, a cross-repo spec-suite arm, schema sync to mthds / mthds-js / mthds-python), API `POST /fix`, MCP `mthds_fix` tool, VS Code `CodeActionProvider` (first code action in the LSP — keyed on `diag.code = error_type`, fix payloads already ride the validation backends), `mthds-fix` / pipelex-plugins skill updates, pruning rules as lint warnings with attached fixes.
## Salvage map from `feature/Bundle-fixer`
diff --git a/wip/autofix/validation-error-reporting-plan.md b/wip/autofix/validation-error-reporting-plan.md
index 98e72b397..4a21adc4e 100644
--- a/wip/autofix/validation-error-reporting-plan.md
+++ b/wip/autofix/validation-error-reporting-plan.md
@@ -1,10 +1,10 @@
# Validation-error reporting & surfacing — improvement plan
-> **ARCHIVED — track COMPLETE (2026-07-09).** All phases done; the only open item is the release-gated `conformance/validate-error-qa/` corpus regen (folded into the autofix step-6 release train). The durable record now lives in the code, the wording-pinning tests (`test_validation_render.py`, `test_validate_bundle_error_format.py`, `test_handle_pipe_errors_suffix.py`, `test_fix_loop_bail.py`, and the `*_enrichment.py` suites), the CHANGELOG `[Unreleased]` entries, and the conformance corpus. The `wip/validation-reporting/` before/after captures + `phase0-inventory.md` + `writeup.html` referenced throughout were dogfooding artifacts, removed at archival — recoverable from git history (`d4fc4749a`, `4911b6b90`). Archived here from the worktree-root `TODOS.md`.
+> **ARCHIVED — track COMPLETE (2026-07-09).** All phases done; the only open item is the release-gated error-QA corpus regen in our cross-repo spec suite (folded into the autofix step-6 release train). The durable record now lives in the code, the wording-pinning tests (`test_validation_render.py`, `test_validate_bundle_error_format.py`, `test_handle_pipe_errors_suffix.py`, `test_fix_loop_bail.py`, and the `*_enrichment.py` suites), the CHANGELOG `[Unreleased]` entries, and that corpus. The `wip/validation-reporting/` before/after captures + `phase0-inventory.md` + `writeup.html` referenced throughout were dogfooding artifacts, removed at archival — recoverable from git history (`d4fc4749a`, `4911b6b90`). Archived here from the worktree-root `TODOS.md`.
## Goal (use this as the /goal)
-Perfect, clear validation-error reports and fix reports on every surface: every validation error must state — in MTHDS author syntax, never internal repr — what is wrong, where it is, and exactly what to write to fix it; and every surface (human `pipelex validate` / `pipelex fix`, agent `pipelex-agent validate` / `pipelex-agent fix` in markdown and JSON, the API `/validate` payload) must present that explanation at full strength, with an actionable next step, verified hands-on against the `pipelex-demos/bad_bundles` playground.
+Perfect, clear validation-error reports and fix reports on every surface: every validation error must state — in MTHDS author syntax, never internal repr — what is wrong, where it is, and exactly what to write to fix it; and every surface (human `pipelex validate` / `pipelex fix`, agent `pipelex-agent validate` / `pipelex-agent fix` in markdown and JSON, the API `/validate` payload) must present that explanation at full strength, with an actionable next step, verified hands-on against the internal bad-bundles playground.
## Where this work lives
@@ -13,12 +13,12 @@ Perfect, clear validation-error reports and fix reports on every surface: every
## The test bed (built 2026-07-09, session before this plan)
-`/Users/lchoquel/repos/Pipelex/pipelex-demos/bad_bundles/` — a playground of deliberately broken `.mthds` bundles, one scenario per directory, covering every autofix rule plus an unfixable-collision safety case and a kitchen-sink combo. Its `README.md` documents every scenario and the exact commands; `_pristine/` holds backups and `./restore.sh` re-breaks everything, so it can be exercised repeatedly. **This is where every before/after comparison in this plan gets verified.**
+An internal **bad-bundles playground** — deliberately broken `.mthds` bundles, one scenario per directory, covering every autofix rule plus an unfixable-collision safety case and a kitchen-sink combo. Its `README.md` documents every scenario and the exact commands; `_pristine/` holds backups and `./restore.sh` re-breaks everything, so it can be exercised repeatedly. **This is where every before/after comparison in this plan gets verified.** Its location is recorded at workspace level.
-Run everything from the `pipelex-demos` repo root with its own venv (the user fixed it; it has the `fix` command):
+Run everything from that repo's root with its own venv (the user fixed it; it has the `fix` command):
```bash
-cd /Users/lchoquel/repos/Pipelex/pipelex-demos
+cd <bad-bundles playground repo>
source .venv/bin/activate
export PIPELEX_NO_DECK_NOTICE=1
pipelex validate bundle bad_bundles/01_wrong_sequence_output/bundle.mthds
@@ -34,7 +34,7 @@ Comparing `pipelex validate`, `pipelex-agent validate`, and `pipelex fix --diff`
1. **Messages leak internal repr instead of author syntax.** The sequence-multiplicity raise site (`pipelex/pipe_controllers/sequence/pipe_sequence.py:114-118`) says `declares output multiplicity=None, but the last step ... has output multiplicity=True` — Python internals (`None` = single, `True` = list). An author writes `StoryIdea` vs `StoryIdea[]`. The message never shows the solution.
2. **The `(required: [...], provided: ...)` suffix is misleading on multiplicity errors.** Appended generically in `categorize_pipe_validation_with_libraries_error` (`pipelex/core/pipes/handle_pipe_errors.py:193`) by raw-repr-ing `required_concept_codes` (a Python list) and `provided_concept_code` (a string). For `INADEQUATE_OUTPUT_MULTIPLICITY` the concepts are identical by definition (the concept check passed just above), so it prints two same-looking refs — and the list-repr brackets `['story_studio.StoryIdea']` accidentally mimic MTHDS `[]` multiplicity syntax. It reads like a multiplicity statement it is not making.
3. **The correct solution string exists at the raise site and is thrown away by the message.** `expected_output_ref` is computed as exactly `"StoryIdea[]"` (`pipe_sequence.py:86-90`, via `StuffSpec.to_bundle_representation`) but flows only into the fix-planner enrichment (the `💡` line). Any surface showing only `message` (agent top line, API consumers) gets the `None`/`True` riddle.
-4. **The agent markdown under-delivers on the workspace's own "format follows consumer" doctrine.** `pipelex-agent validate` markdown = a title, a *truncated* top message (drops the required/provided detail the item has), a boilerplate hint ("Check the validation_errors array for specific issues", from `pipelex/pipeline/exceptions.py:92`), then a raw JSON dump of `validation_errors`. The per-item prose rendering the human renderer got in step 5 (titled error, field lines, `💡 Suggested fix:` line, actionable footer naming the fix command) never got mirrored to the agent markdown. Doctrine reference: workspace-root `CLAUDE.md` § "Surface output conventions" and `docs/specs/pipelex-mthds-protocol.md` § "Presentation vs contract".
+4. **The agent markdown under-delivers on the workspace's own "format follows consumer" doctrine.** `pipelex-agent validate` markdown = a title, a *truncated* top message (drops the required/provided detail the item has), a boilerplate hint ("Check the validation_errors array for specific issues", from `pipelex/pipeline/exceptions.py:92`), then a raw JSON dump of `validation_errors`. The per-item prose rendering the human renderer got in step 5 (titled error, field lines, `💡 Suggested fix:` line, actionable footer naming the fix command) never got mirrored to the agent markdown. Doctrine reference: the workspace's "Surface output conventions" and the MTHDS protocol spec's "Presentation vs contract".
5. **The human footer is the model to generalize:** `💡 N of these errors can be fixed automatically — run: pipelex fix bundle <path>` — "a hint needs an action behind it". The agent surfaces have no equivalent (neither validate nor the hint text), even though the payload carries `suggested_fix` with `safety: "safe"`.
## Key code map
@@ -52,11 +52,11 @@ Comparing `pipelex validate`, `pipelex-agent validate`, and `pipelex fix --diff`
| Agent/API fix markdown renderer (CLI-free) | `pipelex/pipeline/fixes/fix_render.py` (`format_fix_markdown`) |
| API error envelope (`ValidateBundleError.to_error_report`, boilerplate hint) | `pipelex/pipeline/exceptions.py` (hint at :92, report at ~:154) |
| Tests pinning current wordings/renderings | `tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py`, `tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py`, `tests/integration/pipelex/cli/test_fix_bundle_human.py`, `tests/integration/pipelex/pipeline/test_fix_convergence_loop.py`, e2e under `tests/e2e/pipelex/cli/` and `tests/e2e/agent_cli/` |
-| Cross-repo wording corpus (regen after wording changes) | `conformance/validate-error-qa/` — the generated error-explanation QA corpus, freshness-tested against the live API (see workspace-root `CLAUDE.md`) |
+| Cross-repo wording corpus (regen after wording changes) | The generated error-explanation QA corpus in our cross-repo spec suite, freshness-tested against the live API |
## Guardrails
-- **Presentation vs contract:** wordings, markdown shape, exit codes, and hints are presentation — free to improve. The structured fields (`is_valid`, `error_type`, `category`, `suggested_fix`, `validation_errors[]`) are the machine contract — additive changes only, and any addition ripples to the API report and conformance fixtures (step-6 already owes a `suggested_fix` fixture regen; coordinate, don't collide).
+- **Presentation vs contract:** wordings, markdown shape, exit codes, and hints are presentation — free to improve. The structured fields (`is_valid`, `error_type`, `category`, `suggested_fix`, `validation_errors[]`) are the machine contract — additive changes only, and any addition ripples to the API report and the cross-repo spec-suite fixtures (step-6 already owes a `suggested_fix` fixture regen; coordinate, don't collide).
- **One engine, every surface:** improvements go into the message at the raise site or the shared items builder/renderers — never into per-surface private wording that can drift.
- Wording changes WILL break string-pinning tests; update the pins in the same change (that's the point of them).
@@ -103,20 +103,20 @@ The intended architecture for Phase 2 (agent surfaces catch up), converged after
- [x] **Carry-over from Phase 2 (disease C, JSON `message`):** cleaned the leaky top-level `message` at its **source** — a new `_summarize_bundle_validation_message(...)` in `pipeline/exceptions.py`, called from `ValidateBundleError.__init__`, replaces the raw pydantic/interpreter top-line with a clean summary derived from the per-error item messages (the lone item message when there's one categorized error; `N validation errors (first: …)` when several). Falls back to the raw message only when there is NO categorized data (a parse-level failure whose raw message is authoritative — e.g. TOML syntax; keeps the pipelex-api `"TOML" in body["message"]` pin green). One engine → **every** surface benefits (agent JSON `message`, API `InvalidReport.message`/report `detail`), not CLI-only. Verified live on the playground: the JSON `message` is now clean on all 10 scenarios (the *only* line that changed; the human/agent-md/fix surfaces are byte-identical). No hook branches on `message`.
- [x] API `/validate` parity: `to_error_report` carries the improved messages verbatim (the summary rides `report.message` → `InvalidReport.message`; a produced verdict stays a 200/`is_valid` body — no contract change). **Unified** `render_invalid_validation_markdown` (the API `rendered_markdown` invalid-arm renderer, `validation_render.py`) to reconstruct the typed items and delegate to the shared `format_validation_error_items_markdown` — so the API markdown now carries per-item `💡 Suggested fix` lines and is structurally identical to the agent/human prose (was the older dict-based `## Errors (N)` list with no fix lines). The redundant top summary line was dropped (matches the agent CLI prose surface; no CLI-command footer since an API consumer applies fixes via the structured `suggested_fix` ops). `rendered_markdown` is presentation, never the contract.
- [x] Fix reports: reviewed all `bail_reason` wordings against the message bar. The one that leaked internal repr — the no-progress bail dumping raw `_fix_fingerprint` strings (`fix_loop.py`) — now names the re-proposed fix's author-facing **description** instead (`"no progress: the same fix was re-proposed without changing the bundle (<description>); its target could not be applied as written — fix the remaining errors manually"`). The other bail reasons (out-of-scope, cross-file collision, max-iterations) already met the bar. The `--diff` preview runs the **real** loop against a sandbox copy and reuses `_render_fix_result(preview=True)`, so preview wording matching the real run is structurally guaranteed (no change needed). The still-invalid "still shows a suggested fix that was not applied" tip already meets the bar.
-- [x] Additive structured fields: **decided NOT to add any.** The `suggested_fix` ops already carry the machine-actionable data (e.g. `set_key output = "StoryIdea[]"`) and the message states it in author syntax, so an `expected_output_ref` wire field would be redundant and would expand the contract (changelog + conformance regen) for no concrete consumer — against the "smallest correct surface, no speculative additions" guardrail.
+- [x] Additive structured fields: **decided NOT to add any.** The `suggested_fix` ops already carry the machine-actionable data (e.g. `set_key output = "StoryIdea[]"`) and the message states it in author syntax, so an `expected_output_ref` wire field would be redundant and would expand the contract (changelog + cross-repo corpus regen) for no concrete consumer — against the "smallest correct surface, no speculative additions" guardrail.
- [x] **CHECKPOINT 3** — this doc updated (below). Tests updated in the same change: retargeted `test_validate_bundle_category_framing.py` (the `.message` framing pin → a clean-summary invariant across all four entry points, since the category-framing prefix was subsumed by the structured items), `test_validation_render.py` (invalid-arm prose shape + 💡 line), `test_fix_loop_bail.py` (no-progress wording). `make agent-check` green; targeted suites green (pipeline + cli + core + fixes + e2e agent_cli = 1798 passed).
-### Phase 4 — Full-sweep QA and closeout — DONE (conformance regen release-gated)
+### Phase 4 — Full-sweep QA and closeout — DONE (cross-repo corpus regen release-gated)
- [x] Restored the playground and re-captured every scenario × every surface → `wip/validation-reporting/after/`. **The only per-scenario delta vs Phase 2 is the JSON `message` line (now clean) on all 10**; human validate, agent-md, human fix `--diff`, and agent fix are byte-identical — zero regressions. Zero leak fragments (`Value errors:` / `multiplicity=None` / `Could not load …` / json-fence) remain in any capture. Goal-bar spot-check on scenario 03 (the Phase-0 worst offender): human/agent-md/agent-json all state the problem AND the concrete author-syntax action; scenario 09's collision bail renders the remaining error as prose + the actionable bail reason + tip.
-- [ ] **Regenerate `conformance/validate-error-qa/` corpus — DEFERRED, release-gated (belongs to step 6).** All 40 `invalid_*.json` + `invalid_*.md` fixtures pin the old leaky top-line `message`; the freshness guard (`conformance/tests/validate_error_qa/test_corpus_fresh.py`) asserts them byte-for-byte against the **live** `/validate`, and the conformance repo pins a *released* pipelex — so the corpus can only be regenerated (`make validate-error-qa`) once these wordings ship. Coordinate with the step-6 `suggested_fix` fixture regen already owed (guardrail: "coordinate, don't collide"). The `invalid_*.agentcli.md` channel is unaffected (it already renders items via `format_validation_error_items_markdown`, ungated).
-- [x] Docs: CHANGELOG `[Unreleased]` gained the validation-error-reporting entries (author-syntax messages, agent prose rendering, clean summary message on every surface + API `rendered_markdown` 💡 lines, no-progress bail wording). The CLI docs (`docs/tools/cli/validate.md`, `fix.md`, `agent-cli.md`) describe the 💡 line / fix command / error envelope **generically and remain accurate** — no stale reprs were embedded, so no edits were needed. `pipelex-demos/bad_bundles/README.md` embeds no error-output strings (commands unchanged), so it needs no update.
+- [ ] **Regenerate the error-QA corpus in our cross-repo spec suite — DEFERRED, release-gated (belongs to step 6).** Every invalid-case fixture pins the old leaky top-line `message`; that suite's freshness guard asserts them byte-for-byte against the **live** `/validate`, and the suite pins a *released* pipelex — so the corpus can only be regenerated once these wordings ship. Coordinate with the step-6 `suggested_fix` fixture regen already owed (guardrail: "coordinate, don't collide"). The agent-CLI channel is unaffected (it already renders items via `format_validation_error_items_markdown`, ungated).
+- [x] Docs: CHANGELOG `[Unreleased]` gained the validation-error-reporting entries (author-syntax messages, agent prose rendering, clean summary message on every surface + API `rendered_markdown` 💡 lines, no-progress bail wording). The CLI docs (`docs/tools/cli/validate.md`, `fix.md`, `agent-cli.md`) describe the 💡 line / fix command / error envelope **generically and remain accurate** — no stale reprs were embedded, so no edits were needed. The bad-bundles playground's own `README.md` embeds no error-output strings (commands unchanged), so it needs no update.
- [x] `make agent-check` green. `make agent-test` (full suite — run because the change touches the shared `ValidateBundleError` base) — see status log for result. Final status update below.
## Status log
-- 2026-07-09 — **Phase 4 DONE — TRACK COMPLETE (conformance regen release-gated to step 6).** Full-sweep re-capture confirms the only per-scenario delta vs Phase 2 is the now-clean JSON `message` on all 10 scenarios; every other surface byte-identical; zero leak fragments anywhere; goal bar met on every surface (spot-checked scenario 03, the Phase-0 worst offender, + scenario 09 collision bail). CHANGELOG `[Unreleased]` updated; CLI docs verified accurate as-is (no stale reprs embedded → no edits); `bad_bundles/README.md` unaffected. `make agent-check` green; **full `make agent-test` suite green**. Remaining follow-up = the release-gated `conformance/validate-error-qa/` corpus regen (all 40 `invalid_*.{json,md}` fixtures pin the old leaky top-line; regenerate via `make validate-error-qa` once these wordings ship, alongside step 6's owed `suggested_fix` fixture regen). All code changes UNCOMMITTED on `feature/Autofix`.
-- 2026-07-09 — **Phase 3 DONE (CHECKPOINT 3 cleared).** Disease C fixed at the source: new `_summarize_bundle_validation_message(...)` in `pipeline/exceptions.py`, called from `ValidateBundleError.__init__`, replaces the leaky pydantic/interpreter top-line (`Validation error(s): … Value errors: '<field>': Value error, …`, plus `Pipe validation failed:` / `Could not load … because of:` prefixes) with a clean item-derived summary — one engine, so the agent JSON `message` **and** the API `InvalidReport.message` both benefit; raw message kept as the fallback only when there's no categorized data (keeps the TOML-syntax pin green). API markdown unified: `render_invalid_validation_markdown` now delegates to the shared `format_validation_error_items_markdown`, gaining per-item 💡 lines (was a dict-based `## Errors (N)` list). No-progress fix bail_reason no longer dumps internal fingerprints — names the fix description instead. Decided against adding speculative structured wire fields (`suggested_fix` ops already carry the actionable data). Tests: retargeted `test_validate_bundle_category_framing.py` (framing pin → clean-summary invariant), updated `test_validation_render.py` (prose+💡) and `test_fix_loop_bail.py` (wording). `make agent-check` green; targeted suites green (1798 passed). **Full-sweep re-capture** (`wip/validation-reporting/after/`): the ONLY per-scenario delta vs Phase 2 is the JSON `message` line on all 10 (now clean); human/agent-md/fix surfaces byte-identical; zero leak fragments remain anywhere. NEXT = **Phase 4** (conformance corpus regen is release-gated → deferred to step 6; docs + CHANGELOG; final agent-test).
+- 2026-07-09 — **Phase 4 DONE — TRACK COMPLETE (cross-repo corpus regen release-gated to step 6).** Full-sweep re-capture confirms the only per-scenario delta vs Phase 2 is the now-clean JSON `message` on all 10 scenarios; every other surface byte-identical; zero leak fragments anywhere; goal bar met on every surface (spot-checked scenario 03, the Phase-0 worst offender, + scenario 09 collision bail). CHANGELOG `[Unreleased]` updated; CLI docs verified accurate as-is (no stale reprs embedded → no edits); `bad_bundles/README.md` unaffected. `make agent-check` green; **full `make agent-test` suite green**. Remaining follow-up = the release-gated error-QA corpus regen in our cross-repo spec suite (every invalid-case fixture pins the old leaky top-line; regenerate once these wordings ship, alongside step 6's owed `suggested_fix` fixture regen). All code changes UNCOMMITTED on `feature/Autofix`.
+- 2026-07-09 — **Phase 3 DONE (CHECKPOINT 3 cleared).** Disease C fixed at the source: new `_summarize_bundle_validation_message(...)` in `pipeline/exceptions.py`, called from `ValidateBundleError.__init__`, replaces the leaky pydantic/interpreter top-line (`Validation error(s): … Value errors: '<field>': Value error, …`, plus `Pipe validation failed:` / `Could not load … because of:` prefixes) with a clean item-derived summary — one engine, so the agent JSON `message` **and** the API `InvalidReport.message` both benefit; raw message kept as the fallback only when there's no categorized data (keeps the TOML-syntax pin green). API markdown unified: `render_invalid_validation_markdown` now delegates to the shared `format_validation_error_items_markdown`, gaining per-item 💡 lines (was a dict-based `## Errors (N)` list). No-progress fix bail_reason no longer dumps internal fingerprints — names the fix description instead. Decided against adding speculative structured wire fields (`suggested_fix` ops already carry the actionable data). Tests: retargeted `test_validate_bundle_category_framing.py` (framing pin → clean-summary invariant), updated `test_validation_render.py` (prose+💡) and `test_fix_loop_bail.py` (wording). `make agent-check` green; targeted suites green (1798 passed). **Full-sweep re-capture** (`wip/validation-reporting/after/`): the ONLY per-scenario delta vs Phase 2 is the JSON `message` line on all 10 (now clean); human/agent-md/fix surfaces byte-identical; zero leak fragments remain anywhere. NEXT = **Phase 4** (the cross-repo corpus regen is release-gated → deferred to step 6; docs + CHANGELOG; final agent-test).
- 2026-07-09 — Plan written from the dogfooding session (playground built + three-surface diagnosis on scenario 01). No implementation started.
- 2026-07-09 — **Phase 0 DONE.** Confirmed the step-5 code is present on `feature/Autofix` (came in via the `dev` merge `ec477700f`); demos venv points at this worktree, so code changes dogfood live. Captured every scenario × five surfaces to `wip/validation-reporting/before/`. Inventory in `phase0-inventory.md`: 6 diseases (A internal-repr messages, B misleading required/provided suffix, C pydantic top-line leak, D agent-md JSON-dump-not-prose, E boilerplate agent hint, F snake_case wording). Raise sites confirmed: `pipe_sequence.py:114` (multiplicity), `pipe_abstract.py:361-373` (stuff-spec-mismatch — worst), `handle_pipe_errors.py:192` (suffix). `StuffSpec.to_bundle_representation(relative_to_domain=…)` is the author-syntax renderer for Phase 1.
- 2026-07-09 — **Phase 2 DONE (CHECKPOINT 2 cleared).** Agent surfaces now render prose. New shared CLI-free renderer `format_validation_error_items_markdown(items)` + `build_fix_command(executable, *, bundle_path, library_dirs, allow_signatures)` in `pipeline/validation_render.py` (mirror the human `display_validation_error_items` / footer). New dispatcher `agent_error_validate_bundle(exc, *, bundle_path, library_dirs, allow_signatures)` in `agent_output.py` (markdown prose + fix-aware footer; JSON envelope byte-identical) wired into `validate/bundle_cmd.py` + `method_cmd.py`. New `format_fix_still_invalid_markdown(result, *, bundle_path)` in `fix_render.py` wired into `fix/bundle_cmd.py` markdown branch (JSON `FixBundleError` unchanged). Human `handle_validate_bundle_error` refactored to the shared `build_fix_command` (byte-identical). Disease D (JSON-dump→prose) + E (boilerplate hint→fix-aware footer) cured on the markdown surface; disease C cured in markdown (items shown, not `exc.message`) — **JSON `message` cleanup deferred to Phase 3** (fix at source, one-engine). Tests: +1 new module (`tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py`), strengthened `test_validation_render.py` / `test_fix_render.py` / `test_fix_format.py`. `make agent-check` green; cli+integration-pipeline+e2e suites green. Re-captured `wip/validation-reporting/after/` (regen script: `scratchpad/capture_after.sh` — runs human `pipelex` with `--no-logo`, strips banner/telemetry-DEBUG noise; demos venv points at this worktree so changes dogfood live). Per-section verification: AGENT-md CHANGED×10, AGENT-json SAME×10, HUMAN-validate/fix SAME×10, AGENT-fix-md CHANGED×1 (09 only). NEXT = **Phase 3** (JSON/API parity + the disease-C JSON-`message` carry-over at source; fix reports' `bail_reason` wording; consider additive structured fields).
diff --git a/wip/boot-split/README.md b/wip/boot-split/README.md
deleted file mode 100644
index 7b7ca6014..000000000
--- a/wip/boot-split/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Boot split
-
-The composition root `pipelex/pipelex.py` was split into a runtime-layer `RuntimeBoot` (`pipelex/runtime_boot.py`) and the interpreter-layer `Pipelex` that subclasses it. **Track complete** — [PR #1073](https://github.com/Pipelex/pipelex/pull/1073) squash-merged into `dev` as `8448c5ca2` on 2026-07-30, and the repo-root `TODOS.md` tracker was archived here as [`boot-split-tracker.md`](boot-split-tracker.md).
-
-The change itself is described in that tracker — the reviewer's guide, the load-bearing decisions, the measured payoff and every review round's record; start at its "Final state at merge" — and in [Where the boot splits](../../docs/contribute/hub-layering.md#where-the-boot-splits). Everything else here is what was **deliberately not done**, each with the analysis and a suggested shape.
-
-Every deferral note was raised by a review pass, verified against the source, and deferred on a stated tradeoff rather than on effort. Production comments point at these files by path, so moving or renaming one means updating its citation.
-
-| Note | What it defers |
-|---|---|
-| [`runtime-boot-external-interpreter-orchestrator.md`](runtime-boot-external-interpreter-orchestrator.md) | **RESOLVED.** A runtime-only boot used to accept an interpreter-layer orchestrator contributed by an *external* entry-point plugin, because `build_registrar` discovered externals unconditionally. The plugin entry-point group split supplied the missing layer signal and scoped discovery, so the name is no longer registered and the existing gate rejects it. Neither proposed remedy was built. |
-| [`config-dir-does-not-scope-inference-paths.md`](config-dir-does-not-scope-inference-paths.md) | `config_dir` scopes the main TOML load but not the inference files (backends, routing profiles, model deck), because pinning those needs path overrides that live on the concrete `ModelManager` rather than on the `ModelManagerAbstract` the boot is typed against. Closing it means widening a public injection contract. Cited from both `make()` docstrings and the boot call site. |
-| [`failed-boot-does-not-release-every-resource.md`](failed-boot-does-not-release-every-resource.md) | `_teardown_runtime` and `_release_after_failed_boot` are two hand-maintained release lists. The half that *poisons* the next boot is now identical on both; the *dangling* half (`sdk_client_manager`, `reporting_delegate`, `func_registry`) is not. Collapsing them into one list is a lifecycle decision. |
-| [`pipelex-setup-narrows-the-runtime-boot-contract.md`](pipelex-setup-narrows-the-runtime-boot-contract.md) | `Pipelex.setup` is an `@override` that does not accept its base's `builtin_plugins` / `core_unconditional_plugin_names`, absorbs them in `**kwargs` and raises — so a caller written against the base type type-checks and fails at run time. Every candidate remedy trades one wart for another. |
-| [`boot-split-test-coverage-gaps.md`](boot-split-test-coverage-gaps.md) | The gaps *around* the new tests. A test-quality pass confirmed no new test passes vacuously; these are the coverage tradeoffs it found, each a decision rather than a patch. |
-
-None of these blocked the merge. The two that name a first caller — the external-orchestrator hole and the `config_dir` scoping — are the ones to settle before `RuntimeBoot.make()` becomes reachable from a real entry point.
-
-## Still open outside this repo
-
-One **required cross-repo follow-up**, deliberately out of scope for PR #1073: `pipelex-temporal/tests/conftest.py:86` and `pipelex-transport/tests/conftest.py:89` each patch `"pipelex.pipelex.load_pipelex_service_config_if_exists"` in an autouse session fixture. That symbol now lives in `pipelex.runtime_boot`, so both suites fail at session start once they pick up the new `pipelex`. Repoint both strings. ⚠ Use `git -C <repo> grep` for any cross-repo sweep here — this environment's `grep` is a shell function that does not traverse sibling repos and silently returns zero.
diff --git a/wip/boot-split/boot-split-test-coverage-gaps.md b/wip/boot-split/boot-split-test-coverage-gaps.md
deleted file mode 100644
index 9fab33515..000000000
--- a/wip/boot-split/boot-split-test-coverage-gaps.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Boot-split test-coverage gaps left open deliberately
-
-**Status:** deferred. Found by a test-quality review pass on PR #1073, which confirmed no new test on that branch passes vacuously. These are the gaps it found *around* the new tests. Each is a coverage tradeoff rather than a defect, so each is recorded rather than patched — the two that were cheap and pinned a documented unrecoverable invariant (the same-class exclusivity guard, and `Pipelex.teardown_if_needed()` against a bare `RuntimeBoot`) were fixed on the branch instead.
-
-## 1. The `try`/`finally` around `_teardown_plugin_callbacks` is only distinguishable under `BaseException`
-
-`_teardown_plugin_callbacks` swallows every ordinary `Exception` per callback, so wrapping the call in `try`/`finally` differs from a bare sequence *only* when a `BaseException` passes through — and the 16-line justification on the failed-boot path says exactly that ("must run even on a `KeyboardInterrupt` mid-teardown"). No test raises one, so deleting the `try`/`finally` keeps the suite green.
-
-This now covers **three** sites, not one: `_release_after_failed_boot`, `RuntimeBoot.teardown` and `Pipelex.teardown` all wrap the call, the latter two added by the pre-landing review that found the sibling gap. Three unpinned copies of one argument is a stronger case for a test than one was.
-
-Still not fixed, for the same reason: the test would be pinning Python's `finally` semantics against a hand-raised `KeyboardInterrupt` from a plugin callback, contrived enough that the next reader would reasonably question why it exists. The rationale comments are the actual defence. Worth adding if any of the three paths ever grows a leading step that can raise ordinarily — at which point the test stops being contrived.
-
-## 2. The booted-runtime closure subprocess runs outside the test harness
-
-`tests/unit/pipelex/test_runtime_boot_closure.py` boots in a fresh interpreter via `subprocess.run`, and `RunMode` is set by an in-process session fixture rather than an env var. Measured inside the subprocess: `run_mode=normal`, `is_unit_testing=False`. Consequences:
-
-- `tests/pipelex_unit_test.toml` is **not** layered.
-- The developer's real global and project `.pipelex/` configs **are** (cwd is inherited).
-- `ensure_global_config_exists()` runs — a filesystem write to `~/.pipelex` from a unit test.
-
-So the verdict depends on the machine's config: a `.pipelex/pipelex.toml` enabling an external plugin that pulls an interpreter package would produce a spurious failure.
-
-Not fixed with the obvious one-liner (`env={**os.environ, "RUN_MODE": "unit_test"}`) because it cuts the other way too: the unit-test config layer may disable plugin groups, which would *weaken* the sweep it is meant to strengthen. Deciding which config a hermetic boot-closure test should run against — and whether the answer is a purpose-built minimal config dir rather than either existing one — is a decision worth making deliberately. Note that the sibling import-closure test does not have this problem, because it only imports.
-
-## 3. Untested new public surfaces
-
-- `RuntimeBoot.make(needs_inference=True)` — every call site passes `False`, so `validate_model_deck()` on the runtime-only path has no coverage.
-- `Pipelex.make(config_dir=...)` — `config_dir` is tested through `RuntimeBoot.make` only, though the parameter is documented at length on both.
-- The two `| None` narrowing guards in `Pipelex.setup` (plugin registrar, class registry). These are unreachable by construction — `super().setup()` assigns both unconditionally and any earlier failure propagates — and exist to satisfy the declarations. Testing an unreachable branch is not worth it; the note is here so nobody mistakes the absence for an oversight.
-
-## 4. Teardown *phase order* is asserted nowhere
-
-`Pipelex.teardown` sequences plugin callbacks → pipeline manager → runtime, and the comment calls the order load-bearing (a worker's in-flight resources must release before the pipeline manager drops the pipelines they may still be reporting on). `test_teardown_callbacks_run_lifo` pins LIFO *among* callbacks only. Replacing the three explicit lines with `self.pipeline_manager.teardown(); super().teardown()` reads cleaner, inverts the documented order, and passes everything.
-
-A test would need an ordering probe across all three phases — a plugin callback, an injected pipeline manager, and a runtime-teardown observer appending to one list. Worth doing when the Temporal worker's teardown path is next touched, since that is the integration the order exists for.
-
-## 5. The `MetaSingleton.get_subclass_instance` copy-fix is unpinned
-
-`pipelex/system/registries/singleton.py` changed `for subclass, instance in cls.instances.items()` to iterate `list(cls.instances.items())`, justified by a four-line comment: `instances` is a process-global dict that grows at run time (`GraphTracerManager` registers itself during a pipeline run) and this lookup sits on the boot hot path `ensure_pipelex_booted` reaches from concurrent threads.
-
-Reverting the `list(...)` leaves the whole suite green. The two concurrency tests in the tree — `tests/unit/pipelex/runtime_bridge/test_bootstrap_concurrency.py` — patch `Pipelex.get_optional_instance` and `Pipelex.make` out entirely, so they never reach the metaclass.
-
-Not fixed because a deterministic test needs a `base_cls` whose `__instancecheck__` or `__subclasshook__` inserts a key into `MetaSingleton.instances` mid-scan, plus a `finally` restoring the process-global dict. That is a test about CPython's dict-mutation semantics wearing a Pipelex costume, and the copy is a one-word defensive change with no downside. The honest position is that this is defence-in-depth rather than a pinned invariant; if it is ever removed as "unused", nothing will notice.
-
-## 6. `config_dir` is pinned as "reaches the loader", not as "bypasses layering"
-
-`tests/unit/pipelex/test_runtime_boot_config_dir.py` writes one overridden leaf into a temp dir and asserts it landed. That passes identically if `config_dir` were merely an *extra highest-priority layer* rather than a replacement for project/global layering — which is the half the docstrings actually promise.
-
-Two reasons it is left alone. First, the assertion belongs at `ConfigLoader.load_config`, not at the boot: it is a property of the layer list, and asserting absence at boot level needs a leaf that differs between `pipelex/pipelex.toml` and the project `.pipelex/pipelex.toml`, of which there is currently none committed. Second, the bypass is genuinely *not* total under pytest — `load_config` appends `tests/pipelex_{run_mode}.toml` on both branches — so a boot-level test would be pinning a statement that is true in production and false in the harness running it.
-
-## 7. `test_gateway_terms_check.py` stubs a `RemoteConfigSource` as a bare string
-
-`test_needs_inference_false_does_not_raise_when_terms_not_accepted` sets `mock_result.source = "fresh"` where the contract is a `RemoteConfigSource` (the session conftest uses the real enum). `setup()` therefore dies at `gateway_config_source.is_cached` with an `AttributeError` about ten lines past the gate the test exists for, and the trailing `except Exception: pass` swallows it.
-
-The test still does what its name says — the gate is reached and does not raise — but the swallow is wide enough that it cannot distinguish "gate skipped correctly" from "gate never reached", so a future reordering that moves an unrelated failure ahead of the gate would leave it green and blind. It also calls `setup()` on a `Pipelex.__new__(Pipelex)` with no `__init__`, which is what keeps the damage contained.
-
-Pre-existing (this branch only renamed the module constant it patches), and left alone because the one-line stub fix moves the swallowed `AttributeError` from one unasserted line to another without adding coverage. The real fix is to assert the specific expected failure instead of swallowing, which is a rewrite of the test's contract.
diff --git a/wip/boot-split/boot-split-tracker.md b/wip/boot-split/boot-split-tracker.md
deleted file mode 100644
index 195d5994e..000000000
--- a/wip/boot-split/boot-split-tracker.md
+++ /dev/null
@@ -1,259 +0,0 @@
-# Boot split — the composition root gets the same layer seam as everything else
-
-**Status: ARCHIVED — track complete and merged.** Archived here from the repo-root `TODOS.md` on 2026-07-30, once [PR #1073](https://github.com/Pipelex/pipelex/pull/1073) squash-merged into `dev` as `8448c5ca2` and branch `refactor/Boot` was deleted. Branch was cut off `dev` at `96b992786`.
-
-This document is the reviewer's guide and the as-built record: what the change does, why, what was decided and why, and where a reviewer pushed hardest. The deferrals it names are still open and sit beside it in this folder — see [`README.md`](README.md). Nothing here is an open action; the only work left from this track is the required cross-repo follow-up recorded below.
-
-## Final state at merge
-
-**Merged:** [PR #1073](https://github.com/Pipelex/pipelex/pull/1073) → `dev`, squash `8448c5ca2`, 2026-07-30. The round-8 `/review` fixes described below are **in** that squash (`test_runtime_boot_teardown_resilience.py` arrives with it).
-
-- CI on the final head: **21 pass / 0 fail** (3 conditional jobs skipped). Greptile Review check passed, Codex found "no major issues", **0 unresolved review threads**.
-- Local gates green on the merged tree: `make agent-check` (pyright 0, mypy clean, keyword-only, hub-layering), full `make agent-test`, `make drift-check`.
-- The headline measurement was reproduced independently: `import pipelex.runtime_boot` → **356** modules / **0** interpreter; `import pipelex.pipelex` → 619.
-
-**One item survives the merge:** the required cross-repo follow-up on `pipelex-temporal` and `pipelex-transport` (see below) — separate repos, deliberately out of scope for the PR, still open.
-
-⚠ Every commit SHA below other than `8448c5ca2` is a **pre-squash branch commit**. `refactor/Boot` is deleted, so they survive only as unreferenced objects locally (until GC) and permanently on the PR — read them through [#1073](https://github.com/Pipelex/pipelex/pull/1073), not `git log`.
-
-### How the review procedure ran
-
-The prescribed review procedure was run to completion. Three sub-agents were fanned out, none with inherited context:
-
-1. **Opus bot-feedback triage** — polled CI to terminal, collected every thread (resolved and unresolved) plus both bots' review bodies, deduplicated, and verified each claim against source rather than trusting the bot. Verdict: CI all green; of 13 distinct items, 12 already addressed; **one live clear win.**
-2. **Adversarial review of the boot split** — nine findings, confirming the triage agent's one and adding accuracy defects.
-3. **Test-quality review** — traced every new behavioural assertion back to the `dev` code it pins. **Found no vacuously-passing test**; all eight fail if their fix is reverted, all five repointed `mocker.patch` targets resolve to real bindings, no order dependence under `-n 4`. Its findings are coverage gaps and one wrong comment.
-
-**What `62249bd6a` fixed from those reports:**
-
-- **The teardown wedge** (all three agents, independently). A raising step in `_teardown_runtime` skipped the release block at its end, leaving the boot registered with **no recovery** — `teardown_if_needed` resolves the same instance and re-enters the same raiser. Same for `Pipelex.teardown`'s middle phase. Both now `try`/`finally`, no `except`. Pre-existing on `dev`; this branch had fixed the identical flaw one method away and left its sibling bare.
-- **The same-class boot guard.** The guard sat only in `__init__`, which `MetaSingleton` skips for an already-registered class, so a second `RuntimeBoot.make()` silently re-ran the whole `setup()` on the live boot while its docstring promised a `PipelexSetupError`. Neither cross-class test could see it. Now checked before the construction in both `make()`s, single-sourced.
-- **`get_subclass_instance` iterating a live process-global dict** (its sibling already copied).
-- **Five claims that were wrong, not merely thin** — including a comment asserting a mutation result that is the *opposite* of what the mutation does (verified by re-running it).
-
-**Two new deferrals** in `wip/boot-split/`, per the no-over-engineering bar: `pipelex-setup-narrows-the-runtime-boot-contract.md` (an LSP narrowing whose every remedy trades one wart for another) and `boot-split-test-coverage-gaps.md` (four gaps whose fixes are decisions, not patches — notably that the closure subprocess boots outside the harness and reads the developer's real `~/.pipelex`).
-
-### ⚠ Read this before spawning any more sub-agents
-
-**A review sub-agent reverted the working tree twice mid-session** — `git stash` / restore to `d845f7dad` — to probe pre-fix behaviour. It destroyed a new test module, a CHANGELOG entry, and two source fixes, and it did so while a `make agent-test` run was executing against the tree. All of it was reconstructed and re-verified, and the agent was stopped.
-
-**Any future review fan-out must be told explicitly: read-only. No `git stash`, `git checkout --`, `git restore`, `git clean`, and no edits to tracked files. To compare against earlier behaviour, use `git show <rev>:<path>`.** The instruction to hand it "only a pointer to the changes under review" is not enough on its own — a pointer plus write access invites exactly this.
-
-The read-only instruction above was then given to all four `/review` sub-agents and none of them touched the tree. It is the durable lesson from this track — carry it into every future review fan-out.
-
-### Round 8 — the `/review` pass, and the fix that traded loud for silent
-
-Four read-only sub-agents (testing, maintainability, security, performance) plus an adversarial pass. Performance found nothing. The two that matter both landed on the **same commit that fixed the round-7 wedge**, from opposite directions.
-
-**The one behavioural fix.** `62249bd6a` moved `_teardown_runtime`'s de-registration into a `finally` and stopped there. That is what makes the *next* boot succeed — so the releases still sitting in the `try` above a raising step stopped being a dangling-resource problem and became a **silent-corruption** one. `KajsonManager` is the sharp one: it is a singleton, so a surviving manager makes the next boot's `KajsonManager(class_registry=…)` hand back the old manager and discard the fresh registry. That boot then serves the previous boot's classes, registers its own into a registry nothing resolves to, and reports `is_ready`. On `dev` the identical raiser failed loudly on "already initialized". Verified end to end: `runtime_hub.reset_config()` calls `log.reset()` (so `log.configure` does not refuse), and `TemplateLoader.register_set` is idempotent (so nothing else fails loudly either) — the boot really does complete. `KajsonManager.teardown()`, `TemplateLoader.reset()` and `TemplateRegistry.clear()` moved into the `finally`, matching `_release_after_failed_boot` exactly; all three are idempotent. Pinned in `test_runtime_boot_teardown_resilience.py`, negative control run individually.
-
-**The lesson is the round-7 lesson again, one level up.** Round 7 recorded "fixing a bug class on one path and leaving its sibling". This was fixing *part of a release list* on one path and leaving the rest — and the partial fix was worse than none, because it removed the loud failure that had been covering the silent one. When a fix's whole justification is "these releases must not be skipped", the unit is the release **set**, not the statement that happened to be named in the report.
-
-**Also applied:** the plugin-callback phase moved inside the same `try` on both teardown paths (`except Exception` per callback does not cover `BaseException` — the argument `_release_after_failed_boot` already made and its two siblings had not). Plus seven comment/doc accuracy fixes, the sharpest being `runtime_boot.py`'s claim that `KajsonManager` "overwrites unconditionally" — it does the exact opposite, and line 721 of the same file said so. Two were the *same* sentence in two places (`config_loader.load_config`'s `config_dir` docstring still carried the wording this branch corrected in `RuntimeHub.setup_config`) and two were stale doc references the earlier sweeps missed because they say `pipelex.py`, not `pipelex/pipelex.py`.
-
-**Not applied, deliberately:** the `619 → 356` module counts stay in the CHANGELOG (a point-in-time measurement, not an enumeration count); the `make()` lifecycle duplication between the two halves stays (factoring it is the "no new abstraction over the two boots" non-goal). Three new coverage gaps are recorded in `wip/boot-split/boot-split-test-coverage-gaps.md` rather than fixed.
-
-**Cross-repo, re-verified with `git -C <repo> grep` over every repo enumerated from disk:** still exactly the two known breaks, `pipelex-temporal/tests/conftest.py:86` and `pipelex-transport/tests/conftest.py:89`. Nothing new.
-
-**How the review loop has been run** (worth continuing — every round but one produced at least one genuine defect):
-
-1. Read every unresolved thread; **verify the claim against the source before acting.** Several bot findings were right about the mechanism and wrong about severity; two were right about a mechanism I had reasoned about incorrectly; and one sub-agent finding, re-run by hand, was right where my own committed comment was wrong.
-2. Fix only clear wins. Defer genuine design tradeoffs as `.md` in `wip/boot-split/` with an analysis and a suggested shape.
-3. For every behavioural fix, **write the negative control**: revert the fix and confirm the new test fails. Do it per fix, not for the pair — reverting both at once proves only that the pair is needed. This caught a vacuous test and confirmed six real ones.
-4. Reply on the thread with the reasoning (including where my own earlier reasoning was wrong), resolve it, re-run gates, commit, push, ping both bots.
-
-**Three recurring mistakes of mine, if more findings arrive:**
-
-- **Cost misjudgement drove two wrong deferrals.** The telemetry singleton I deferred as "needs its own test matrix" was one guarded call; the `config_dir` propagation I priced at four lines needed a public abstract interface widened. *Write the patch to price it*, then decide.
-- **Reasoning from a concrete class's guarantees about a call through an injectable abstract type.** Bit three times now, on three different methods. Anything typed `…Abstract` or `…Protocol` that a caller can inject must be treated as unbounded — and that includes `teardown`.
-- **Fixing a bug class on one path and leaving its sibling.** The teardown wedge existed *next to* the failed-boot path whose 16-line comment explains precisely why it needs `try`/`finally`. When a fix is justified by a general argument, grep for every site the argument covers.
-
-**Five deferrals are recorded** in `wip/boot-split/`: `runtime-boot-external-interpreter-orchestrator.md`, `config-dir-does-not-scope-inference-paths.md`, `failed-boot-does-not-release-every-resource.md`, `pipelex-setup-narrows-the-runtime-boot-contract.md`, `boot-split-test-coverage-gaps.md`. Each has the analysis and a suggested remedy.
-
-**One required cross-repo follow-up** (separate repos, out of scope for this PR): `pipelex-temporal/tests/conftest.py:86` and `pipelex-transport/tests/conftest.py:89` patch `"pipelex.pipelex.load_pipelex_service_config_if_exists"` in autouse session fixtures; that symbol is now in `pipelex.runtime_boot`, so both suites break at session start once they pick this up. ⚠ Use `git -C <repo> grep` for any cross-repo sweep here — the environment's `grep` is a **shell function** that does not traverse sibling repos and silently returns zero.
-
----
-
-## What this branch does
-
-`pipelex/pipelex.py` is split into two composition roots:
-
-- **`pipelex/runtime_boot.py`** (new) — `RuntimeBoot`: config, logging, the secrets provider, telemetry, the Kajson class registry + `CoreRegistryModels`, the template sets, `sdk_client_manager`, the model deck, the plugin-derived runtime registries, storage, the content generator, the inference manager, the reporting delegate, the observers, and the runtime slot claims. **Loads zero interpreter modules.**
-- **`pipelex/pipelex.py`** — `Pipelex`, unchanged address and unchanged public surface, now `class Pipelex(RuntimeBoot)`. It adds the `InterpreterHub`, the composed plugin manifests, the `PipeFuncExecutorRegistry` and its executor, the `LibraryManager` and default library dirs, the `PipelineManager`, the `PipeRegistryModels` registration, the `PipeRouter` and the `PipeRun`.
-
-## Why
-
-Pipelex has two layers and one hub each, enforced two ways: `check-hub-layering` owns the rule (no runtime-layer module imports `interpreter_hub`) and `test_runtime_layer_import_closure.py` owns the property it buys (importing the Pipelex runtime loads zero interpreter modules). Every package in the tree had been placed on one side of that line and pinned there.
-
-**The composition root never got the treatment.** It boots both layers in one interleaved sequence, so it is interpreter-layer by construction and sat entirely *outside* the declaration — and an undeclared module is not neutral, it is unpoliced. Two consequences:
-
-1. **The property was real for importing and vacuous for booting.** The entry point every embedder actually calls — `Pipelex.make()` — loaded the interpreter unconditionally. There was no way to boot the runtime layer at all.
-2. **The interleaving was undocumented and unenforced, so it would rot.** The interpreter constructions were sprinkled through `setup()` at four separate points with no marker saying so. Nothing told the next person which half a new boot step belonged in, and nothing caught a wrong answer. Now the wrong answer is an import in a declared runtime-layer module, and the guard names it.
-
-The shape has a worked in-tree precedent: the built-in plugin manifests were split exactly this way (runtime half in a declared runtime-layer home, interpreter half importing it downward and welding the two), which `docs/contribute/hub-layering.md` §"Placement, not coupling" prescribes and the layer-placement track applied three more times.
-
-## Measured payoff
-
-| | modules | interpreter modules | SLOC (non-blank) |
-|---|---|---|---|
-| `import pipelex.pipelex` | 619 | 172 | 60,026 |
-| `import pipelex.runtime_boot` | **356** | **0** | 27,630 |
-
-**The zero is the gate**, via a new closure entry point. The module and SLOC deltas are context, not gates. Reproduce — note the trailing dot in `'pipelex.'`, which is the convention the closure test uses; dropping it also counts the bare `pipelex` package and gives 357/620:
-
-```bash
-.venv/bin/python -c "import importlib, sys; importlib.import_module('pipelex.runtime_boot'); print(len([m for m in sys.modules if m.startswith('pipelex.')]))"
-```
-
-The projection made before any code was written was 356 / 0. It matched exactly, because the runtime half of the boot sequence already reached no interpreter module — so the split needed **no** deferred imports, no function-local `# noqa: PLC0415`, and no new indirection. Every import stays at module top level.
-
-## The load-bearing decisions
-
-**Inheritance, not composition.** `Pipelex` subclasses `RuntimeBoot` rather than holding one.
-
-- Every attribute address is preserved — `self.models_manager`, `self.class_registry`, `self.telemetry_manager`, `self.kajson_manager`, `self._plugin_registrar` all read the same from both halves — so no consumer inside or outside this repo changes. Composition would rename all of them for no architectural gain.
-- It reads as what it is: the interpreter boot *is* the runtime boot plus the interpreter constructions.
-
-**The singleton resolves by subclass.** `RuntimeBoot` carries `MetaSingleton` too, and the class-level accessors go through `MetaSingleton.get_subclass_instance` (in-tree precedent: `TelemetryManagerAbstract`, `GraphTracerManager`). Each `make()` asks the **base** class whether a boot exists — not `cls`. That is what makes the two mutually exclusive in *both* directions: asking `cls` would let `Pipelex.make()` boot on top of a live bare `RuntimeBoot`, because `get_subclass_instance(Pipelex)` cannot see one, and it would then quietly serve that boot's half-populated class registry. `set_runtime_hub`, `KajsonManager` and `log.configure` are all once-per-process.
-
-**Teardown ordering is explicit, not a template hook.** The plugin-contributed callbacks must run LIFO *before* `pipeline_manager.teardown()`, so a worker's in-flight resources release first. `RuntimeBoot` exposes `_teardown_plugin_callbacks()` and `_teardown_runtime()` as separate phases; `Pipelex.teardown` sequences them with its own step between. For a lifecycle this order-sensitive, explicit sequencing beats a base-calls-derived hook.
-
-**The failed-boot release path is shared, not duplicated.** Both `make()`s call `_release_after_failed_boot()`. That block is the subtle part — a partial boot must release process globals it acquired or the next boot raises "LogConfig is already set" and serves a stale registry — and it deliberately touches only entry points safe on a half-built instance. Its docstring records *why* it cannot just call `teardown()`: `teardown` reads `self.inference_manager` (and `self.pipeline_manager`) unguarded, and both are assigned partway through `setup()`. That is intentional — guarding them would let a half-built teardown look successful.
-
-## Deliberate behaviour changes
-
-Each has a test; each is in the changelog.
-
-- **A second boot on top of an existing one fails loud.** `Pipelex.make()` refuses when a bare `RuntimeBoot` holds the process globals, and vice versa. The error message names the class that actually holds them, not a hardcoded "Pipelex".
-- **`config_dir` at boot reaches `setup_config`.**
-- **Breaking:** `Pipelex.__init__` takes keyword-only `config_dir` in place of the inert positional `config_dir_path`. Nothing in the workspace constructed `Pipelex` positionally.
-- **Breaking:** `teardown()` no longer propagates a plugin teardown callback's exception. The callbacks are attempted individually and failures are logged, so one bad plugin cannot strand another's resources.
-
-## Pre-existing bugs fixed (flag-and-fix)
-
-- **`config_dir` was silently ignored.** Stored at `pipelex.py:123` as `config_dir_path` and never read again; `setup_config` was called without a `config_dir` even though `runtime_hub.setup_config` accepts one. An embedder passing an explicit config dir got ordinary project/global layering and no error.
-- **`is_pipelex_service_enabled` was permanently a lie.** Assigned `False` in `__init__` with the comment "Will be set during setup", but `setup()` only ever assigned a **local** of the same name. Nothing in the tree or any sibling repo read it. Deleted rather than wired — a public attribute that always answers `False` is worse than no attribute.
-- **`make()`'s `pipeline_manager` was annotated with the concrete `PipelineManager`** while `setup()`'s was `PipelineManagerAbstract`. Aligned on the abstract, as every other injected manager is.
-
-Also noted and deliberately left alone: `teardown()` reads `self.pipeline_manager` and `self.inference_manager` unguarded, so teardown on a half-built instance raises `AttributeError`. That is *why* `make()` carries its own release path; guards there would let a half-built teardown look successful. The reason is now recorded in the release helper's docstring so the next reader finds the reason rather than the symptom.
-
-## How it is pinned
-
-- **Declared:** `pipelex.runtime_boot` in `RUNTIME_LAYER_PACKAGES`, a **module** entry beside `pipelex.runtime_hub`. Declaring it is the entire reason the rule reaches it.
-- **Membership asserted both ways:** `test_the_boot_split_left_the_runtime_half_declared` requires the runtime half to stay declared *and* `pipelex.pipelex` to stay undeclared. Deletion is the silent regression — the neighbouring checks all *iterate* the tuple and say nothing about a name that is simply gone. And declaring `pipelex.pipelex` would make the layer rule fail by design, so "surely the boot should be runtime-layer" is a plausible future edit worth catching.
-- **Import closure:** `"pipelex.runtime_boot"` added to `RUNTIME_LAYER_ENTRY_POINTS`.
-- **Boot closure:** `tests/unit/pipelex/test_runtime_boot_closure.py` *runs* `RuntimeBoot.make()` in a subprocess and asserts zero interpreter modules loaded, no `InterpreterHub` installed, and `class_registry_scoping` left at its unscoped default.
-
- **The subprocess is required, not preferred.** Both hubs are sticky class-attribute singletons (`RuntimeHub._instance` / `InterpreterHub._instance`) that teardown deliberately never clears, so once anything in a process has booted a `Pipelex`, an in-process `InterpreterHub.get_optional_instance()` answers with the stale hub forever and the assertion **passes vacuously**. And *booting* rather than importing is what catches a boot step resolving out of an interpreter-contributed registry — see the next section.
-
-## The one thing worth reviewing hardest
-
-**Empty registries on a runtime-only boot.** A runtime-only `build_registrar` sees `RUNTIME_BUILTIN_PLUGINS` alone, so the `direct` orchestrator, the direct bundle validator and the built-in PipeFunc executor modes are all absent: `OrchestratorRegistry` and `BundleValidatorRegistry` are constructed **empty**. That is harmless only because nothing in the runtime half *resolves* out of them at boot. Verified per-site rather than assumed:
-
-- The only two runtime-half sites that resolve out of a plugin-derived registry are secrets (`secrets_provider_registry.get_required`) and storage (`storage_provider_registry.get_required`). Both are runtime-contributed *and* core-unconditional — `StoragePlugin`/`SecretsPlugin` are in `RUNTIME_BUILTIN_PLUGINS`, and `storage`/`secrets`/`openai` are in `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES`.
-- `OrchestratorRegistry` / `BundleValidatorRegistry` are only constructed and set on the hub, never resolved at boot; they are looked up at run time by the interpreter.
-- The `TASK_MANAGER`, `ISOLATED_EXECUTION_PROBE` and `CONTENT_GENERATOR` slots are `slot_claims` lookups that no-op or fall to a core default when unclaimed.
-- `build_registrar` uses `core_unconditional_plugin_names` **only** as a may-not-be-denylisted guard, so passing the `RUNTIME_*` pair requires nothing interpreter-side to be present.
-
-The closure test cannot catch a *runtime resolution* failure, which is exactly why the booted-runtime test boots instead of importing.
-
-**Boot-orchestrator gate on a runtime-only boot.** `plugins.boot_orchestrator` defaults to `None` (`configs.py:250`, absent from every TOML), so the gate does not fire on a default runtime-only boot. When config *does* name an interpreter-contributed orchestrator, the existing check raises `UnknownBootOrchestratorError` unchanged — the decided behaviour, since a process with no interpreter genuinely cannot honour that runtime. No code change; the reason is a comment at the gate.
-
-**The interleaving assumption.** The whole plan rested on the interpreter constructions being deferrable to the tail. They were, confirmed per-site and then by the full suite. Two specific confirmations: `PipelineManager.setup()` is a literal `pass`, and `LibraryManager.__init__` is pure dict initialisation — so neither depends on the class registry being populated, which is what makes it safe for them to move *after* the `CoreRegistryModels` registration they used to precede. The two values that cross the seam go the other way (`self._plugin_registrar` and `self.multi_observer`, built by the runtime half and read by the tail).
-
-**A registration-order consequence, verified inert.** Old order was Core → Pipe → Test; it is now Core → Test (runtime half) → Pipe (interpreter tail). `kajson`'s `register_classes` is name-keyed dict insertion, `TestRegistryModels` holds only `FictionCharacter`, and `test_registry_models_split.py` already pins the manifests pairwise name-disjoint *order-independently*. It is also not fixable without making the layering wrong: `test_extras` is declared runtime-layer, so its registration belongs beside `CoreRegistryModels`.
-
-## Deliberate non-goals
-
-- **No `boot/` package.** Two top-level modules mirroring `runtime_hub.py` / `interpreter_hub.py` — the tree's strongest naming precedent for a layered pair, and it needs no top-level-package accounting in the guard's docstring.
-- **`Pipelex` does not move and is not renamed.** It is the public entry point every consumer and sibling repo imports; the boundary never required moving it.
-- **No parameter-list refactor.** `setup()`/`make()` duplicate a long typed parameter list and the split adds a second copy of the runtime subset. That is the cost of two typed entry points; a kwargs-forwarding fix would trade typing for brevity.
-- **No new abstraction over the two boots.** No protocol, no factory, no registry. The interpreter boot subclasses the runtime boot; that is the whole mechanism.
-- **Doctor was assessed and deliberately not adopted.** `setup_doctor_runtime` is the tree's only other bare-`RuntimeHub` builder, but its needs are **not** a strict subset: it requires `log.configure_if_unset` rather than `configure` (pinned by `tests/unit/pipelex/tools/test_log_idempotence.py`), a `log_config_overrides` deep-merge the agent doctor uses to keep its JSON envelope clean, and specifically *not* an `SdkClientManager` — doctor exists to report on models/plugins/inference without standing them up. Two flag parameters and an unwanted construction to de-duplicate ~10 lines is a worse outcome than two short sequences that differ honestly.
-
-## Honest scoping
-
-This fixes no bug in the layering and unblocks no feature. The guard was green before and stays green — nothing runtime-layer imports `pipelex.pipelex`, so there was no violation to remove. What changes is that a capability becomes expressible and a boundary maintained by discipline becomes maintained by a test.
-
-The fair reviewer question is "who calls the runtime-only boot?" The honest answer: the pinned closure and booted-runtime entry points in this PR, and any embedder wanting inference + storage + models without the method machinery. That is the same shape as `RUNTIME_BUILTIN_PLUGINS`, which the plugin split created with zero importers — and which is load-bearing here, as its first caller.
-
-## Verification performed
-
-- `make agent-check` — ruff, `generate-mthds-schema`, plxt, pyright (0 errors), mypy (2385 files), `check-keyword-only`, `check-hub-layering`. All green.
-- `make agent-test` — full suite passes. This is the proof the interleaving was incidental.
-- `make tb` — green.
-- `make drift-check` — green; `hub-layering-convention` reviewed and acked, with a dogfood-log entry. The contract's prescribed mechanical check **caught a real gap**: `pipelex.runtime_boot` was missing from the doc's enumeration of the declared runtime layer. Fixed. Seven consecutive rounds where an enumeration on that page was the rot, and three in a row where it was that same enumeration — the log now names automating it as the clearest candidate the pilot has produced.
-- **Cross-repo**, redone with `git -C <repo> grep` over repos enumerated from disk. `pipelex-transport`'s `ALLOWED_SURFACE` names no boot/runtime module, and zero references anywhere outside this repo touch either removed surface (`config_dir_path`, `is_pipelex_service_enabled`). Most downstream references are `from pipelex.pipelex import Pipelex` or `pipelex.pipelex.Pipelex.make(...)` — the *class*, which does not move — and keep working.
-
- ⚠️ **Two real downstream breaks, which the first sweep missed.** `pipelex-temporal/tests/conftest.py:86` and `pipelex-transport/tests/conftest.py:89` each `session_mocker.patch("pipelex.pipelex.load_pipelex_service_config_if_exists", …)` in an **autouse session fixture**. That symbol now lives in `pipelex.runtime_boot`, so both suites `AttributeError` at session start — total suite failure, not a subtle one. Both pin `pipelex>=0.40.0` as a floor with no `tool.uv.sources` override, so it arrives at the next routine lockfile refresh rather than only at a deliberate bump. **Required cross-repo follow-up** (separate repos, so out of scope for this PR): repoint both strings to `pipelex.runtime_boot.load_pipelex_service_config_if_exists`.
-
- **Why the first sweep missed them — the methodology matters more than the result.** `grep` in this environment resolves to a **shell function**, not `/usr/bin/grep`, and it does not traverse sibling repos: a recursive `grep -r` from the workspace root returned zero and read as a clean bill of health. That is the same failure shape as a hardcoded repo list — a repo the instrument never reached is indistinguishable from one that came back clean. `git -C <repo> grep` per enumerated repo is both correct and fast, and is the instrument to use for any future cross-repo sweep here.
-
-**Test-side fallout was mechanical:** six `mocker.patch` targets named `pipelex.pipelex.<symbol>` for symbols that now live in `runtime_boot`, repointed, with the shared four-file constant renamed `RUNTIME_BOOT_MODULE`. Those string references are invisible to every import lint — the hazard the guard's own docstring calls out.
-
-## Review already applied
-
-An independent reviewer with no context on the plan raised four findings against the staged diff. Three were accepted and fixed:
-
-1. **Three `TestClass`es in one module** — violates `pytest_standards.md` ("NEVER EVER put more than one TestClass into a test module"), which is not lint-gated. Split into `test_runtime_boot_closure.py`, `test_runtime_boot_exclusivity.py`, `test_runtime_boot_config_dir.py`. The 2-line `_test_integration_mode()` helper is duplicated across the two files needing it rather than hoisted — that is what `test_hub_lifecycle.py` already does with the same helper, so a shared helper module would be the novel thing, not the duplication.
-2. **A fresh dead attribute `self.config_dir`** — set in `__init__`, read nowhere. Not a functional bug (the local parameter is what reaches `setup_config`), but it re-created the exact trap this PR removes twice over. Deleted, with a comment recording why the boot deliberately keeps no copy.
-3. **Hardcoded "Pipelex" in `RuntimeBoot`'s error messages** — a lie for an embedder that never touched `Pipelex`. Both messages now name the real class. The sharpest part of the finding was that *nothing caught it*, since the test asserted only the exception type; the exclusivity test now asserts the wording, and a second test pins the reverse direction.
-
-The fourth was the registration-order consequence above — verified inert, not fixable without misplacing `test_extras`, and explicitly not a requested fix. Recorded so it is known rather than rediscovered.
-
-Codex then raised a fifth on the PR, **verified correct and deliberately deferred**: a runtime-only boot rejects an interpreter-layer orchestrator contributed by a *built-in* (it is never registered, since `builtin_plugins` defaults to the runtime half) but **not** one contributed by an *external* entry-point plugin, because `build_registrar` discovers externals unconditionally. Such a boot would apply the plugin's runtime claims — including `TASK_MANAGER` — never apply its `PIPE_ROUTER` / `PIPE_RUN` / `PIPE_FUNC_EXECUTOR` claims, and still report ready.
-
-Not fixed here for three reasons: it needs an external interpreter-side orchestrator installed *and* configured *and* a caller of `RuntimeBoot.make()`, of which there are none; every remedy needs a layer signal the runtime layer deliberately does not have (a `PipelexPlugin` carries no layer field, by design); and the nearest clean remedy is a flag on the very class pair that exists to avoid flags — which would contradict the doctor-adoption decision taken twenty lines away in the same file. The gate's comment now states the hole precisely instead of overclaiming (it previously said the runtime-only boot "also rejects an interpreter-contributed orchestrator name, which is correct" — true for built-ins, false for externals, so the comment was the actual defect). Full analysis and two candidate remedies: [`runtime-boot-external-interpreter-orchestrator.md`](runtime-boot-external-interpreter-orchestrator.md).
-
-### Round 7 — the same mistake twice, named
-
-Codex found a third defect on the failed-boot path, and it is worth recording because it is the **same reasoning error** as the round-6 one, one line away.
-
-My telemetry release call sat as the first statement in the `finally`, justified by a comment citing the built-in `TelemetryManager`'s "telemetry teardown must never break the app" property. But `self.telemetry_manager` is whatever the *factory* produced, and `telemetry_manager` is a public `make()` injection point typed only as `TelemetryManagerAbstract` — so an injected implementation carries no such guarantee. Unisolated, a raising one skips every release below it and replaces the boot error going out.
-
-**The generalisable mistake: reasoning from a concrete class's guarantees about a call made through an injectable abstract type.** Round 6 was the granularity version of it (catching around a loop over unbounded callbacks); this is the identity version. Both are now isolated per-call, and the comments say why rather than asserting safety.
-
-Pinned by `test_an_injected_telemetry_manager_that_raises_does_not_abort_the_other_releases`. Two things about its construction are deliberate: it patches `TelemetryFactory.make_telemetry_manager` rather than passing `telemetry_manager=`, because the injection is only adopted in some telemetry/integration modes and the subject is the resulting *state*; and it proves the suite completed by asserting the **singleton de-registration**, which is the suite's last statement, rather than by re-booting — which also keeps the patched factory from leaking into a second boot. Verified as a real control: reverting the isolation fails it.
-
-### Round 6 — Greptile back to 5/5; Codex found the granularity bug in my round-4 fix
-
-Codex's last finding is a consequence of the fix I made two rounds earlier, and it is a good one: my `except Exception` sat around the **loop** rather than inside it, so the first raising callback (LIFO, i.e. the last registered) ended the loop and every remaining callback was skipped. With two plugins registered — Temporal plus a sandbox executor is the realistic pair — the second one's runtime stayed live while the log said only that one callback had failed.
-
-"Catch around the loop" and "catch per iteration" look equivalent and are not, which is exactly why this needed a test rather than a re-read. Fixed by moving the catch inside the loop; the outer one became dead and was removed, though the `try`/`finally` stays, because `except Exception` does not cover `BaseException` and the state releases must still run if a teardown is interrupted.
-
-Pinned by `test_one_raising_teardown_callback_does_not_skip_the_others`, which registers the raiser **last** so LIFO reaches it first — the ordering that strands the others. Verified as a real control: restoring the around-the-loop catch fails it with "a raising callback skipped the remaining teardown callbacks".
-
-**Third deliberate behaviour change, now declared:** `teardown()` no longer propagates a plugin callback's exception. That follows from making the loop best-effort, and it is the right semantics — no caller can act on "plugin B failed to release", while every caller is harmed by B never being asked. Same shape as `TelemetryManager.teardown`, which wraps each of its own shutdown steps for the same reason.
-
-### Round 5 — Greptile blocked on the deferred telemetry leak, and it was right to
-
-Greptile dropped from 5/5 to **3/5** and said the PR should not merge until the failed-boot cleanup clears the telemetry singleton — the item the pre-landing review had raised and I had deferred. Two independent reviewers on the same defect, one of them blocking, so I re-examined the deferral and **it was wrong on cost**.
-
-`TelemetryManager.teardown()` already ends with `TelemetryManagerAbstract.clear_instance()`, and its internals are each wrapped defensively with the comment "telemetry teardown must never break the app". So the fix is **one guarded call** on a path that already guards the same attribute — not the "change to failure-path semantics with its own test matrix" I had described. I had conflated the narrow fix (release the singleton) with the broad one (collapse the two teardown paths), and deferred both on the strength of the broad one's cost.
-
-Fixed, and pinned by `tests/unit/pipelex/test_runtime_boot_failed_boot_release.py`: an injected models manager whose `setup()` raises reproduces the real shape (telemetry is already live by then), and the test asserts no telemetry singleton survives. Verified as a real control — with the release reverted it fails on exactly that assertion.
-
-What remains deferred is genuinely narrower and of a different kind: `sdk_client_manager`, `reporting_delegate` and `func_registry` are still not released on a failed boot. Those leave resources dangling rather than corrupting the next boot, and adding three more calls would widen a second hand-maintained copy of the teardown list. The right fix is to collapse the two paths, which is a lifecycle decision — [`failed-boot-does-not-release-every-resource.md`](failed-boot-does-not-release-every-resource.md).
-
-### Codex round 4 — two more, one fixed and one deferred after being attempted
-
-1. **Fixed: the `try`/`finally` still let a teardown error replace the boot error.** The `finally` guaranteed the releases, but a raising plugin callback propagated out of `_release_after_failed_boot()`, so `make()`'s bare `raise` was never reached and the caller saw the *teardown* failure instead of the one that killed the boot. This refines a judgement I had made and stated on the previous round — I declined to catch, reasoning that "the five existing operations have the same property, so it's all six or none." That reasoning was wrong on its own terms: only the plugin callbacks are **unbounded third-party code**, everything in the `finally` is ours, so catching exactly one of the six is principled rather than inconsistent — and it is case (2) of this repo's own `except Exception` carve-out (a user-registered callback whose exception surface cannot be enumerated), which requires a naming comment and gets one.
-2. **Deferred after being attempted: `config_dir` scopes the main TOML load but not the inference file paths.** Real: `models_manager.setup()` is called without path arguments, so backends, routing profiles and the model deck still resolve through the layered `config_manager.*` properties — an alternate `config_dir` combines its own main settings with whatever tree is detected. `ModelManager.setup`'s comment already names the remedy, and doctor's `--global` path implements it.
-
- The four-line propagation was written and tested, then **backed out**: those path overrides exist on the concrete `ModelManager`, not on `ModelManagerAbstract`, which is what the boot is typed against *and* a documented `make()` injection point. Pyright rejects the call, and this repo forbids the `cast`/`isinstance` shortcut — the honest fix is to widen the abstract interface, which is a change to a public injection contract and does not belong in a placement refactor claiming unchanged behaviour. Two things learned while attempting it and worth carrying: completing the scoping makes an explicit `config_dir` **require a complete config directory** (verified — a dir holding only `pipelex.toml` then fails with `InferenceBackendLibraryNotFoundError`), which is the correct contract but a deliberate behavioural decision; and doctor spells the four paths as inline literals while `config_loader` already owns them as constants, so a second copy would double a drift risk that should be collapsed instead.
-
- What shipped instead: both `make()` docstrings now state the limit explicitly rather than promising "only this directory is read", the boot carries a `NOTE:` at the call site, and the analysis plus a four-step suggested shape is in [`config-dir-does-not-scope-inference-paths.md`](config-dir-does-not-scope-inference-paths.md) — including that the negative test for it was written on this branch and verified to fail on a reverted propagation, so it can be lifted from history.
-
-### Pre-landing review triage (second independent reviewer)
-
-A pre-landing review then found five more, **four of them in the two commits that fixed the earlier findings** — a reminder that a fix commit deserves the same scrutiny as the change it fixes. All five accepted:
-
-1. **`_release_after_failed_boot` ran unbounded plugin code before the un-poisoning, with no `try`/`finally`.** Introduced by the leak fix itself. If a plugin teardown callback raised, the state releases below it never ran — logging stayed configured (every later boot dies on "LogConfig is already set"), `KajsonManager` kept a half-populated registry, the singleton stayed registered — *and* the teardown error replaced the exception that actually killed the boot. The method's entire purpose is to leave the process re-bootable. Now `try: callbacks / finally: releases`, which is the shape `AGENTS.md` prescribes for required cleanup — and the same rule Codex had cited when reporting the leak.
-2. **The exclusivity guard and the release resolved at different classes.** `make()` asked the base (so it saw any boot) but `teardown_if_needed()` asked `cls`, so `Pipelex.teardown_if_needed()` silently no-opped against a live bare `RuntimeBoot` while `Pipelex.make()` kept refusing — a deadlock with no recovery path, reachable from every existing `teardown_if_needed()` call site. Both now resolve at the base: a release must be able to clear everything its matching guard refuses on.
-3. **`__init__` took `RuntimeHub._instance` before any exclusivity check.** `set_runtime_hub` overwrites unconditionally, so constructing a second boot directly clobbered a live boot's hub and only then failed at `log.configure`, orphaning it. `MetaSingleton` used to make this unreachable *by accident* — a second `Pipelex(...)` short-circuits on the registry and never re-runs `__init__` — but a subclass is a different registry key, so the accident stopped covering it. The exclusivity check moved into `__init__`, which holds on every path including direct construction; both `make()` guards were deleted as redundant rather than duplicated.
-4. **The `config_dir` test bypassed `make()`.** Construct-then-`setup()` re-implements what `make()` wraps, and `teardown()` on a half-built instance raises `AttributeError` — masking the real error and leaving the singleton registered for the rest of the xdist worker. Now goes through `RuntimeBoot.make(config_dir=…)`, which already accepts it.
-5. **The booted-runtime test had lost its negative control.** Its sweep lives in a `textwrap.dedent` string, so nothing type-checks the predicate; the sibling import-closure module carries a `DIRTY_ENTRY_POINT` for exactly this reason and the copy dropped it. Verified rather than assumed: changing the sweep's `split(".")[1]` to `[0]` made the module green forever. A control case now treats `cogt` — which the runtime boot loads by definition — as an interpreter package and requires a failure. Re-verified: with the predicate broken, the real case passes and **the control fails**.
-
-A sixth was **pre-existing and deferred**: a failed boot leaves the `TelemetryManager` singleton live, so the next boot in the process adopts the dead one (reachable via `ensure_pipelex_booted`'s per-call lazy boot, since the commonest boot failure — `models_manager.setup()` on a missing deck or credentials — fires *after* telemetry setup). Unchanged from `dev`, and widening the release path is a change to failure-path semantics with its own test matrix, not a comment fix — so it was written up as `wip/inputs/failed-boot-leaks-telemetry-singleton.md` with a suggested shape. (That deferral was **reversed two rounds later** — see "Round 5" below — and the doc was deleted in `760b4a9b3`; what survives of it is [`failed-boot-does-not-release-every-resource.md`](failed-boot-does-not-release-every-resource.md).) What *was* fixed is the docstring, which claimed this path "releases the same process-global state `teardown()` does": it releases a subset, and the "only safe entry points" rationale never explained the omission, since `reporting_delegate` and `telemetry_manager` are already guarded.
-
-Codex raised a **sixth** on the re-review, and this one was accepted and fixed: **a failed boot leaked a plugin runtime.** `_release_after_failed_boot()` released process-global state but never ran the plugin teardown callbacks, so a boot dying after the `TASK_MANAGER` thunk left a live runtime running. Verified that the boot split genuinely widened the window — pre-split the thunk ran at `pipelex.py:524`, *after* the pipe-func executor resolution (471), `pipeline_manager.setup()` (499) and the pipe-class registration (504); all three now follow it. The most reachable trigger is a plain config error (`pipe_func_config.execution_mode` naming an unregistered mode). Fixed by running `_teardown_plugin_callbacks()` first on that path, mirroring the normal teardown ordering. Pinned by `test_a_failed_interpreter_tail_still_runs_plugin_teardown_callbacks`, which asserts the thunk ran *and* the callback ran so it cannot pass vacuously — and which was confirmed to fail with the fix removed.
diff --git a/wip/boot-split/config-dir-does-not-scope-inference-paths.md b/wip/boot-split/config-dir-does-not-scope-inference-paths.md
deleted file mode 100644
index 6d147e10e..000000000
--- a/wip/boot-split/config-dir-does-not-scope-inference-paths.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# `config_dir` at boot scopes the main TOML load but not the inference file paths
-
-**Status:** deferred, with the docstrings narrowed to say exactly what the parameter does. Found by Codex on PR #1073. Attempted on that PR and backed out — the fix needs a public abstract interface widened, which is a decision of its own.
-
-## What it does and does not scope
-
-`RuntimeBoot.__init__(config_dir=…)` passes the directory to `runtime_hub.setup_config(config_dir=…)`, so the **main TOML** load becomes `package defaults + this directory` instead of following project → global layering.
-
-It stops there. `models_manager.setup(...)` is called without path arguments, and `ModelManager.setup` falls back to the layered `config_manager.*` properties when they are `None`:
-
-- `config_manager.backends_file_path` → `inference/backends.toml`
-- `config_manager.backends_dir_path` → `inference/backends/`
-- `config_manager.routing_profiles_file_path` → `inference/routing_profiles.toml`
-- `config_manager.model_decks_dir_path` → `inference/deck/`
-
-Each resolves from the *detected* project or global config dir. So a boot pointed at an alternate `config_dir` combines that directory's main settings with whatever inference tree happens to be detected — cross-contamination between two config trees, silently.
-
-There is a **fifth** unscoped read, and it is not an inference path at all: the gateway consent/onboarding state.
-
-```python
-pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)
-```
-
-That is hardcoded to the global dir, so a `config_dir`-scoped boot still reads `~/.pipelex/` for terms acceptance and `inference_setup_completed` — the two whose absence raises `GatewayTermsNotAcceptedError` / `InferenceSetupRequiredError`. Compounding it, the `config_dir` branch of `load_config` skips `ensure_global_config_exists()`, so a scoped boot never materialises the tree that this line then reads.
-
-Unlike the four inference paths, it is **not obvious that scoping this one is correct**: terms acceptance is per-user consent, and per-user global state is arguably where it belongs no matter which config directory a given boot reads. That is the question to settle first — the fix here may be "document it as intentional" rather than "propagate `config_dir`". It is listed with the others because the *documented limit* had omitted it, not because the behaviour is known to be wrong.
-
-`ModelManager.setup`'s own comment already says this is the intended remedy: *"Override paths let the doctor scope --global properly; default None falls back to layered config_manager paths for all other callers."* The doctor's `--global` path does exactly that, pinning all four with the comment *"so layered config_manager.X resolution doesn't silently fall back to the project-local files."*
-
-## Why it was not fixed on PR #1073
-
-The four-line propagation was written, tested, and backed out for one reason: **the path overrides exist on the concrete `ModelManager`, not on `ModelManagerAbstract`.**
-
-`RuntimeBoot.models_manager` is typed `ModelManagerAbstract` — and that is deliberate, because `models_manager` is a documented `make()` injection point, so an embedder may supply their own. Pyright rejects the call:
-
-```
-error: No parameter named "backends_library_path" (reportCallIssue)
-```
-
-The doctor avoids this only by constructing a concrete `ModelManager()` itself.
-
-This repo's own rule forbids the shortcut: *"When a getter returns a Protocol type, callers must only rely on methods declared on that Protocol. If you need to call a method that lives on a concrete implementation, extend the Protocol — do not work around it with `isinstance`, `cast`, or inline imports."* So the honest fix is to widen `ModelManagerAbstract.setup()` with the four optional path parameters and update every implementation — a change to a public injection contract, which does not belong inside a placement refactor whose whole claim is that behaviour is unchanged.
-
-Two smaller observations that argue for doing it properly rather than quickly:
-
-- Completing the scoping makes an explicit `config_dir` **require a complete config directory**. Verified: with the paths pinned, a directory holding only `pipelex.toml` fails boot with `InferenceBackendLibraryNotFoundError`. That is the correct contract — it is what "only this directory is read" means, and what `~/.pipelex` satisfies because `ensure_global_config_exists` materialises it from kit templates — but it is a real behavioural requirement that deserves to be introduced deliberately, not as a side effect.
-- The four path literals are currently spelled inline in `doctor_cmd.py` (`"inference"`, `"backends.toml"`, …) while `config_loader.py` already owns them as constants (`INFERENCE_DIR_NAME`, `BACKENDS_FILE_NAME`, `BACKENDS_DIR_NAME`, `ROUTING_PROFILES_FILE_NAME`, `MODEL_DECKS_DIR_NAME`). A second copy would double a drift risk that should instead be collapsed.
-
-## Suggested shape
-
-1. Widen `ModelManagerAbstract.setup()` with the four optional path parameters, and update every implementation (`@override` will surface any that drift).
-2. Add a `config_manager` helper that derives the scoped set from a directory — something like `inference_paths_for(config_dir)` returning the four — and use it from **both** `RuntimeBoot.setup` and `doctor_cmd`, replacing doctor's inline literals. That is the step that removes the drift risk rather than duplicating it.
-3. Pin it with the negative that matters: a `config_dir` holding only `pipelex.toml` must **fail** rather than quietly borrowing another tree's backends. That test was written on #1073 and verified to fail when the propagation is reverted, so it can be lifted straight from this branch's history.
-4. Document the "complete config directory required" contract on `config_dir` in both `make()` docstrings.
-
-## What exists today instead
-
-Both `make()` docstrings now state the limit explicitly and point here, so the parameter no longer promises isolation it does not deliver. The boot carries a `NOTE:` at the `models_manager.setup` call naming the same thing.
diff --git a/wip/boot-split/failed-boot-does-not-release-every-resource.md b/wip/boot-split/failed-boot-does-not-release-every-resource.md
deleted file mode 100644
index e7daea634..000000000
--- a/wip/boot-split/failed-boot-does-not-release-every-resource.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# A failed boot still leaves three non-singleton resources unreleased
-
-**Status:** deferred, narrowed. The headline item this file used to describe — the **telemetry manager singleton** surviving a failed boot so the next boot adopted the dead one — is **fixed** on PR #1073 (`_release_after_failed_boot` now calls the guarded `telemetry_manager.teardown()`, which flushes and calls `clear_instance()`), pinned by `tests/unit/pipelex/test_runtime_boot_failed_boot_release.py` and verified to fail when the release is reverted.
-
-A second item has since been fixed too, and it belonged to the *other* path — worth recording because this file used to scope itself to the failed-boot path alone, and that scoping is exactly what let the defect hide. `_teardown_runtime` kept `KajsonManager.teardown()`, `TemplateLoader.reset()` and `TemplateRegistry.clear()` in its `try`, above steps reachable through injectable abstract types, while its sibling had them in the `finally`. Since the same commit also moved the `MetaSingleton` de-registration into the `finally`, a raiser stopped failing loudly on the next boot ("already initialized") and started letting it **succeed against the previous boot's class registry** — the `KajsonManager` singleton hands back the surviving manager and discards the fresh registry. The three releases now sit in `_teardown_runtime`'s `finally` as well, so the *poisoning* half of the two lists is identical on both paths, and `test_runtime_boot_teardown_resilience.py` asserts no `KajsonManager` survives a raising teardown.
-
-**The scope of this note is therefore both paths, not just the failed-boot one.** What remains is smaller and of a different kind.
-
-## What is still not released on a failed boot
-
-`_release_after_failed_boot()` releases the process globals that would otherwise **poison the next boot**: the hub config, `class_registry_scoping`, `KajsonManager`, the template registries, the telemetry singleton, and the `MetaSingleton` registration. It does not release three things that `teardown()` does:
-
-| not released | what `teardown()` does | consequence |
-|---|---|---|
-| `sdk_client_manager` | `.teardown()` | vendor SDK clients constructed during `sdk_client_manager.setup()` are not closed |
-| `reporting_delegate` | `.teardown()` | the delegate's own resources are not released |
-| `func_registry` | `.teardown()` | registrations from this boot persist into the next one |
-
-None of these is a *singleton-identity* bug — that was the telemetry case, where a stale registration silently replaced a fresh construction, and the `KajsonManager` case above. These are ordinary "resources not closed on the error path": the next boot builds its own `sdk_client_manager` and `reporting_delegate`, so it does not inherit broken state, it merely leaves the old ones dangling. `func_registry` is the closest to a real problem, being a module-level global whose entries carry over — and note that it carries over on the **normal** teardown path too, whenever a step above it raises, since it stayed in `_teardown_runtime`'s `try`. That was left alone deliberately: moving it would break the symmetry with `_release_after_failed_boot`, which cannot release it at all, and the symmetry is what makes the two lists reviewable against each other. It is the first thing the collapse below should pick up.
-
-## Why it is deferred rather than patched
-
-Adding three more guarded calls to the failure path is easy but is the wrong shape. `_release_after_failed_boot` exists only because `teardown()` is unsafe on a half-built instance — it reads `self.inference_manager` (and, on the interpreter half, `self.pipeline_manager`) unguarded, deliberately, so that a half-built teardown cannot look successful. Every resource added to the failure path widens a **second, hand-maintained copy** of the teardown list, which will drift from the first.
-
-The better change is to collapse them:
-
-1. Guard `inference_manager` and `pipeline_manager` in `_teardown_runtime` / `Pipelex.teardown` the way `telemetry_manager` and `reporting_delegate` already are.
-2. Have `_release_after_failed_boot()` call the real teardown, keeping its own `try`/`finally` so the process-global un-poisoning still happens even if a manager teardown or a plugin callback raises.
-3. Delete the duplicated list.
-
-The risk to weigh in step 1 is the property the current code deliberately protects: guards let a half-built teardown *look* successful. The mitigation is that on the failure path the caller already knows the boot failed, so "looking successful" is not load-bearing there — unlike in `teardown()`, where it is. That asymmetry is the thing to decide, and it is a decision about lifecycle semantics rather than a missing line.
-
-## Why not on PR #1073
-
-That PR is a placement refactor whose claim is that a full `Pipelex` boot behaves identically. Collapsing the two teardown paths changes what *every* failed boot does for every existing caller and wants its own test matrix. The telemetry singleton was fixed there because it is a different class of defect — a stale singleton silently adopted by the next boot, production-reachable through `ensure_pipelex_booted`'s per-call lazy boot, and closed by one guarded call to an API written to never raise.
diff --git a/wip/boot-split/pipelex-setup-narrows-the-runtime-boot-contract.md b/wip/boot-split/pipelex-setup-narrows-the-runtime-boot-contract.md
deleted file mode 100644
index e200aec28..000000000
--- a/wip/boot-split/pipelex-setup-narrows-the-runtime-boot-contract.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# `Pipelex.setup` narrows its base class's parameter list, and `**kwargs` turns that into a runtime error
-
-**Status:** deferred as a design tradeoff, not applied. Found by an adversarial review pass on PR #1073. Nothing in the workspace hits it; the honest fix is a signature decision rather than a patch.
-
-## What happens
-
-`RuntimeBoot.setup()` documents `builtin_plugins` and `core_unconditional_plugin_names` as part of its contract — they are how a runtime-only boot discovers exactly the runtime half of the built-in plugins. `Pipelex.setup()` is an `@override` that deliberately does *not* accept them, because it supplies its own composed manifests (`BUILTIN_PLUGINS`, `CORE_UNCONDITIONAL_PLUGIN_NAMES`) to `super().setup()`.
-
-It absorbs the difference in `**kwargs: Any` and rejects it:
-
-```python
-if kwargs:
- msg = f"The Pipelex setup method does not support any additional arguments: {kwargs}"
- raise PipelexSetupError(msg)
-```
-
-So `pipelex_instance.setup(integration_mode=…, builtin_plugins=[])` type-checks — `**kwargs: Any` swallows the argument, and pyright sees nothing wrong — and raises at run time. A caller who wrote against the *base* type gets a green type check and a failure in production.
-
-## Why it was not "fixed"
-
-Every candidate remedy trades one wart for another, and the current behaviour is not the worst of them:
-
-- **Accept and ignore them.** Silently discarding a caller's plugin manifests is worse than refusing: they asked for a specific plugin set and would get a different one with no signal.
-- **Accept and honour them.** That contradicts what `Pipelex` *is* — the boot that runs methods, and therefore needs the interpreter-touching built-ins. A caller who wants a different set wants `RuntimeBoot`.
-- **Drop `**kwargs` and let Python raise `TypeError`.** Arguably the most honest, and it makes the narrowing visible to pyright at the call site. But `**kwargs` is doing a second job here — catching typo'd keyword arguments across a 17-parameter surface with a message that names them — and the `TypeError` wording would be worse for the common case.
-- **Split the base signature** so the manifest parameters live on a separate protected method the subclass overrides instead of on `setup()`. This is the actually-correct answer, and it is a change to a public injection contract that does not belong in a placement refactor.
-
-The narrowing is real (`Pipelex.setup` is not substitutable for `RuntimeBoot.setup`), and it is at least *loud* — the failure names the offending argument. Worth revisiting alongside any other work on the `setup()` signature; not worth a workaround on its own.
-
-## What exists today instead
-
-Nothing in the workspace passes either parameter to `Pipelex.setup`, and `Pipelex.make()` — the way essentially every consumer boots — does not expose them at all, so the reachable surface is a direct `setup()` call on a constructed instance.
diff --git a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md b/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md
deleted file mode 100644
index cdfc75037..000000000
--- a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# A runtime-only boot accepts an external interpreter-side orchestrator, then half-applies it
-
-**Status: RESOLVED** by the plugin entry-point group split (Part A of the kernel track). The analysis below is kept for the rationale trail; read the closing section first — its central premise no longer holds.
-
-## The hole
-
-`RuntimeBoot.setup` gates the requested boot orchestrator like this:
-
-```python
-requested_boot_orchestrator = get_config().plugins.boot_orchestrator
-if requested_boot_orchestrator is not None and requested_boot_orchestrator not in plugin_registrar.registered_plugin_names:
- raise UnknownBootOrchestratorError(requested=requested_boot_orchestrator)
-```
-
-On a bare runtime boot, `builtin_plugins` defaults to `RUNTIME_BUILTIN_PLUGINS`, so an orchestrator contributed by an interpreter-layer **built-in** (`direct`) is never registered and the gate correctly rejects it.
-
-But `build_registrar` discovers **external** `pipelex.plugins` entry points unconditionally — the `builtin_plugins` parameter only scopes the built-in half (`plugins/discovery.py`, the `for entry_point in _external_entry_points()` loop). So an installed external interpreter-side orchestrator — our Temporal plugin is the live example — registers its name on a runtime-only boot too, and satisfies the gate.
-
-What follows is silent and incoherent. The six `HubSlot`s split exactly 3/3 along the layer line:
-
-| slot | applied in |
-|---|---|
-| `CONTENT_GENERATOR` | `runtime_boot.py` |
-| `TASK_MANAGER` | `runtime_boot.py` |
-| `ISOLATED_EXECUTION_PROBE` | `runtime_boot.py` |
-| `PIPE_FUNC_EXECUTOR` | `pipelex.py` |
-| `PIPE_ROUTER` | `pipelex.py` |
-| `PIPE_RUN` | `pipelex.py` |
-
-So `RuntimeBoot.make(boot_orchestrator="temporal")` with the plugin installed applies the plugin's **runtime** claims — including `TASK_MANAGER`, which does the full worker wiring — never applies its `PIPE_ROUTER` / `PIPE_RUN` / `PIPE_FUNC_EXECUTOR` claims, and then sets `is_ready = True`. A process that believes it is running under an orchestrator, isn't.
-
-## Why it was not fixed on #1073
-
-- **Unreachable today.** It needs all three of: an external interpreter-side orchestrator plugin installed, config or an argument naming it, *and* a caller of `RuntimeBoot.make()`. There are no callers yet — the PR is explicit that the pinned test entry points are the only ones.
-- **Every remedy needs a layer signal the runtime layer deliberately does not have.** A `PipelexPlugin` carries no layer field, and `docs/contribute/hub-layering.md` says so on purpose ("a plugin belongs to exactly one layer… Nothing enforces it mechanically"). Asking the runtime layer to classify plugins by layer inverts the boundary the split exists to draw.
-- **The nearest clean remedy is a flag on the class pair that exists to avoid flags** — see below. On the same PR, the doctor-adoption question was declined for exactly this reason ("a flag argument added to make one caller fit is a worse outcome than two short sequences that differ honestly"), so adding one here for a path with no callers would contradict the decision taken twenty lines away.
-
-## Candidate remedy, for whoever adds the first runtime-only caller
-
-The invariant is expressible without classifying *plugins*, because the split is a property of the **slots**, which already live in the runtime layer:
-
-1. Give `HubSlot` an `is_interpreter_slot` property — a `match`/`case` over the six members. Exhaustive, so adding a seventh slot forces a placement decision at the type level (this repo's StrEnum idiom, per `.claude/rules/python-standards.md`).
-2. Let the boot say whether it honours those slots — a class attribute `RuntimeBoot.honours_interpreter_slots = False`, overridden `True` in `Pipelex`. This is polymorphism rather than a parameter, which is the mechanism the split already chose, so it is the least-bad shape available.
-3. In `RuntimeBoot.setup`, after `build_registrar`, raise when `honours_interpreter_slots` is false and any claimed slot is an interpreter slot. Name the plugin and the slots in the message.
-
-That check also subsumes the narrower orchestrator question: it catches *any* external plugin whose claims a runtime-only boot cannot honour, not just orchestrators, and it does not care whether the plugin is built-in or external.
-
-**Cheaper alternative worth weighing first:** have `build_registrar` take the set of slots the caller will apply and refuse a claim outside it. That pushes the check into the one place that already knows every claim, and removes the class attribute — but it widens `build_registrar`'s signature, and that function is currently a pure discover-and-register with no policy in it, which is a property worth protecting.
-
-## The first runtime-only caller has arrived — and the verdict is "still not now"
-
-`tests/unit/pipelex/kernel/test_kernel_boot_contract.py` (the pipelex-kernel extraction, Phase 1) is the first thing in the tree to call `RuntimeBoot.make()` for a purpose other than measuring the boot itself: it boots runtime-only and then *runs* both kernel façade calls (`llm_object` and `llm_text`) on it. That is the caller this document deferred the decision to, so the decision is recorded here rather than left open.
-
-**It does not trigger the hole, and not by luck.** The gate is only reached when `get_config().plugins.boot_orchestrator` is non-`None`. That test names no `boot_orchestrator` and the config sets none, so nothing is requested, nothing is matched, and no slot claim is half-applied. The same is true of every runtime-only caller the kernel work adds — the kernel's own doctrine forbids it from reading `HubSlot` at all, and Phase 2's `PipeFunc` op takes its executor as an explicit protocol-typed argument for exactly that reason.
-
-**The remedy stays unbuilt, deliberately.** Both candidates above are real machinery — a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class attribute, or a widened `build_registrar` signature — bought for a path that *still* has no production caller. The three preconditions are unchanged: an external interpreter-side orchestrator installed, config or an argument naming it, and a runtime-only boot. A test that names no orchestrator satisfies none of the second two, so implementing the guard now would mean adding a mechanism no code can reach in order to close a hole no code can fall into. Reassess when a runtime-only boot is offered to real callers (a kernel-embedding host, an SDK entry point) — at that moment the second precondition becomes reachable for the first time and the slot-property remedy is the one to build.
-
-## What exists today instead
-
-The gate's comment in `runtime_boot.py` states the hole precisely and points here, so the next reader meets the reasoning rather than rediscovering the trap. Nothing silently claims to handle it.
-
-## Resolution — the layer signal arrived, and the hole closed on its own
-
-Everything above rests on one premise: *"every remedy needs a layer signal the runtime layer deliberately does not have."* That premise is now false. An external plugin declares its layer by the entry-point group it publishes under (`pipelex.plugins.kernel` / `pipelex.plugins.interpreter`), and discovery is scoped to the groups the caller asks for.
-
-The consequence is that the hole closed without anyone building either candidate remedy. A kernel-only boot defaults `entry_point_groups` to `KERNEL_ENTRY_POINT_GROUPS`, so an interpreter-group orchestrator plugin is never queried, never loaded, and never registered — its name therefore fails the existing `registered_plugin_names` gate and raises `UnknownBootOrchestratorError`. Loud, at boot, with no new machinery. Note where the fix landed: not in the gate this document is about, but in *what discovery is allowed to see* one step upstream. The gate was never the defect; the unconditional discovery behind it was.
-
-Both candidate remedies are therefore withdrawn rather than deferred:
-
-- **`HubSlot.is_interpreter_slot` + `honours_interpreter_slots`** — half-built, under a different name and for a different job. `HubSlot.is_interpreter_layer` exists (the menu-tier cross-check reads it to decide what a kernel-group plugin may claim), but no `honours_interpreter_slots` class attribute was added and none is needed: a kernel-only boot cannot see an interpreter-group plugin's claims in the first place.
-- **A widened `build_registrar` signature** — this is, in effect, what shipped, but scoped to *discovery* rather than to *policy*. `build_registrar` gained `entry_point_groups`, which says which groups to read; it did not gain a set of applicable slots, so the function stays a pure discover-and-register with no policy in it. The property that made the alternative unattractive is intact.
-
-**One narrower gap survives, and it is a different question.** The group split constrains what a kernel-group plugin may *register*; it does not constrain what its module *imports*. A kernel-group plugin that imports the interpreter at module scope still drags it into a kernel-only boot. That is tracked as its own item — `wip/kernel/plugin-group-split-deferred-items.md`, D-2 — and is not what this document was about.
diff --git a/wip/concept-purity/concept-purity-explained.html b/wip/concept-purity/concept-purity-explained.html
index d32e0a131..9ff1e5217 100644
--- a/wip/concept-purity/concept-purity-explained.html
+++ b/wip/concept-purity/concept-purity-explained.html
@@ -691,12 +691,7 @@
<h3>Cross-repo</h3>
-<p><b>No other repo needs a code change.</b> Cross-repo usage of the four removed member names is zero — measured by enumerating the workspace directory rather than trusting a hardcoded repo list. Two <i>documents</i> cite them and will want a look when their tracks resume:</p>
-
-<ul>
- <li><b><code>pipelex-js</code></b> — <code>wip/gauntlet/invariants-structural.md</code>, invariant <code>CONCEPT-6</code>. A live invariant register for the in-progress TS port, citing the compatibility block this PR restructured. There is a handoff note next to this document for that track.</li>
- <li><b><code>pipelex-temporal</code></b> — <code>wip/bad-parallel-combine-class-identity-bug.md</code> cites the removed <code>get_structure_class()</code>.</li>
-</ul>
+<p><b>No other repo needs a code change.</b> Cross-repo usage of the four removed member names is zero — measured by enumerating the workspace directory rather than trusting a hardcoded repo list. Two <i>documents</i> in other repos cite them and will want a look when their tracks resume — one an invariant register for the in-progress TS port, citing the compatibility block this PR restructured; the other a bug note citing the removed <code>get_structure_class()</code>. Both are tracked at workspace level.</p>
<footer>
<p>Diagrams are hand-authored inline SVG — no script, no CDN, renders offline and in both colour schemes. Written from <code>refactor/Concept-purity</code> at head <code>81ba5817c</code>.</p>
diff --git a/wip/concept-purity/concept-purity-tracker.md b/wip/concept-purity/concept-purity-tracker.md
index e0f1a1188..32b81c898 100644
--- a/wip/concept-purity/concept-purity-tracker.md
+++ b/wip/concept-purity/concept-purity-tracker.md
@@ -65,6 +65,6 @@ The verdicts are asymmetric on purpose, and the docstrings say so: at the declar
## Verification
-`make agent-check` green (ruff, plxt, pyright, mypy, keyword-only, hub-layering). Full `make agent-test` green. Cross-repo usage of the four removed member names is **zero in code** (enumerated the workspace directory rather than a hardcoded list). Two live *documents* cite them and will want a follow-up when their tracks resume: `pipelex-js/wip/gauntlet/invariants-structural.md` (CONCEPT-6) is an invariant register for the in-progress TS port citing `concept.py`'s compatibility block, and `pipelex-temporal/wip/bad-parallel-combine-class-identity-bug.md` cites the removed `get_structure_class()`. No code in either repo is affected. `pipelex-transport`'s `ALLOWED_SURFACE` names none of the touched symbols and no module moved, so no spec/conformance edit is due.
+`make agent-check` green (ruff, plxt, pyright, mypy, keyword-only, hub-layering). Full `make agent-test` green. Cross-repo usage of the four removed member names is **zero in code** (enumerated the workspace directory rather than a hardcoded list). Two live *documents* in other repos cite them and will want a follow-up when their tracks resume — tracked at workspace level; no code in either repo is affected. The transport boundary spec names none of the touched symbols and no module moved, so no spec or spec-suite edit is due.
One registry hygiene note: `is_valid_structure_class` was demoted to keyword-only when it moved, so its now-dead entry was deleted from `subject_grants.toml` — the guard hard-fails on a stale grant, which is how it surfaced.
diff --git a/wip/drift-contracts-design.md b/wip/drift-contracts-design.md
index b5f8a24de..89ee21ea4 100644
--- a/wip/drift-contracts-design.md
+++ b/wip/drift-contracts-design.md
@@ -6,7 +6,7 @@ Design accepted and implemented (engine in Phase 1, wiring/seeds/docs in Phase 2
## Problem
-CLAUDE.md already states the policy ("document at every iteration", "keep the toml files and configs.py in sync", "keep specs and conformance in sync"), but prose policy is advisory: nothing tells a PR author — human or agent — *which* docs and tests are stale relative to *this* change, and nothing records that the check happened. The research brief proposes a deterministic traceability tool for this. This design adapts that proposal to what the Pipelex repo already has, and deliberately simplifies it in several places.
+CLAUDE.md already states the policy ("document at every iteration", "keep the toml files and configs.py in sync", "keep specs and their verifying tests in sync"), but prose policy is advisory: nothing tells a PR author — human or agent — *which* docs and tests are stale relative to *this* change, and nothing records that the check happened. The research brief proposes a deterministic traceability tool for this. This design adapts that proposal to what the Pipelex repo already has, and deliberately simplifies it in several places.
## What the repo already has — and the actual gap
@@ -15,7 +15,7 @@ The brief describes a greenfield. We are not greenfield. Three synchronization t
| Tier | Mechanism | Judgment needed | Status in this repo |
|---|---|---|---|
| **Derived** | Regenerate + diff: `check-config-sync`, `check-mthds-schema`, `check-gateway-models`, `check-rules`, `generate-error-pages` | None — output is a pure function of sources | **Exists**, wired into `make check` and CI |
-| **Linkage** | Referential integrity of declared cross-references: `conformance/scripts/check-spec-links.py` (spec `> Verified by:` ↔ test `pytest.mark.spec`) | None — links either resolve or they don't | **Exists** for the spec/conformance pair |
+| **Linkage** | Referential integrity of declared cross-references: the spec-link checker (spec `> Verified by:` ↔ test `pytest.mark.spec`) | None — links either resolve or they don't | **Exists** for the spec ↔ verifying-test pair |
| **Review** | "This code changed → these docs/tests must be *looked at* against this exact change, and the look must be recorded" | Yes — a human or agent must judge whether the prose/tests still hold | **Missing** — this is the gap |
This framing yields the first design principle: **the new tool covers only the review tier**. Derived checks stay exactly where they are (Makefile + `pipelex-dev` commands); they are strictly better than review contracts because they need no judgment and can't be rubber-stamped. Whenever a review contract turns out to be mechanizable — the doc section could be generated, the sync could be checked structurally — the right move is to *delete the review contract and write a derived check*. The best review contract is one you eventually mechanize out of existence.
@@ -173,7 +173,7 @@ Unchanged from the brief, and worth restating because they bound the tool's prom
- It does not trace the whole repo. Contracts are added one at a time, where staleness has actually hurt.
- It does not replace the CLAUDE.md documentation culture; it enforces the culture's floor on the few surfaces where silent drift is most expensive.
-And one addition: it does not handle cross-repo contracts. The spec/conformance pair spans the workspace root and the `conformance/` repo and already has a purpose-built checker (`check-spec-links.py`) doing linkage-tier validation with in-file markers; `drift` is per-repo and should not absorb it. If cross-repo review contracts become pressing, that is a separate design.
+And one addition: it does not handle cross-repo contracts. The spec ↔ verifying-test pair spans two sibling repos and already has a purpose-built checker doing linkage-tier validation with in-file markers; `drift` is per-repo and should not absorb it. If cross-repo review contracts become pressing, that is a separate design.
## Failure modes, honestly
@@ -191,7 +191,7 @@ Start with three, all in the `pipelex` repo, all places where prose has already
- **cli-docs** — triggers: `pipelex/cli/**/*.py` excluding `dev_cli/`; review: `docs/tools/cli/`, `pipelex/cli/agent_cli/CLAUDE.md`. The agent-CLI output-format contract doc is load-bearing for the whole workspace's surface conventions.
- **keyword-only-convention** — triggers: `pipelex/cli/dev_cli/commands/keyword_only_guard.py`; review: `docs/contribute/keyword-only-arguments.md`. Small, sharp, and the doc is explicitly the convention's specification.
-Candidates deliberately *not* seeded: anything under `wip/` (not release-facing), generated pages (derived tier), broad feature docs (too noisy to start), spec/conformance (covered, cross-repo).
+Candidates deliberately *not* seeded: anything under `wip/` (not release-facing), generated pages (derived tier), broad feature docs (too noisy to start), the spec ↔ verifying-test pair (covered, cross-repo).
## Rollout plan
@@ -215,7 +215,7 @@ Polish the `plan` packet for agent consumption, add `--format json` for software
- Symbol-level triggers via griffe; markdown-anchor targets; pytest node-ID validation via `--collect-only`.
- Unifying the derived-tier checks into `drift plan` output as read-only `kind = "derived"` entries, so one command shows the full sync map. Nice-to-have; duplicates Makefile wiring today.
-- Cross-repo contracts (workspace-root specs, conformance, downstream consumers).
+- Cross-repo contracts (the protocol specs, their verifying suite, downstream consumers).
- Semantic assistance: `cocode`'s doc/code drift proofreading could consume the plan packet as its work list — the deterministic layer decides *what* to look at, cocode helps judge *whether* it drifted.
- Extraction into a standalone tool for the other workspace repos, if the pipelex-repo dogfood earns it.
diff --git a/wip/drift-hunt/drift-hunt-explainer.html b/wip/drift-hunt/drift-hunt-explainer.html
index 9d1aec255..1679f1a76 100644
--- a/wip/drift-hunt/drift-hunt-explainer.html
+++ b/wip/drift-hunt/drift-hunt-explainer.html
@@ -216,7 +216,7 @@
<thead><tr><th>Tier</th><th>Mechanism</th><th>Judgment needed</th></tr></thead>
<tbody>
<tr><td><strong>Derived</strong></td><td>Regenerate and diff (config sync, schema, gateway models, error pages)</td><td>None — output is a pure function of sources</td></tr>
- <tr><td><strong>Linkage</strong></td><td>Referential integrity of declared cross-references (spec ↔ conformance links)</td><td>None — links resolve or they don't</td></tr>
+ <tr><td><strong>Linkage</strong></td><td>Referential integrity of declared cross-references (spec ↔ verifying-test links)</td><td>None — links resolve or they don't</td></tr>
<tr><td><strong>Review</strong></td><td><strong>Drift contracts</strong>: "this changed → that must be looked at, and the look recorded"</td><td>Yes — someone must judge whether the prose still holds</td></tr>
</tbody>
</table>
diff --git a/wip/drift-hunt/findings/SUMMARY.md b/wip/drift-hunt/findings/SUMMARY.md
index 84d945779..c681d90c8 100644
--- a/wip/drift-hunt/findings/SUMMARY.md
+++ b/wip/drift-hunt/findings/SUMMARY.md
@@ -64,7 +64,7 @@ A ruling that shapes both the fix triage and the check design. Omitting *scaffol
- **`docs/under-the-hood/execution-graph-tracing.md:269`** — RESOLVED as Part 2 F10 (`execute_pipeline`→`execute`, confirmed). Fold into Stage 2's fix batch.
- **`docs/tools/cli/agent-cli.md:38`** — NEW, from Part 3 F1. The agent-CLI page documents `--mock-inputs` as just "Use mock inputs", omitting the **`(requires --dry-run)`** qualifier that `docs/tools/cli/run.md` states correctly three times. `docs/tools/cli/` is out of Stage-1 scope (D2, freshly reviewed) — but D2 reopens it precisely when a Stage 1 finding points back in, and this one does. One-line fix; fold into Stage 2.
- **`PipeStructure` missing from the operator roster — 3 pages** (Part 3 on `features/index.md` + `features/pipe-operators.md`; Part 4 F10 on `docs/index.md`, the site's landing page). One stale closed list, three copies. Fix as a single Stage-2 batch.
-- **⚠ SPILLOVER OUTSIDE `docs/` — the stale `make agent-test` claim (Part 4 F8). NEEDS A LOUIS RULING at Checkpoint 1.** `agent-test` is no longer silent on success (it echoes a start line, a 20 s heartbeat, and a completion line — `Makefile:732-739`, `:49-65`, `:27`). The doc page F8 covers is in scope, but **the same false claim is also in `CLAUDE.md:52` ("Zero output on success") and the workspace-root `CLAUDE.md:160` ("silent on success")** — agent-facing instruction files, outside D2's `docs/` scope, and the likely *source* the doc page was written from. Fixing the page while leaving its source stale re-seeds the drift. **Question for Louis:** fold both `CLAUDE.md` fixes into the Stage-2 batch, or split them out?
+- **⚠ SPILLOVER OUTSIDE `docs/` — the stale `make agent-test` claim (Part 4 F8). NEEDS A LOUIS RULING at Checkpoint 1.** `agent-test` is no longer silent on success (it echoes a start line, a 20 s heartbeat, and a completion line — `Makefile:732-739`, `:49-65`, `:27`). The doc page F8 covers is in scope, but **the same false claim is also in `CLAUDE.md:52` ("Zero output on success") and in the workspace-level agent guide ("silent on success")** — agent-facing instruction files, outside D2's `docs/` scope, and the likely *source* the doc page was written from. Fixing the page while leaving its source stale re-seeds the drift. **Question for Louis:** fold both `CLAUDE.md` fixes into the Stage-2 batch, or split them out?
- *(No outgoing carry-overs from Part 2 — its findings are self-contained to their pages.)*
## Cookbook-repo defects (handoff, not fixed here)
@@ -91,7 +91,7 @@ Stage 1 swept **104 of the 125 in-scope hand-written pages** (denominator: `inve
- **Every one of the 109 Stage-1 findings was fixed; 0 were rejected at fix time** — each reproduced exactly as recorded when the fixer re-verified it against the code (D6). Combined with 0 rejections at verify time, the pipeline's precision across the whole campaign is unblemished; its known error mode is false *negatives* (see the Stage-1 note above).
- **Fix-time drift (D16) added 31 confirmed findings + 1 stale section pointer, all fixed in-batch; 13 candidates were refuted** — the refutations cluster on omission/scope/equivalence claims (a scoped list is not incomplete; an intentionally-narrower command is not wrong), the confirmations on checkable facts. Fix agents over-flag; the D6 verify gate is what keeps D16 honest.
- **Every changed example re-validated against the real parser** (incl. dry-run execution for the load-bearing ones); blind no-context post-fix reviews ran on every batch commit — they caught 2 defects in S2-1's own new text and 3 in S2-3's (folded in pre-PR); S2-2 and S2-4 came back clean.
-- **Cross-cutting sweeps all landed:** the `PipeStructure` roster on all three pages (incl. the docs landing page), `agent-cli.md`'s `--mock-inputs` qualifier, and the D13 `agent-test` heartbeat claim everywhere — including the `pipelex/kit/agent_rules/` source templates (repo-root `CLAUDE.md`/`AGENTS.md` are generated from them) and the workspace-root `CLAUDE.md` in its own repo (commit `cc2b68c` on `feature/Follow-ups` there).
+- **Cross-cutting sweeps all landed:** the `PipeStructure` roster on all three pages (incl. the docs landing page), `agent-cli.md`'s `--mock-inputs` qualifier, and the D13 `agent-test` heartbeat claim everywhere — including the `pipelex/kit/agent_rules/` source templates (repo-root `CLAUDE.md`/`AGENTS.md` are generated from them) and the workspace-level agent guide in its own repo.
- **Gates on the final reconciled branch:** `make docs-check` strict, `make check`, and full **`make agent-test` — all green** (the agent-test run itself displayed the start-line + 20 s heartbeats the D13 fixes now document).
Counting Stage 0's mechanical fixes (dead paths/keys/links, committed at Checkpoint 0), the campaign fixed **~140 confirmed code↔doc drift defects** across the docs tree, plus the two instruction-file sweeps outside `docs/`.
diff --git a/wip/durable-results-tokens-usage-exposure.md b/wip/durable-results-tokens-usage-exposure.md
deleted file mode 100644
index 2143b0b26..000000000
--- a/wip/durable-results-tokens-usage-exposure.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# Durable-run results drop `tokens_usages` — expose usage on the start+poll path
-
-**Status:** Feature ask from the Fenix workspace (delivery-plan task A6, cost-measurement
-exploration, 2026-07-18). Live-verified against hosted api-dev. Full findings:
-`~/repos/Fenix/project/designs/a6-cost-measurement.md`.
-
-> **Superseded on the wire shape (2026-07-19):** the "keep it raw records, not a computed $ total" note below was deliberately reversed by the tokens-usage wire contract (workspace `wip/usage/tokens-usage-wire-contract.md`, FINAL). The wire record ships a server-computed `cost` and MUST NOT expose `unit_costs` — rates are the runtime's pricing data, not client contract, and `cost: null` (vs `0.0`) resolves the "zero-cost record" caveat flagged below. Consumers that want a run total sum the per-record `cost` values; the deterministic multiply-and-sum now happens server-side, pinned by parity tests against `CostRegistry`. The artifact/route plumbing described in this doc remains accurate.
-
-## The gap
-
-The engine assembles per-call usage onto `PipeOutput.tokens_usages` (token counts by category +
-`unit_costs` $/1M + model id, for LLM **and** img-gen/extract/search), and the sync path returns
-it: `POST /v1/execute` → `pipe_output.tokens_usages` — confirmed live (probe run `d020718b…`:
-claude-4.6-sonnet, `{input: 15, output: 4}`, `unit_costs {input: 3.0, output: 15.0}` → $0.000105
-computable client-side).
-
-But a durable client (`start` + `GET /v1/runs/{id}/results`) never sees it:
-
-- **pipelex** — `pipe_run/delivery_executor.py` `generate_result_files(pipe_output)` receives the
- full `PipeOutput` (so `tokens_usages` + `usage_assembly_error` are in hand) but persists only
- `graphspec.json`, `main_stuff.json` (+ md/html/viewer renders), `working_memory.json`.
-- **pipelex-platform** — `src/pipelex_platform/routers/v1/runs.py`
- `_fetch_run_result_artifacts()` reads exactly those three files; `RunResultsResponse` has no
- usage field. Per-node `metrics: {}` in the graphspec sits empty; no
- `/runs/{id}/usage`-style route exists (probed, 404).
-
-Sync `/execute` is not a workaround for durable clients: the ~30s gateway ceiling rules it out
-for img-gen and parallel-heavy pipes — exactly the runs whose cost matters most.
-
-## Proposed change (smallest that closes it) — ✅ BOTH SHIPPED in v0.40
-
-Both halves landed: pipelex writes the artifact (`delivery_executor.generate_result_files`), pipelex-platform serves it (`runs.py`).
-
-1. **pipelex** `delivery_executor.generate_result_files`: also write `tokens_usages.json` —
- `{"tokens_usages": [...], "usage_assembly_error": null}`, same serialization the `/execute`
- response already uses.
-2. **pipelex-platform** `runs.py`: fetch the fourth file in `_fetch_run_result_artifacts()`
- (tolerating its absence for runs delivered before the change) and add
- `tokens_usages` / `usage_assembly_error` to `RunResultsResponse`.
-
-No SDK release needed to unblock: `pipelex-sdk` 0.4.0's `RunResults` is `extra="allow"`, so the
-new fields ride along via `model_extra`; typing them in the SDK can follow.
-
-## Notes
-
-- Keep it raw records, not a computed $ total — consumers (e.g. `fenix-pipelex`) do the
- multiply-and-sum deterministically, and the existing `CostRegistry.build_cost_summary` shape is
- available if a summary is wanted later.
-- Known caveat carried over from the engine: models with no `costs` in their backend TOML price
- at 0 — consumers should flag zero-cost records rather than trust them.
diff --git a/wip/hub/README.md b/wip/hub/README.md
deleted file mode 100644
index 2bcd9c28e..000000000
--- a/wip/hub/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Hub layering — working docs
-
-Working notes for the `refactor/Hub` track: splitting `pipelex.hub` into two hubs and drawing an enforced layering boundary between them. **Track complete** — the repo-root `TODOS.md` tracker was archived here on 2026-07-27 once `_hub/` moved on to the `refactor/Modularity-3` track. What is left is not a phase, it is the release-gated cross-repo sweep (see the tracker's [Cross-repo sweep](hub-split-tracker.md#cross-repo-sweep) section).
-
-| doc | what it is |
-| --- | --- |
-| [`hub-split-tracker.md`](hub-split-tracker.md) | **The archived executable tracker** (formerly the repo-root `TODOS.md`) — every phase, checkpoint record, and the release-gated cross-repo sweep tables. Start at its "▶ Resume here" section. |
-| [`hub-split-refactor.md`](hub-split-refactor.md) | The original design rationale — why one hub was a problem, alternatives considered, the measured argument. Written before Phase 0. Where it disagrees with the tracker, the tracker wins (it carries the settled decisions and the re-measured numbers). |
-| [`layer-and-hub-renaming.md`](layer-and-hub-renaming.md) | The decision to rename the layers to *runtime* / *interpreter* and the hubs to `runtime_hub` / `interpreter_hub`, with the full rationale, the rejected alternatives, and the mechanical plan. **Landed** as its own commit after H-4. |
-| [`hub-split-explained.html`](hub-split-explained.html) | **Read this first if you are new to the track.** A self-contained walkthrough for co-developers: what was wrong, what we built, the measured gains (import cost, agentic work, docs and plugin contract), the critical code diffs, how the boundary is enforced, what to import from where, and the cross-repo migration table. Open it in a browser — no network needed. Also published as a shareable artifact: <https://claude.ai/code/artifact/b34e68eb-3ee1-44e1-a2ca-00a7f0ac8339>. |
-| [`pr-1062-review-followups.md`](pr-1062-review-followups.md) | The executable follow-up plan from the full `/review` pass on PR #1062: the transitive hole in the layer rule, the in-PR fixes, the test hardening, and the additions the release-gated sweep is missing. Phases A, B and the F1 remedy are applied; only the release-gated Phase C is left. |
-| [`../layer-placement-completion.md`](../layer-placement-completion.md) | **Shipped as PR [#1071](https://github.com/Pipelex/pipelex/pull/1071)** — finishes the boundary by removing the placement wart the split deliberately left: declares the measured-clean packages (`graph`, `tracing`, `observer`, `errors`), evicts the one module hiding inside `graph/` that loaded the whole interpreter, relocates four leaf models out of `pipeline`/`pipe_run`, then widens the predicate and deletes the caveat from all six sites. Lives one level up, at `wip/`, not in this folder. Its Phase 4 is release-gated and folded into the sweep. |
-
-The shipped specification of the boundary is [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md). The earlier single-thread triage is [`../pr-1062-review-notes.md`](../pr-1062-review-notes.md). The continuation of this track is [`../refactoring/`](../refactoring/README.md) — the modularity refactors, whose tracker carries the **M1 wave** of the shared release-gated cross-repo sweep. The other waves' consumer tables stay here, in [`hub-split-tracker.md`](hub-split-tracker.md#cross-repo-sweep); that file is the sweep's union home and neither table is complete on its own.
diff --git a/wip/hub/hub-split-explained.html b/wip/hub/hub-split-explained.html
deleted file mode 100644
index f96439b11..000000000
--- a/wip/hub/hub-split-explained.html
+++ /dev/null
@@ -1,812 +0,0 @@
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Splitting pipelex.hub</title>
-<style>
- :root{
- --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;
- --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;
- --rule:#dfe3e7; --rule-2:#cbd2d8;
- --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;
- --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;
- --stop:#b3261e; --stop-soft:#fbeae8;
- --code-bg:#f1f4f6; --code-fg:#1a2027;
- --add-bg:#e3f1e9; --del-bg:#fbeae8;
- --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);
- --serif:"Iowan Old Style","Charter","Bitstream Charter","Sitka Text",Cambria,Georgia,serif;
- --sans:ui-sans-serif,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
- --mono:ui-monospace,"SF Mono",SFMono-Regular,"JetBrains Mono","Cascadia Mono",Menlo,Consolas,monospace;
- --measure:68ch;
- }
- @media (prefers-color-scheme: dark){
- :root{
- --paper:#0f1216; --card:#161b21; --sunk:#12171c;
- --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;
- --rule:#252d35; --rule-2:#333d47;
- --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;
- --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;
- --stop:#f5a3a0; --stop-soft:#301a1a;
- --code-bg:#0c1015; --code-fg:#dde3e9;
- --add-bg:#0f2a1d; --del-bg:#301a1a;
- --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);
- }
- }
- :root[data-theme="light"]{
- --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;
- --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;
- --rule:#dfe3e7; --rule-2:#cbd2d8;
- --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;
- --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;
- --stop:#b3261e; --stop-soft:#fbeae8;
- --code-bg:#f1f4f6; --code-fg:#1a2027;
- --add-bg:#e3f1e9; --del-bg:#fbeae8;
- --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);
- }
- :root[data-theme="dark"]{
- --paper:#0f1216; --card:#161b21; --sunk:#12171c;
- --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;
- --rule:#252d35; --rule-2:#333d47;
- --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;
- --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;
- --stop:#f5a3a0; --stop-soft:#301a1a;
- --code-bg:#0c1015; --code-fg:#dde3e9;
- --add-bg:#0f2a1d; --del-bg:#301a1a;
- --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);
- }
-
- *{box-sizing:border-box}
- body{
- margin:0; background:var(--paper); color:var(--ink); font-family:var(--sans);
- font-size:16.5px; line-height:1.68; -webkit-font-smoothing:antialiased;
- }
- .frame{max-width:1040px; margin:0 auto; padding:0 1.25rem 6rem}
- p,ul,ol,figcaption,.note,.tldr,blockquote{max-width:var(--measure)}
-
- a{color:inherit; text-decoration:underline; text-decoration-thickness:1px;
- text-decoration-color:var(--rule-2); text-underline-offset:3px}
- a:hover{text-decoration-color:currentColor}
- a:focus-visible,summary:focus-visible,input:focus-visible + label{outline:2px solid var(--rt-line); outline-offset:2px; border-radius:3px}
- @media (prefers-reduced-motion: reduce){*{animation:none !important; transition:none !important; scroll-behavior:auto !important}}
-
- /* ── masthead ─────────────────────────────────────────── */
- .masthead{padding:3.2rem 0 1.6rem; border-bottom:1px solid var(--rule)}
- .eyebrow{font-family:var(--mono); font-size:.74rem; letter-spacing:.14em; text-transform:uppercase; color:var(--ink-3); margin:0 0 .9rem}
- h1{font-family:var(--serif); font-weight:600; letter-spacing:-.02em; text-wrap:balance;
- font-size:clamp(2.15rem,1.55rem + 2.2vw,3rem); line-height:1.1; margin:0 0 .6rem}
- h1 .mono{font-family:var(--mono); font-size:.82em; font-weight:500; letter-spacing:-.01em}
- .deck{font-size:1.12rem; color:var(--ink-2); margin:0 0 1.6rem; max-width:60ch; text-wrap:pretty}
- .deck b{color:var(--ink); font-weight:600}
- .meta{display:flex; flex-wrap:wrap; gap:.4rem; list-style:none; margin:0; padding:0; max-width:none}
- .meta li{font-family:var(--mono); font-size:.74rem; letter-spacing:.01em; color:var(--ink-2);
- border:1px solid var(--rule); background:var(--card); border-radius:2px; padding:.24rem .55rem}
- .meta li b{color:var(--ink); font-weight:600}
- .meta li.live{border-color:var(--rt); color:var(--rt)}
-
- /* ── sticky section rail ─────────────────────────────── */
- .rail{position:sticky; top:0; z-index:9; display:flex; gap:.15rem; overflow-x:auto; scrollbar-width:none;
- padding:.5rem 0; margin:0 0 .4rem; border-bottom:1px solid var(--rule);
- background:color-mix(in srgb, var(--paper) 88%, transparent); backdrop-filter:blur(8px)}
- .rail::-webkit-scrollbar{display:none}
- .rail a{font-family:var(--mono); font-size:.72rem; letter-spacing:.04em; text-transform:uppercase;
- color:var(--ink-3); text-decoration:none; white-space:nowrap; padding:.28rem .5rem; border-radius:3px}
- .rail a:hover{color:var(--ink); background:var(--sunk)}
-
- /* ── headings ────────────────────────────────────────── */
- h2{font-family:var(--serif); font-weight:600; font-size:1.6rem; letter-spacing:-.015em; text-wrap:balance;
- margin:3.4rem 0 1rem; scroll-margin-top:4rem; display:flex; align-items:baseline; gap:.7rem}
- h2 .n{font-family:var(--mono); font-size:.72rem; font-weight:500; letter-spacing:.1em; color:var(--rt);
- border:1px solid var(--rule); border-radius:2px; padding:.1rem .38rem; flex:none; position:relative; top:-.25em}
- h3{font-size:1.02rem; font-weight:650; margin:2rem 0 .4rem; letter-spacing:-.005em}
- h4{font-family:var(--mono); font-size:.74rem; font-weight:500; letter-spacing:.12em; text-transform:uppercase;
- color:var(--ink-3); margin:1.6rem 0 .3rem}
- p{margin:.75rem 0} ul,ol{margin:.75rem 0; padding-left:1.15rem} li{margin:.32rem 0}
-
- code,kbd{font-family:var(--mono); font-size:.86em}
- :is(p,li,td,th,summary,figcaption,.deck) code{background:var(--code-bg); padding:.08em .32em; border-radius:3px; white-space:nowrap}
-
- /* ── TL;DR ───────────────────────────────────────────── */
- .tldr{margin:2.2rem 0; padding:1.3rem 1.5rem 1.4rem; background:var(--card);
- border:1px solid var(--rule); border-top:2px solid var(--ink); border-radius:3px; box-shadow:var(--shadow)}
- .tldr h2{font-family:var(--mono); font-size:.78rem; font-weight:600; letter-spacing:.16em; text-transform:uppercase;
- color:var(--ink-3); margin:0 0 .7rem; display:block}
- .tldr ul{margin:0; padding-left:1.05rem; max-width:none}
- .tldr li{margin:.5rem 0}
- .tldr li::marker{color:var(--rule-2)}
-
- /* ── figures / stats ─────────────────────────────────── */
- .stats{display:grid; grid-template-columns:repeat(auto-fit,minmax(158px,1fr)); gap:.6rem; margin:1.6rem 0}
- .stat{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem .9rem .8rem}
- .stat .n{display:block; font-family:var(--mono); font-variant-numeric:tabular-nums; font-size:1.4rem;
- font-weight:600; letter-spacing:-.03em; line-height:1.2}
- .stat .n s{color:var(--ink-3); font-weight:400; font-size:.62em; text-decoration-color:var(--rule-2)}
- .stat .n em{font-style:normal; color:var(--rt)}
- .stat .l{display:block; font-size:.78rem; line-height:1.4; color:var(--ink-2); margin-top:.25rem}
-
- figure{margin:1.8rem 0; padding:1.1rem 1.1rem .75rem; background:var(--card);
- border:1px solid var(--rule); border-radius:3px; box-shadow:var(--shadow)}
- figure svg{display:block; width:100%; height:auto}
- figcaption{font-size:.83rem; line-height:1.55; color:var(--ink-2); margin-top:.7rem; padding-top:.7rem; border-top:1px solid var(--rule)}
-
- .s-box{fill:var(--card); stroke:var(--rule-2)}
- .s-rt{fill:var(--rt-soft); stroke:var(--rt-line)}
- .s-it{fill:var(--it-soft); stroke:var(--it-line)}
- .s-bad{fill:var(--stop-soft); stroke:var(--stop)}
- .s-t{fill:var(--ink); font:600 13px var(--sans)}
- .s-ts{fill:var(--ink-2); font:400 11.5px var(--mono)}
- .s-tm{fill:var(--ink-2); font:400 11.5px var(--sans)}
- .s-trt{fill:var(--rt); font:600 10.5px var(--mono); letter-spacing:.1em}
- .s-tit{fill:var(--it); font:600 10.5px var(--mono); letter-spacing:.1em}
- .s-tbad{fill:var(--stop); font:600 11.5px var(--sans)}
- .s-tok{fill:var(--rt); font:600 12px var(--sans)}
- .s-line{stroke:var(--rule-2); fill:none}
- .s-badline{stroke:var(--stop); fill:none}
- .s-okline{stroke:var(--rt-line); fill:none}
- .s-barwas{fill:var(--rule)}
- .s-barnow{fill:var(--rt-line)}
-
- /* ── tables ──────────────────────────────────────────── */
- .scroll{overflow-x:auto; margin:1.2rem 0; border:1px solid var(--rule); border-radius:3px; background:var(--card)}
- table{border-collapse:collapse; width:100%; font-size:.89rem; font-variant-numeric:tabular-nums}
- th,td{padding:.55rem .7rem; text-align:left; vertical-align:top; border-bottom:1px solid var(--rule)}
- th{font-family:var(--mono); font-size:.72rem; font-weight:600; letter-spacing:.08em; text-transform:uppercase;
- color:var(--ink-3); background:var(--sunk); white-space:nowrap}
- tbody tr:last-child td{border-bottom:0}
-
- /* ── code ────────────────────────────────────────────── */
- pre{background:var(--code-bg); color:var(--code-fg); border:1px solid var(--rule); border-radius:3px;
- padding:.9rem 1rem; overflow-x:auto; font-size:.8rem; line-height:1.6; margin:1rem 0}
- pre code{font-family:var(--mono)}
- .diff .del{display:block; margin:0 -1rem; padding:0 1rem; background:var(--del-bg); color:var(--stop)}
- .diff .add{display:block; margin:0 -1rem; padding:0 1rem; background:var(--add-bg); color:var(--rt)}
- .diff .hdr{display:block; color:var(--ink-3)}
- .cmt{color:var(--ink-3)}
-
- /* ── tabs ────────────────────────────────────────────── */
- .tabs{display:flex; flex-wrap:wrap; gap:.3rem; margin:1.3rem 0}
- .tabs input{position:absolute; width:1px; height:1px; opacity:0; clip-path:inset(50%)}
- .tabs label{cursor:pointer; font-family:var(--mono); font-size:.74rem; letter-spacing:.02em;
- border:1px solid var(--rule); background:var(--card); color:var(--ink-2);
- border-radius:2px; padding:.3rem .6rem; user-select:none}
- .tabs label:hover{color:var(--ink); border-color:var(--rule-2)}
- .tabs .panels{flex:1 0 100%; margin-top:.35rem}
- .tabs .panel{display:none}
- .tabs .panel > :first-child{margin-top:0}
- #d1:checked ~ label[for="d1"],#d2:checked ~ label[for="d2"],#d3:checked ~ label[for="d3"],
- #d4:checked ~ label[for="d4"],#d5:checked ~ label[for="d5"],#d6:checked ~ label[for="d6"]
- {background:var(--ink); color:var(--paper); border-color:var(--ink)}
- #d1:focus-visible ~ label[for="d1"],#d2:focus-visible ~ label[for="d2"],#d3:focus-visible ~ label[for="d3"],
- #d4:focus-visible ~ label[for="d4"],#d5:focus-visible ~ label[for="d5"],#d6:focus-visible ~ label[for="d6"]
- {outline:2px solid var(--rt-line); outline-offset:2px}
- #d1:checked ~ .panels > .panel:nth-child(1),
- #d2:checked ~ .panels > .panel:nth-child(2),
- #d3:checked ~ .panels > .panel:nth-child(3),
- #d4:checked ~ .panels > .panel:nth-child(4),
- #d5:checked ~ .panels > .panel:nth-child(5),
- #d6:checked ~ .panels > .panel:nth-child(6){display:block}
-
- /* ── misc blocks ─────────────────────────────────────── */
- details{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem 1rem; margin:1.2rem 0}
- details[open]{padding-bottom:1rem}
- summary{cursor:pointer; font-weight:600; font-size:.92rem}
- summary::marker{color:var(--rule-2)}
- details > :nth-child(2){margin-top:.85rem}
-
- .note{border-left:2px solid var(--rule-2); padding:.1rem 0 .1rem .95rem; color:var(--ink-2); font-size:.93rem; margin:1.1rem 0}
- .note.stop{border-left-color:var(--stop)}
- .note.go{border-left-color:var(--rt-line)}
-
- .cards{display:grid; grid-template-columns:repeat(auto-fit,minmax(255px,1fr)); gap:.7rem; margin:1.4rem 0}
- .cards .card{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.9rem 1rem}
- .cards h3{margin:0 0 .3rem; font-size:.95rem}
- .cards p{margin:.3rem 0; font-size:.88rem; color:var(--ink-2); max-width:none}
- .cards p strong{color:var(--ink)}
-
- .legend{display:flex; flex-wrap:wrap; gap:1rem; margin:1.4rem 0 0; font-family:var(--mono); font-size:.74rem; color:var(--ink-2)}
- .legend span{display:flex; align-items:center; gap:.4rem}
- .legend i{width:10px; height:10px; border-radius:2px; display:block}
- .legend .k-rt{background:var(--rt-line)} .legend .k-it{background:var(--it-line)} .legend .k-stop{background:var(--stop)}
-
- footer{margin-top:3.5rem; padding-top:1.2rem; border-top:1px solid var(--rule); color:var(--ink-3); font-size:.83rem}
- footer p{max-width:none}
-</style>
-
-<div class="frame">
-
-<header class="masthead">
- <p class="eyebrow">Pipelex · refactor/Hub · architecture note</p>
- <h1>Splitting <span class="mono">pipelex.hub</span></h1>
- <p class="deck">One god-object became two hubs with a single enforced arrow between them — and importing the Pipelex runtime now loads <b>zero</b> interpreter modules.</p>
- <ul class="meta">
- <li>branch <b>refactor/Hub</b></li>
- <li>base <b>v0.40.0</b></li>
- <li class="live">PR <b><a href="https://github.com/Pipelex/pipelex/pull/1062">#1062 → dev</a></b> open</li>
- <li>follow-ups <b><a href="https://github.com/Pipelex/pipelex/pull/1063">#1063</a></b> merged</li>
- <li>535 files · ~490 mechanical</li>
- <li>measured <b>2026-07-27</b></li>
- </ul>
-</header>
-
-<nav class="rail" aria-label="Sections">
- <a href="#s1">01 · Problem</a>
- <a href="#s2">02 · What we built</a>
- <a href="#s3">03 · The code</a>
- <a href="#s4">04 · Where core splits</a>
- <a href="#s5">05 · What we gained</a>
- <a href="#s6">06 · Enforcement</a>
- <a href="#s7">07 · For you</a>
- <a href="#s8">08 · Limits</a>
-</nav>
-
-<div class="tldr">
- <h2>TL;DR</h2>
- <ul>
- <li><strong>What was wrong.</strong> <code>pipelex/hub.py</code> brokered <em>every</em> cross-cutting dependency — config, console, secrets, storage, the model deck, the inference workers — <em>and</em> the concept/pipe libraries, the router, the pipeline manager. Four module-level imports meant that asking it for <code>get_console()</code> loaded the entire MTHDS interpreter. It also formed a real import cycle, papered over by three <code>importlib.import_module("pipelex.hub")</code> hacks that no lint and no type checker can see.</li>
- <li><strong>What we did.</strong> Deleted <code>pipelex/hub.py</code> outright — no alias — and replaced it with <code>pipelex/runtime_hub.py</code> (<code>RuntimeHub</code>) and <code>pipelex/interpreter_hub.py</code> (<code>InterpreterHub</code>). One rule: <em>the interpreter hub may import the runtime hub; the runtime hub must never import the interpreter hub.</em> Then the misplaced types moved down, and core's data model got injected providers so it could join the runtime layer.</li>
- <li><strong>What it bought.</strong> The inference layer went from 50 interpreter modules to <strong>0</strong>; the runtime closure from 357 modules / 29,193 SLOC to <strong>269 / 20,299</strong>. Six <code>core.*</code> entry points went 50 → 0 each. The cycle and its three hacks are gone.</li>
- <li><strong>It is mechanically enforced, not review-enforced.</strong> An AST guard (<code>make check-hub-layering</code>, in <code>make agent-check</code> and CI) checks the rule on imports <em>and on string literals</em>; a subprocess closure test pins the <em>property</em> across eight runtime entry points, with a negative control so it can never pass vacuously.</li>
- <li><strong>What changes for you.</strong> Pick your hub by what you need: infrastructure → <code>pipelex.runtime_hub</code>; anything about the loaded method → <code>pipelex.interpreter_hub</code>. A stale <code>from pipelex.hub import …</code> fails loudly at import time, by design.</li>
- <li><strong>Not done yet.</strong> The layer rule is enforced only one hop deep — 4 of 476 declared runtime-layer modules breach it transitively, all in <code>pipelex.plugins</code>, and the headline property is unaffected. Remedy decided, its own PR after #1062. The cross-repo sweep is release-gated: external repos still import <code>pipelex.hub</code> and break the moment this ships.</li>
- </ul>
-</div>
-
-<div class="stats">
- <div class="stat"><span class="n"><s>50</s> <em>0</em></span><span class="l">interpreter modules loaded by the inference layer</span></div>
- <div class="stat"><span class="n"><s>357</s> <em>269</em></span><span class="l">pipelex modules in the runtime closure</span></div>
- <div class="stat"><span class="n"><s>29,193</s> <em>20,299</em></span><span class="l">SLOC parsed and executed at import</span></div>
- <div class="stat"><span class="n"><s>3</s> <em>0</em></span><span class="l"><code>importlib</code> cycle hacks in <code>core/concepts/</code></span></div>
-</div>
-
-<div class="legend" aria-hidden="true">
- <span><i class="k-rt"></i> runtime layer</span>
- <span><i class="k-it"></i> interpreter layer</span>
- <span><i class="k-stop"></i> forbidden / deleted</span>
-</div>
-
-<h2 id="s1"><span class="n">01</span> The problem</h2>
-
-<p>One module brokered everything, so everything imported it: 309 files. Because the hub annotated its own getters with <code>Library</code>, <code>LibraryManagerAbstract</code>, <code>PipeAbstract</code> and <code>Concept</code>, those annotations dragged the whole interpretation layer into the import graph of every consumer — including consumers that only ever wanted a console handle.</p>
-
-<figure>
-<svg viewBox="0 0 760 250" role="img" aria-label="Before: every runtime-layer caller reaches the interpreter through pipelex.hub">
- <rect class="s-box" x="8" y="52" width="176" height="120" rx="3"/>
- <text class="s-trt" x="24" y="76">RUNTIME CALLERS</text>
- <text class="s-ts" x="24" y="98">cogt · tools · system</text>
- <text class="s-ts" x="24" y="116">plugins · reporting</text>
- <text class="s-tm" x="24" y="142">“I just want</text>
- <text class="s-tm" x="24" y="158">get_console()”</text>
-
- <path class="s-line" d="M188 112 H244" stroke-width="1.5" marker-end="url(#ar)"/>
-
- <rect class="s-bad" x="248" y="46" width="184" height="132" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="268" y="76">pipelex/hub.py</text>
- <text class="s-ts" x="268" y="98">one module</text>
- <text class="s-ts" x="268" y="116">309 importers</text>
- <text class="s-tbad" x="268" y="146">god object</text>
- <text class="s-ts" x="268" y="164">323 modules on import</text>
-
- <path class="s-badline" d="M436 112 H520" stroke-width="1.5" marker-end="url(#arb)"/>
- <text class="s-tbad" x="437" y="102">4 module-level imports</text>
- <text class="s-ts" x="437" y="132">(type annotations only)</text>
-
- <rect class="s-it" x="524" y="34" width="228" height="156" rx="3" stroke-width="1.5"/>
- <text class="s-tit" x="544" y="58">INTERPRETER</text>
- <text class="s-ts" x="544" y="82">libraries</text>
- <text class="s-ts" x="544" y="100">pipe_operators</text>
- <text class="s-ts" x="544" y="118">pipe_controllers</text>
- <text class="s-ts" x="544" y="136">codegen</text>
- <text class="s-ts" x="544" y="154">builder</text>
- <text class="s-tbad" x="544" y="178">50 modules pulled in</text>
-
- <path class="s-badline" d="M600 190 C600 224, 360 236, 340 186" stroke-width="1.3" stroke-dasharray="4 3" marker-end="url(#arb)"/>
- <text class="s-tbad" x="366" y="228">↺ cycle: core/concepts/concept.py ⇄ hub.py — 3 × importlib.import_module("pipelex.hub")</text>
-
- <defs>
- <marker id="ar" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M0 0 L10 5 L0 10 z" fill="var(--rule-2)"/>
- </marker>
- <marker id="arb" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M0 0 L10 5 L0 10 z" fill="var(--stop)"/>
- </marker>
- </defs>
-</svg>
-<figcaption>Before. Traced on the base commit: <code>cogt.content_generation.content_generator</code> reached <code>pipe_controllers</code>, <code>libraries</code>, <code>pipe_operators</code> and <code>codegen</code> <em>only</em> via <code>pipelex.hub</code> — never independently. The hub was the single edge holding the two halves together.</figcaption>
-</figure>
-
-<p>Three consequences, all of them daily costs:</p>
-
-<ul>
- <li><strong>An unanalyzable cycle.</strong> <code>core/concepts/concept.py</code>, <code>concept_factory.py</code> and <code>structure_generation/generator.py</code> each carried an identical lazy-import shim to break a circular dependency with the hub. All three wanted exactly one symbol — <code>get_class_registry</code>, an infrastructure-level one. Those shims are invisible to every import lint and to pyright's module graph: real coupling, load-bearing, unanalyzable.</li>
- <li><strong>A layer boundary that existed but could not be expressed.</strong> Of the 309 importers, 134 used only infrastructure symbols, 139 only method-machinery ones, and just 36 straddled. Every package below <code>core</code> used infrastructure symbols exclusively, with zero exceptions. The architecture was already layered — the hub was the one place the layering was unstateable, and therefore the one place it silently rotted.</li>
- <li><strong>Import cost paid by everyone.</strong> <code>pipelex-api</code>'s health check, the CLI's <code>--version</code>, every plugin registration module and every test touching <code>get_console</code> paid for the full interpreter.</li>
-</ul>
-
-<h2 id="s2"><span class="n">02</span> What we built</h2>
-
-<p><code>pipelex/hub.py</code> is <strong>deleted</strong>, not aliased. That is deliberate: a stale import must fail loudly at import time rather than silently resolve to the wrong layer, and it matches the repo's no-backward-compatibility principle. In its place, two containers with genuinely different lifecycles.</p>
-
-<figure>
-<svg viewBox="0 0 760 330" role="img" aria-label="After: two hubs, one permitted arrow, one forbidden arrow">
- <rect class="s-rt" x="8" y="20" width="340" height="236" rx="3" stroke-width="1.5"/>
- <text class="s-trt" x="28" y="46">RUNTIME LAYER — PROCESS-SCOPED</text>
- <rect class="s-box" x="28" y="60" width="300" height="46" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="44" y="80">pipelex/runtime_hub.py</text>
- <text class="s-ts" x="44" y="97">RuntimeHub · get_runtime_hub()</text>
- <text class="s-ts" x="28" y="128">cogt · tools · system · plugins · reporting</text>
- <text class="s-ts" x="28" y="146">core.concepts · core.domains · core.memory</text>
- <text class="s-ts" x="28" y="164">core.stuffs · core.pipes.inputs · …stuff_spec</text>
- <text class="s-tm" x="28" y="192">config · console · secrets · storage · telemetry</text>
- <text class="s-tm" x="28" y="210">model deck · inference workers · content generator</text>
- <text class="s-tm" x="28" y="228">reporting · run mode · plugin registries</text>
- <text class="s-tok" x="28" y="248">0 interpreter modules — measured, per entry point</text>
-
- <rect class="s-it" x="412" y="20" width="340" height="236" rx="3" stroke-width="1.5"/>
- <text class="s-tit" x="432" y="46">INTERPRETER LAYER — LIBRARY-SCOPED</text>
- <rect class="s-box" x="432" y="60" width="300" height="46" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="448" y="80">pipelex/interpreter_hub.py</text>
- <text class="s-ts" x="448" y="97">InterpreterHub · get_interpreter_hub()</text>
- <text class="s-ts" x="432" y="128">libraries · pipe_operators · pipe_controllers</text>
- <text class="s-ts" x="432" y="146">codegen · builder · core.bundles · core.interpreter</text>
- <text class="s-ts" x="432" y="164">core.pipes.pipe_abstract · core.pipes.rendering</text>
- <text class="s-tm" x="432" y="192">library manager · concept / domain / pipe libraries</text>
- <text class="s-tm" x="432" y="210">current-library contextvars · pipe router</text>
- <text class="s-tm" x="432" y="228">pipe run · pipeline manager · PipeFunc executor</text>
-
- <path class="s-okline" d="M430 84 H352" stroke-width="2" marker-end="url(#ar2)"/>
- <text class="s-tm" x="391" y="76" text-anchor="middle">may import</text>
-
- <path class="s-badline" d="M330 148 H430" stroke-width="2" stroke-dasharray="6 4"/>
- <line class="s-badline" x1="372" y1="138" x2="388" y2="158" stroke-width="2.5"/>
- <line class="s-badline" x1="388" y1="138" x2="372" y2="158" stroke-width="2.5"/>
- <text class="s-tbad" x="380" y="176" text-anchor="middle">never</text>
-
- <rect class="s-box" x="8" y="272" width="744" height="46" rx="3"/>
- <text class="s-t" x="28" y="292">The one rule</text>
- <text class="s-tm" x="28" y="310">interpreter_hub may import runtime_hub · runtime_hub must never import interpreter_hub · pipelex.hub no longer exists</text>
-
- <defs>
- <marker id="ar2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M0 0 L10 5 L0 10 z" fill="var(--rt-line)"/>
- </marker>
- </defs>
-</svg>
-<figcaption>After. Two containers, two singletons, two lifecycles: the runtime hub is built once at boot from config plus plugin registration and never varies; the interpreter hub is bound to the loaded method, and already had contextvar machinery for exactly that. Today the permitted arrow is not even used — the one runtime-layer thing the interpreter hub needs lives <em>below</em> both hubs — which is stronger than the rule requires.</figcaption>
-</figure>
-
-<h4>Why these names</h4>
-<p>It is the textbook language-implementation split, so it explains itself to anyone who has implemented a language: the <strong>runtime</strong> is the machinery present at execution time (allocator, stdlib, FFI — here: models, workers, config, values); the <strong>interpreter</strong> reads the program and executes it (here: reads <code>.mthds</code>, builds pipes, routes them). It also gives one word across both layer and hub. The earlier working names <code>service_hub</code> / <code>method_hub</code> <strong>never shipped</strong> — <em>service</em> collides with the hosted product (<code>from pipelex.service_hub import get_secret</code> inside <code>pipelex-platform</code> reads two ways one line apart), and <em>method</em> borrows an MTHDS language noun for a Pipelex runtime container, against the brand-boundary rule.</p>
-
-<details>
-<summary>Names considered and rejected — so nobody re-proposes them</summary>
-<div class="scroll">
-<table>
-<thead><tr><th>Candidate</th><th>For</th><th>Why not</th></tr></thead>
-<tbody>
-<tr><td><code>inference</code> (layer)</td><td>Names the valuable half</td><td>A subset masquerading as the whole — <code>tools</code>, <code>system</code>, <code>reporting</code> and the value data model are not inference. It also collides with live usage: “the inference layer” already means <code>cogt</code> specifically.</td></tr>
-<tr><td><code>foundation</code> (layer)</td><td>Genuinely viable; the fallback</td><td>Less informative than <code>runtime</code>, and shares no word with the hub.</td></tr>
-<tr><td><code>core</code> (layer)</td><td>—</td><td>Catastrophic: <code>pipelex/core/</code> exists and straddles both layers.</td></tr>
-<tr><td><code>library_hub</code></td><td>Names the biggest occupant</td><td>A library is inert; the container is active machinery (router, pipeline manager). Undersells it.</td></tr>
-<tr><td><code>pipe_hub</code></td><td>Short, concrete</td><td>Narrower than its contents — a meaningful share is concepts and domains, and <code>get_native_concept()</code> on a <code>pipe_hub</code> reads wrong.</td></tr>
-<tr><td>keep <code>hub.py</code> for one half</td><td>Smaller diff</td><td>A stale import would silently succeed and resolve to the wrong layer. The whole point is that it must not.</td></tr>
-</tbody>
-</table>
-</div>
-</details>
-
-<h2 id="s3"><span class="n">03</span> The critical code</h2>
-
-<p>Six changes carry the design; everything else in the 535-file diff is import churn.</p>
-
-<div class="tabs">
- <input type="radio" name="diffs" id="d1" checked>
- <input type="radio" name="diffs" id="d2">
- <input type="radio" name="diffs" id="d3">
- <input type="radio" name="diffs" id="d4">
- <input type="radio" name="diffs" id="d5">
- <input type="radio" name="diffs" id="d6">
- <label for="d1">1 · the cause</label>
- <label for="d2">2 · the cycle</label>
- <label for="d3">3 · resolver slot</label>
- <label for="d4">4 · a straddler</label>
- <label for="d5">5 · injected providers</label>
- <label for="d6">6 · boot</label>
-
- <div class="panels">
-
- <div class="panel">
- <h3>Four imports, serving nothing but type annotations</h3>
- <p>This is the entire cause. Each annotated a getter's return type, and each dragged a subtree behind it.</p>
- <pre class="diff"><code><span class="hdr">--- a/pipelex/hub.py (deleted)</span>
-<span class="del">-from pipelex.libraries.library import Library # concrete → concept_library, pipe_controllers, codegen</span>
-<span class="del">-from pipelex.libraries.library_manager_abstract import LibraryManagerAbstract # → core.bundles → all twelve pipe blueprints</span>
-<span class="del">-from pipelex.core.pipes.pipe_abstract import PipeAbstract # → graph.graph_tracer_manager</span>
-<span class="del">-from pipelex.core.concepts.concept import Concept # ← the cycle behind the three importlib hacks</span></code></pre>
- <p class="note">Deferring them under <code>TYPE_CHECKING</code> would not have been the fix — that keeps the god object and adds a fig leaf. The four annotations belong to getters that are <em>interpreter</em> concerns, so they moved to the module where naming them is free.</p>
- </div>
-
- <div class="panel">
- <h3>Three identical lazy-import shims become one plain import</h3>
- <pre class="diff"><code><span class="hdr">--- a/pipelex/core/concepts/concept.py (also concept_factory.py, structure_generation/generator.py)</span>
-<span class="del">-def _get_class_registry() -&gt; ClassRegistryAbstract:</span>
-<span class="del">- """Lazy import to break circular dependency between concept.py and hub.py."""</span>
-<span class="del">- import importlib # noqa: PLC0415</span>
-<span class="del">-</span>
-<span class="del">- hub = importlib.import_module("pipelex.hub")</span>
-<span class="del">- return hub.get_class_registry() # type: ignore[no-any-return]</span>
-<span class="add">+from pipelex.system.registries.class_registry_access import get_class_registry</span></code></pre>
- <p>Note where the import points: <strong>not</strong> at <code>runtime_hub</code>. <code>core.concepts.concept</code> sits <em>inside</em> <code>runtime_hub</code>'s own closure (<code>runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factory → core.pipes.pipe_output → core.stuffs.stuff → core.concepts.concept</code>), so importing the hub from there is a hard cycle in <em>both</em> orders. The accessor lives one level below both hubs instead.</p>
- </div>
-
- <div class="panel">
- <h3>Library scoping crosses <em>downward at boot</em>, never as an import</h3>
- <p><code>get_class_registry()</code> must stay library-scoped — a Temporal workflow pins its own registry — but resolving <em>which</em> library is current is interpreter knowledge. So the runtime side holds a defaulted callable slot, and the interpreter installs the real resolver when it is constructed.</p>
- <pre><code><span class="cmt"># pipelex/system/registries/class_registry_access.py — imports nothing from pipelex</span>
-class ClassRegistryScoping:
- def __init__(self) -&gt; None:
- self._resolver: Callable[[], ClassRegistryAbstract | None] = _no_library_scoping
-
- def install(self, *, resolver: Callable[[], ClassRegistryAbstract | None]) -&gt; None:
- self._resolver = resolver
-
- def reset(self) -&gt; None:
- self._resolver = _no_library_scoping
-
-class_registry_scoping = ClassRegistryScoping()
-
-def get_class_registry() -&gt; ClassRegistryAbstract:
- scoped = class_registry_scoping.resolve()
- if scoped is not None:
- return scoped
- return KajsonManager.get_class_registry() <span class="cmt"># degrade, never raise</span>
-
-<span class="cmt"># pipelex/interpreter_hub.py — set_interpreter_hub() installs the library-scoped resolver.</span>
-<span class="cmt"># pipelex.runtime_hub.get_class_registry delegates here and stays the public accessor.</span></code></pre>
- <p class="note go">The default matters: a process that only ever builds a <code>RuntimeHub</code> — the doctor path, most unit tests — degrades to the process-global registry instead of raising. A defaulted callable, never an unset attribute; the same shape as the existing <code>HubSlot.ISOLATED_EXECUTION_PROBE</code>.</p>
- </div>
-
- <div class="panel">
- <h3>What a straddling call site looks like now</h3>
- <p>36 of the 309 files used symbols from both halves. Those are the only ones that gained a second import line — and the line itself now says which layer each symbol belongs to.</p>
- <pre class="diff"><code><span class="hdr">--- a/pipelex/pipe_operators/llm/pipe_llm.py</span>
-<span class="del">-from pipelex.hub import (</span>
-<span class="del">- get_class_registry,</span>
-<span class="del">- get_concept_library,</span>
-<span class="del">- get_content_generator,</span>
-<span class="del">- get_model_deck,</span>
-<span class="del">- get_native_concept,</span>
-<span class="del">- get_required_concept,</span>
-<span class="del">-)</span>
-<span class="add">+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept</span>
-<span class="add">+from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck</span></code></pre>
- <p>Everything else was a one-line module swap, applied by an AST pass over whole import statements — not a regex, because 29 of the blocks were parenthesized and multi-line.</p>
- </div>
-
- <div class="panel">
- <h3>Core's data model stopped reaching upward</h3>
- <p>Five <code>core/</code> modules looked concepts up through the hub. They now <em>declare</em> what they need as a parameter, which is what lets them join the runtime layer.</p>
- <pre class="diff"><code><span class="hdr">--- a/pipelex/core/stuffs/stuff_factory.py</span>
-<span class="del">-def make_from_blueprint(cls, blueprint: StuffBlueprint) -&gt; "Stuff":</span>
-<span class="del">- concept_library = get_concept_library() # ← reaches into the interpreter</span>
-<span class="del">- if isinstance(blueprint.content, str) and concept_library.is_compatible(</span>
-<span class="del">- tested_concept=concept_library.get_required_concept(concept_ref=blueprint.concept_ref),</span>
-<span class="del">- wanted_concept=get_native_concept(native_concept=NativeConceptCode.TEXT),</span>
-<span class="add">+def make_from_blueprint(cls, blueprint: StuffBlueprint, *, concept_provider: ConceptProviderAbstract) -&gt; "Stuff":</span>
-<span class="add">+ if isinstance(blueprint.content, str) and concept_provider.is_compatible(</span>
-<span class="add">+ tested_concept=concept_provider.get_required_concept(concept_ref=blueprint.concept_ref),</span>
-<span class="add">+ wanted_concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),</span>
- ):</code></pre>
- <p><code>ConceptProviderAbstract</code> is a new <em>read-side</em> contract owned by <code>core/</code>: resolve a ref, resolve a native code, answer compatibility. <code>ConceptLibraryAbstract</code> <strong>extends</strong> it, keeping add/remove/list/setup/teardown in the interpreter layer. The split is the point — core depends on <em>resolution</em>, never on a library <em>lifecycle</em>. Injection happens on the interpreter side: <code>pipe_factory</code>, the renderers and <code>pipeline/execution_seams.py</code> call the hub themselves and hand the result down.</p>
- </div>
-
- <div class="panel">
- <h3>Boot builds both, then changes nothing else</h3>
- <pre><code><span class="cmt"># pipelex/pipelex.py — Pipelex.__init__</span>
-self.runtime_hub = RuntimeHub()
-set_runtime_hub(self.runtime_hub)
-self.interpreter_hub = InterpreterHub()
-set_interpreter_hub(self.interpreter_hub) <span class="cmt"># also installs the class-registry resolver</span></code></pre>
- <p class="note stop">The setter sequence after this is <strong>byte-identical in order</strong>, deliberately. Reordering to get a clean “runtime first, then interpreter” run would have moved setters across documented ordering dependencies — the storage-provider block resolves <em>after</em> secrets is on the hub, so the GCP factory's secret read works — a real behavior risk at a checkpoint whose bar was zero behavior change. Constructing both hubs up front already delivers what the ordering was protecting: no setter can run against a missing hub.</p>
- <p>Teardown releases both, and drops any scoping the interpreter hub installed — pinned by <code>tests/unit/pipelex/test_hub_lifecycle.py</code>.</p>
- </div>
-
- </div>
-</div>
-
-<h2 id="s4"><span class="n">04</span> Where <code>core/</code> splits</h2>
-
-<p>The original plan assumed all of <code>pipelex/core/</code> could join the runtime layer once the five hub-straddling modules were converted. Measurement said otherwise, and this is the main finding of the work: beyond those five, seven <code>core/</code> modules import the interpreter <em>directly</em> — no hub involved, so no amount of dependency injection touches them. <code>core.pipes.pipe_abstract</code> alone loads 30 interpreter modules while importing no hub at all.</p>
-
-<figure>
-<svg viewBox="0 0 760 250" role="img" aria-label="pipelex/core splits between the two layers along the Pipe-touching line">
- <text class="s-t" x="8" y="22">pipelex/core/ — one package, two layers</text>
-
- <rect class="s-rt" x="8" y="38" width="360" height="150" rx="3" stroke-width="1.5"/>
- <text class="s-trt" x="26" y="62">RUNTIME — THE VALUE DATA MODEL</text>
- <text class="s-ts" x="26" y="86">concepts/ · domains/ · memory/ · stuffs/</text>
- <text class="s-ts" x="26" y="104">pipes/inputs/ · pipes/stuff_spec/</text>
- <text class="s-tm" x="26" y="132">Takes resolution as a parameter:</text>
- <text class="s-ts" x="26" y="150">concept_provider: ConceptProviderAbstract</text>
- <text class="s-tok" x="26" y="174">6 entry points measured 50 → 0</text>
-
- <rect class="s-it" x="392" y="38" width="360" height="150" rx="3" stroke-width="1.5"/>
- <text class="s-tit" x="410" y="62">INTERPRETER — EVERYTHING NAMING A PIPE</text>
- <text class="s-ts" x="410" y="86">registry_models · bundles/ · interpreter/</text>
- <text class="s-ts" x="410" y="104">pipes/pipe_abstract · pipes/rendering/</text>
- <text class="s-tm" x="410" y="132">Irreducible: a discriminated union over</text>
- <text class="s-tm" x="410" y="150">every pipe kind, the base class every pipe</text>
- <text class="s-tm" x="410" y="168">extends, the registry of pipe kinds.</text>
-
- <path class="s-okline" d="M392 113 H370" stroke-width="2" marker-end="url(#ar3)"/>
- <text class="s-tm" x="381" y="106" text-anchor="middle">injects</text>
-
- <rect class="s-box" x="8" y="200" width="744" height="42" rx="3"/>
- <text class="s-t" x="28" y="226">The honest boundary is not “pipelex.core” — it is: if it names a Pipe, it is interpreter-layer.</text>
-
- <defs>
- <marker id="ar3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M0 0 L10 5 L0 10 z" fill="var(--rt-line)"/>
- </marker>
- </defs>
-</svg>
-<figcaption>Threading a provider through <code>PipeFactory.make_from_blueprint</code> as well was considered and rejected: 337 call sites for <em>no</em> additional closure property, since <code>pipe_factory</code> stays interpreter-bound either way.</figcaption>
-</figure>
-
-<h2 id="s5"><span class="n">05</span> What we gained</h2>
-
-<h3>Import cost — the measurable part</h3>
-
-<figure>
-<svg viewBox="0 0 760 210" role="img" aria-label="Before and after: modules, SLOC and interpreter modules in the runtime closure">
- <text class="s-tm" x="8" y="18">runtime closure · entry point pipelex.cogt.content_generation.content_generator</text>
-
- <text class="s-ts" x="8" y="52">modules</text>
- <rect class="s-barwas" x="110" y="38" width="360" height="14" rx="2"/>
- <text class="s-tm" x="480" y="50">357 before</text>
- <rect class="s-barnow" x="110" y="58" width="271" height="14" rx="2"/>
- <text class="s-tok" x="480" y="70">269 after</text>
-
- <text class="s-ts" x="8" y="116">SLOC</text>
- <rect class="s-barwas" x="110" y="102" width="360" height="14" rx="2"/>
- <text class="s-tm" x="480" y="114">29,193 before</text>
- <rect class="s-barnow" x="110" y="122" width="250" height="14" rx="2"/>
- <text class="s-tok" x="480" y="134">20,299 after</text>
-
- <text class="s-ts" x="8" y="180">interpreter</text>
- <rect class="s-barwas" x="110" y="166" width="360" height="14" rx="2"/>
- <text class="s-tm" x="480" y="178">50 before</text>
- <rect class="s-barnow" x="110" y="186" width="4" height="14" rx="2"/>
- <text class="s-tok" x="480" y="198">0 after — the headline property</text>
-</svg>
-<figcaption>Reproduced on the branch tip on 2026-07-27: <strong>269 modules / 20,299 SLOC / 0 interpreter modules</strong>. The closure test runs this measurement over eight entry points on every CI run.</figcaption>
-</figure>
-
-<p>Be precise about what this buys: <strong>it does not make pipeline execution faster.</strong> It removes import cost from every consumer that never needed the interpreter. Measured today as a proxy — adding <code>pipelex.interpreter_hub</code> on top of the runtime entry point costs <strong>+90 pipelex modules and ~50 ms</strong> of in-process import time (median of seven runs, warm cache, one machine). Before the split that was unavoidable: every caller of <code>get_console()</code> paid it. Who collects the refund:</p>
-
-<ul>
- <li><code>pipelex-api</code>'s health and version paths, and any cold container or Lambda start that imports the runtime before serving.</li>
- <li>The CLI's fast paths — <code>--version</code>, <code>which</code>, anything that does not load a method.</li>
- <li>Every plugin registration module, which by definition runs at import time inside a host process.</li>
- <li>The test suite: hundreds of unit tests that touch the runtime no longer parse and execute ~9,000 lines of interpreter to do it.</li>
-</ul>
-
-<p class="note">On that timing figure: the before/after wall clock was never captured at the base commit, so the number above is measured <em>today</em> as “what the interpreter half costs to load”. The durable, reproducible numbers are the module and SLOC counts.</p>
-
-<h3>Working on this codebase with agents</h3>
-
-<div class="cards">
- <div class="card">
- <h3>Blast radius is now structural</h3>
- <p>A change to a pipe blueprint's module-level imports <strong>cannot</strong> perturb the import graph of <code>cogt</code> any more. Before, it could — silently. That is the difference between “please be careful” and “the arrow does not exist”.</p>
- </div>
- <div class="card">
- <h3>Failures are loud and local</h3>
- <p>Deleting <code>pipelex.hub</code> outright means stale knowledge — a model's memory of the old API, a copied snippet, an old branch — produces an <strong>ImportError at import time</strong>, not a wrong-layer resolution that works until it doesn't.</p>
- </div>
- <div class="card">
- <h3>Placement has a mechanical answer</h3>
- <p>“Which hub does this new accessor go on?” used to be taste. Now it is two partition tables plus one rule — <em>if it names a Pipe, it is interpreter-layer</em> — and getting it wrong fails a check rather than a review.</p>
- </div>
- <div class="card">
- <h3>String references are caught too</h3>
- <p>The guard scans <em>string constants</em>, not just imports. That is the class of edit tooling gets wrong most often: <code>mocker.patch("pipelex.hub.get_console", …)</code> broke 36 tests once, and is invisible to every import-graph tool and to pyright.</p>
- </div>
- <div class="card">
- <h3>Smaller closure, smaller context</h3>
- <p>Reasoning about the runtime layer no longer means reasoning about the interpreter. Fewer modules in the graph is fewer files to read before an answer is trustworthy.</p>
- </div>
- <div class="card">
- <h3>The property is tested, not just the rule</h3>
- <p>A stray import elsewhere can re-drag the interpreter without touching a hub. The subprocess closure test catches exactly that, and prints the offending modules so the shortest path to the fix is in the failure message.</p>
- </div>
-</div>
-
-<h3>Cleaner dev docs and a real plugin contract</h3>
-
-<ul>
- <li><strong>The partition tables are the contract.</strong> A plugin author or external consumer reads one of two scoped tables instead of a 300-symbol god module. Placement is decided by <em>kind</em>, not by in-tree usage — which is why accessors with no in-tree importers were kept rather than deleted: several are live external plugin contract.</li>
- <li><strong>Plugin registries are filed by layer.</strong> <code>inference_backend</code>, <code>model_lister</code>, <code>orchestrator</code>, <code>bundle_validator</code>, <code>storage_provider</code>, <code>secrets_provider</code> are runtime-layer; the PipeFunc executor and its registry are interpreter-layer, because their protocol lives in <code>pipe_operators/func/</code>. That call is recorded with its underlying inversion rather than quietly rounded off.</li>
- <li><strong>The spec is shipped, not tribal.</strong> <code>docs/contribute/hub-layering.md</code> follows the shape the repo already uses for a mechanically-enforced convention, and <code>docs/under-the-hood/architecture-overview.md</code> names the boundary. A <code>hub-layering-convention</code> drift contract keeps both from rotting: touch the guard or either hub, and you owe a review.</li>
- <li><strong>One outward-facing claim, now true and pinned:</strong> <em>importing the Pipelex runtime loads zero interpreter modules</em> — the inference engine does not know the MTHDS language exists, so it can be embedded without loading a line of the interpreter.</li>
- <li><strong>Two documented-but-inert APIs were found and fixed in passing.</strong> <code>docs/advanced/observer-provider-injection.md</code> documented <code>hub.set_observer()</code> as the supported way to register an observer — the value was written and never read, so anyone following that page got a silently ignored observer. That page and <code>docs/advanced/index.md</code>, which showed a bare hub being hand-constructed and was equally inert, were rewritten to the mechanism that actually works.</li>
-</ul>
-
-<h3>Placement fixes that fell out of the same measurement</h3>
-
-<div class="scroll">
-<table>
-<thead><tr><th>Moved</th><th>From → to</th><th>Effect</th></tr></thead>
-<tbody>
-<tr><td><code>JobMetadata</code>, <code>JobCategory</code>, <code>UnitJobId</code>, <code>TraceContext</code>, <code>DataInclusionConfig</code></td><td><code>pipeline/</code> and <code>graph/</code> → <code>pipelex/system/</code></td><td><code>cogt → pipeline</code>: 18 statements → <strong>0</strong>. <code>TraceContext</code> had to travel with <code>JobMetadata</code> — leaving it behind would only have renamed the inversion. The TOML shape is unchanged.</td></tr>
-<tr><td><code>TextFormat</code>, <code>TemplatingStyle</code>, <code>TagStyle</code>, <code>TemplateCategory</code></td><td><code>cogt/templating/</code> → <code>tools/templating/</code> and <code>tools/jinja2/</code></td><td><code>tools → cogt</code>: 15 → <strong>3</strong>, the pdf renderer only. They split across two packages on purpose: <code>TemplateCategory</code>'s payload is jinja2 filters, so filing it beside the others would have created a cycle inside one layer.</td></tr>
-</tbody>
-</table>
-</div>
-
-<details>
-<summary>Reproduce the measurement yourself</summary>
-<pre><code>.venv/bin/python - &lt;&lt;'PY'
-import sys
-from pathlib import Path
-
-import pipelex.cogt.content_generation.content_generator # noqa: F401
-
-INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
-loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
-interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
-sloc = 0
-for mod in loaded.values():
- file = getattr(mod, "__file__", None)
- if file:
- sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
-print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
-print("offenders:", interpreter)
-PY</code></pre>
-<p>Swap the imported module to measure any other entry point. If <code>interpreter modules</code> is not 0, the offenders it prints are what to fix — the shortest import path to one of them is the defect.</p>
-</details>
-
-<h2 id="s6"><span class="n">06</span> How it stays true</h2>
-
-<figure>
-<svg viewBox="0 0 760 230" role="img" aria-label="Three gates: the AST guard, the closure test, and where they run">
- <rect class="s-box" x="8" y="30" width="232" height="130" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="26" y="54">1 · The guard</text>
- <text class="s-ts" x="26" y="74">pipelex-dev check-hub-layering</text>
- <text class="s-tm" x="26" y="98">Rule A — no runtime-layer module</text>
- <text class="s-tm" x="26" y="114">may import pipelex.interpreter_hub</text>
- <text class="s-tm" x="26" y="136">Rule B — no module anywhere may</text>
- <text class="s-tm" x="26" y="152">reference pipelex.hub (deleted)</text>
-
- <path class="s-line" d="M244 95 H272" stroke-width="1.5" marker-end="url(#ar4)"/>
-
- <rect class="s-box" x="276" y="30" width="232" height="130" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="294" y="54">2 · The closure test</text>
- <text class="s-ts" x="294" y="74">test_runtime_layer_import_closure</text>
- <text class="s-tm" x="294" y="98">8 runtime entry points, each in a</text>
- <text class="s-tm" x="294" y="114">subprocess → 0 interpreter modules</text>
- <text class="s-tm" x="294" y="136">+ 1 dirty negative control, so the</text>
- <text class="s-tm" x="294" y="152">suite can never pass vacuously</text>
-
- <path class="s-line" d="M512 95 H540" stroke-width="1.5" marker-end="url(#ar4)"/>
-
- <rect class="s-box" x="544" y="30" width="208" height="130" rx="3" stroke-width="1.5"/>
- <text class="s-t" x="562" y="54">3 · Where it runs</text>
- <text class="s-ts" x="562" y="74">make agent-check</text>
- <text class="s-ts" x="562" y="92">make check</text>
- <text class="s-ts" x="562" y="110">CI job lint-hub-layering</text>
- <text class="s-tm" x="562" y="134">Hard block, empty exception</text>
- <text class="s-tm" x="562" y="150">list — the tree is compliant</text>
-
- <rect class="s-box" x="8" y="176" width="744" height="46" rx="3"/>
- <text class="s-tm" x="26" y="196">Both rules match imports AND bare string literals — importlib, mocker.patch, any config-driven dotted path.</text>
- <text class="s-tm" x="26" y="214">Carve-outs: if TYPE_CHECKING (layer rule only, receiver must be typing) · inline # hub-layering: ignore</text>
-
- <defs>
- <marker id="ar4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
- <path d="M0 0 L10 5 L0 10 z" fill="var(--rule-2)"/>
- </marker>
- </defs>
-</svg>
-<figcaption>The lint guards the <em>rule</em>; the closure test guards the <em>property</em>, which is what actually matters and which a stray import elsewhere could break without touching a hub.</figcaption>
-</figure>
-
-<pre><code><span class="cmt"># pipelex/cli/dev_cli/commands/hub_layering_guard.py</span>
-RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (
- "pipelex.cogt", "pipelex.plugins", "pipelex.reporting", "pipelex.system", "pipelex.tools",
- "pipelex.runtime_hub", <span class="cmt"># a module, not a package — the rule now covers the hub itself</span>
- "pipelex.core.concepts", "pipelex.core.domains", "pipelex.core.memory",
- "pipelex.core.pipes.inputs", "pipelex.core.pipes.stuff_spec", "pipelex.core.stuffs",
-)
-
-INTERPRETER_HUB_MODULE = "pipelex.interpreter_hub" <span class="cmt"># rule A: forbidden above</span>
-DELETED_HUB_MODULE = "pipelex.hub" # hub-layering: ignore <span class="cmt"># rule B: dead everywhere, tests/ included</span></code></pre>
-
-<details>
-<summary>Two things the guard taught us, worth stealing for the next one</summary>
-<p><strong>Generalizing the string check is what made it work.</strong> The plan framed it as an <code>importlib.import_module</code> special case. Scanning <em>every</em> string constant for an exact-or-boundary match on the module path catches <code>importlib</code>, <code>mocker.patch</code>, <code>pkgutil.resolve_name</code> and any config-driven dotted path in one mechanism, with no call-site special-casing. Matching is exact-or-dotted-prefix, which is why <code>pipelex.runtime_hub</code> does not match <code>pipelex.hub</code>, and why a docstring that merely <em>mentions</em> a module is not a reference.</p>
-<p><strong>A negative control has to assert the message, not the exit code.</strong> The closure test's dirty entry point exits 1 for a second reason — <code>pipelex.interpreter_hub in sys.modules</code> — whatever the offender predicate does. An exit-code-only control would have passed over a completely broken detector, leaving all eight real entry points green and vacuous forever. It asserts the offender message too. Confirmed by mutation: typo the package set, and the control fails while everything else stays green.</p>
-<p>Every item in the test-hardening pass was verified <em>by mutation</em> — remove the pinned behavior, watch the new test fail, revert. Watching a new test go green proves nothing about what it pins, and two of those items existed precisely because an existing test appeared to pin something it did not.</p>
-</details>
-
-<h2 id="s7"><span class="n">07</span> What this means for you</h2>
-
-<h3>Picking a hub</h3>
-<div class="scroll">
-<table>
-<thead><tr><th>You need…</th><th>Import from</th></tr></thead>
-<tbody>
-<tr><td>config, console, secrets, storage, telemetry / OTel tracer, class registry, func registry</td><td><code>pipelex.runtime_hub</code></td></tr>
-<tr><td>models manager, model deck, SDK clients, inference manager, LLM / img-gen / extract workers, content generator</td><td><code>pipelex.runtime_hub</code></td></tr>
-<tr><td>report delegate, run mode, event log, and the plugin registries (backend, model lister, orchestrator, bundle validator, storage, secrets)</td><td><code>pipelex.runtime_hub</code></td></tr>
-<tr><td>library manager, concept / domain / pipe lookups, the current-library contextvars, library dirs</td><td><code>pipelex.interpreter_hub</code></td></tr>
-<tr><td>pipe router, pipe run, pipeline manager, the PipeFunc executor and its registry</td><td><code>pipelex.interpreter_hub</code></td></tr>
-</tbody>
-</table>
-</div>
-
-<h3>What failure looks like</h3>
-<div class="scroll">
-<table>
-<thead><tr><th>You did</th><th>You get</th></tr></thead>
-<tbody>
-<tr><td><code>from pipelex.hub import get_console</code></td><td><code>ModuleNotFoundError</code> at import time. The module is gone on purpose — pick a half.</td></tr>
-<tr><td>Imported <code>interpreter_hub</code> from a runtime-layer module</td><td><code>make check-hub-layering</code> fails with the file, the line, the kind and the remedy. Also fails <code>make agent-check</code> and the <code>lint-hub-layering</code> CI job.</td></tr>
-<tr><td>Left a <code>"pipelex.hub"</code> string in a <code>mocker.patch</code> target</td><td>Same guard, dead-module rule — inside <code>tests/</code> too.</td></tr>
-<tr><td>Added an import that re-drags the interpreter without touching a hub</td><td><code>tests/unit/pipelex/test_runtime_layer_import_closure.py</code> fails and prints the offending modules.</td></tr>
-<tr><td>Genuinely need an exception</td><td><code>if TYPE_CHECKING:</code> for a type-only import (layer rule only), or an inline <code>&#35; hub-layering: ignore</code> on the statement.</td></tr>
-</tbody>
-</table>
-</div>
-
-<h3>Cross-repo — release-gated, three waves, one pass per repo</h3>
-<p>External repos still import <code>pipelex.hub</code> and break the moment this ships. The sweep is deliberately <strong>not</strong> in PR #1062; it lands with the release, already retargeted to the final names, so each repo is rewritten exactly once.</p>
-
-<div class="scroll">
-<table>
-<thead><tr><th>Wave</th><th>Old</th><th>New</th></tr></thead>
-<tbody>
-<tr><td rowspan="4">1 · the split</td><td><code>from pipelex.hub import &lt;runtime symbol&gt;</code></td><td><code>from pipelex.runtime_hub import …</code></td></tr>
-<tr><td><code>from pipelex.hub import &lt;interpreter symbol&gt;</code></td><td><code>from pipelex.interpreter_hub import …</code></td></tr>
-<tr><td><code>get_pipelex_hub</code></td><td><code>get_runtime_hub</code> <strong>or</strong> <code>get_interpreter_hub</code> — pick the container the call site meant</td></tr>
-<tr><td><code>PipelexHub</code></td><td><code>RuntimeHub</code> <strong>or</strong> <code>InterpreterHub</code></td></tr>
-<tr><td rowspan="4">2 · moved types</td><td><code>pipelex.pipeline.job_metadata</code></td><td><code>pipelex.system.job_metadata</code></td></tr>
-<tr><td><code>pipelex.graph.trace_context</code> · <code>pipelex.graph.graph_config:DataInclusionConfig</code></td><td><code>pipelex.system.trace_context</code> · <code>pipelex.system.data_inclusion_config</code></td></tr>
-<tr><td><code>pipelex.pipeline.exceptions:JobMetadataError</code></td><td><code>pipelex.system.exceptions</code></td></tr>
-<tr><td><code>pipelex.cogt.templating.{text_format,templating_style}</code> · <code>…template_category</code></td><td><code>pipelex.tools.templating.…</code> · <code>pipelex.tools.jinja2.template_category</code></td></tr>
-<tr><td rowspan="2">3 · moves + signatures</td><td><code>pipelex.codegen.resolved_fields</code> · <code>core.pipes.inputs.input_renderer</code> · <code>core.pipes.output.output_renderer</code></td><td><code>core.concepts.resolved_fields</code> · <code>core.pipes.rendering.{input,output}_renderer</code></td></tr>
-<tr><td><code>StuffFactory.make_stuff_from_stuff_content_or_data</code>, <code>WorkingMemoryFactory.make_from_pipeline_inputs</code>, <code>InputShaper.shape</code>, <code>InputStuffSpecsFactory.make_from_*</code>, <code>StuffSpecFactory.make_from_blueprint</code></td><td>all now require <code>concept_provider=get_concept_library()</code></td></tr>
-</tbody>
-</table>
-</div>
-
-<details>
-<summary>Which repos, and which one bites first</summary>
-<div class="scroll">
-<table>
-<thead><tr><th>Repo</th><th><code>pipelex.hub</code> files</th><th>moved-type files</th><th>note</th></tr></thead>
-<tbody>
-<tr><td><code>pipelex-temporal</code> (private)</td><td>35</td><td>22</td><td>Heaviest consumer. Runner and worker must roll forward together — worth a changelog sentence.</td></tr>
-<tr><td><code>pipelex-mistralai-workflows</code></td><td>11</td><td>6</td><td><code>set_pipe_router</code> / <code>teardown_current_pipe_router</code> / <code>scoped_pipe_router</code> are documented as depended upon here — a contract change to <em>announce</em>, not just make.</td></tr>
-<tr><td><code>pipelex-api</code></td><td>9</td><td>1</td><td></td></tr>
-<tr><td><code>pipelex-transport</code></td><td>8 (2 production)</td><td>7</td><td><strong>The sharp one.</strong> <code>bridge.py</code> calls <code>WorkingMemoryFactory.make_from_pipeline_inputs</code> without the now-required <code>concept_provider</code> — the only production call site of a changed signature outside this repo. Also missing from the workspace repo table, which is why it was missed.</td></tr>
-<tr><td><code>pipelex-daytona-sandbox</code></td><td>1</td><td>3</td><td>An entry-point plugin, so it fails inside a <em>host</em> pipelex process at registration, not in its own tests.</td></tr>
-<tr><td><code>pipelex-demo-mistral</code> · <code>pipelex-demo-vibe</code></td><td>9 each</td><td>5 each</td><td>Example workflows call the changed signatures.</td></tr>
-<tr><td><code>pipelex-cookbook</code> · <code>cocode</code></td><td>2 each</td><td>—</td><td></td></tr>
-<tr><td><code>conformance</code> + <code>docs/specs/</code></td><td>—</td><td>1</td><td><code>docs/specs/pipelex-transport-boundary.md</code> §A declares <code>pipelex.hub</code> a stable cross-boundary seam, verified by an <em>active</em> conformance test. Spec and test move in lockstep with the sweep, then <code>make check-spec-links</code>.</td></tr>
-</tbody>
-</table>
-</div>
-<p>Clean, no action: <code>pipelex-worker</code>, <code>pipelex-starter-python</code>, <code>pipelex-relay</code>, <code>n8n-nodes-pipelex</code>, <code>sandbox</code>. Version-pinned and therefore safe for now: <code>pipelex-workshop</code>, <code>pipelex-demos</code>, <code>pipelex-demo-frostbeam</code>.</p>
-</details>
-
-<h2 id="s8"><span class="n">08</span> Known limits — stated, not hidden</h2>
-
-<ul>
- <li><strong>The layer rule is enforced only one hop deep.</strong> The guard checks direct imports, so a runtime-layer module can reach <code>interpreter_hub</code> transitively with both gates green. Blast radius measured exactly: <strong>4 of 476</strong> declared runtime-layer modules, all in <code>pipelex.plugins</code> — the other ten declared packages are clean across 345 modules — via three transitive routes. <em>The headline property is not damaged</em>: the inference layer and <code>runtime_hub</code> still measure 0 and never reach the breaching modules. The remedy is decided — split the built-in plugins by layer, give the two interpreter-touching ones a single interpreter-side home, and teach the guard the transitive check. Its own PR after #1062 merges; simulated at 0 of 128 breaching once three modules relocate.</li>
- <li><strong>Known inversions, named so the docs stay honest.</strong> Two <code>plugins/</code> modules import from <code>pipe_operators/</code> and one from <code>pipeline/</code>. They import no hub, so the guard does not flag them — which is exactly why they are written down. Remaining measured cross-layer edges: <code>cogt → core</code> (21), <code>system → cogt</code> (7), <code>plugins → runtime_bridge</code> (6), <code>tools → cogt</code> (3), and one genuine wart, <code>cogt/model_backends/model_lists.py</code> importing a CLI exception.</li>
- <li><strong>A general layering ratchet is a sequel, not this change.</strong> “No runtime module may import any interpreter module, with an allowlist” is a much cheaper argument now that the two biggest clusters are gone — but it is a bigger change than this one should carry.</li>
- <li><strong>One eager optional-SDK import is out of scope but worth knowing:</strong> <code>tracing/event_log_factory.py</code> imports the DynamoDB event log at module level, which runs a module-level <code>try: import boto3</code>, so boto3 and friends load in every process that touches the tracing factory. Three-line fix, entirely independent of this work.</li>
-</ul>
-
-<footer>
- <p>Branch <code>refactor/Hub</code> off <code>dev</code> at v0.40.0 · PR <a href="https://github.com/Pipelex/pipelex/pull/1062">#1062</a> open, follow-ups merged via <a href="https://github.com/Pipelex/pipelex/pull/1063">#1063</a> · gates green: <code>make agent-check</code>, full <code>make agent-test</code>, <code>make drift-check</code> · numbers re-measured 2026-07-27 on the branch tip. The shipped specification of the boundary is <code>docs/contribute/hub-layering.md</code>; the executable tracker with every checkpoint record is <code>TODOS.md</code>.</p>
-</footer>
-
-</div>
diff --git a/wip/hub/hub-split-refactor.md b/wip/hub/hub-split-refactor.md
deleted file mode 100644
index 60d86c773..000000000
--- a/wip/hub/hub-split-refactor.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Splitting `pipelex.hub` into a service hub and a method hub
-
-**Status:** plan, drafted 2026-07-26 against the v0.40.0 base (`dev` at `f23fda7a0`). Nothing implemented. Every number below was measured, and the recipe to reproduce it is in this document — no external tooling required.
-
-Branch off `dev` (e.g. `refactor/Hub-split`), normal PR back to `dev`.
-
-## The problem, in one paragraph
-
-`pipelex/hub.py` is a single god-object that brokers *every* cross-cutting dependency in the codebase — the config, the console, secrets, storage, the class registry, the model deck and inference workers, the plugin registries, and also the concept/domain/pipe libraries, the pipe router, the pipeline manager. Because it is one module, importing it for `get_console()` also imports the entire method-interpretation layer. Measured: `import pipelex.hub` alone loads **323 modules / 26,288 SLOC**, including all of `libraries`, `pipe_operators`, `pipe_controllers`, and `codegen`. Every path from the inference layer to the interpreter runs through it — traced, `pipelex.cogt.content_generation.content_generator` reaches `pipe_controllers`, `libraries`, `pipe_operators`, and `codegen` *only* via `pipelex.hub`, never independently.
-
-Four module-level imports in `hub.py`, all serving type annotations on getters, are the whole cause:
-
-```
-from pipelex.libraries.library import Library # CONCRETE — drags concept_library, pipe_controllers, and via concept_factory → codegen
-from pipelex.libraries.library_manager_abstract import ... # → core.bundles.pipelex_bundle_blueprint → all twelve pipe blueprints
-from pipelex.core.pipes.pipe_abstract import PipeAbstract # → graph.graph_tracer_manager
-from pipelex.core.concepts.concept import Concept # the cycle that forces three importlib string-literal hacks
-```
-
-## Why this is worth doing
-
-1. **It removes a real import cycle and the three hacks that paper over it.** `core/concepts/concept.py`, `concept_factory.py`, and `structure_generation/generator.py` each carry an identical `importlib.import_module("pipelex.hub")` function with the comment *"Lazy import to break circular dependency with hub.py"*. All three want exactly one symbol: `get_class_registry` — a low-level one. A hub that does not import `Concept` has no cycle with `concept.py`, so all three become plain top-level imports. These hacks are also invisible to every import lint and to pyright's module graph, so they are the worst kind of coupling: real, load-bearing, and unanalyzable.
-
-2. **It makes a layer boundary that already exists become enforceable.** Measured across all 309 files that import the hub: 134 use only low-level symbols, 139 use only high-level ones, and just **36 straddle**. Every package below `core` — `cogt`, `tools`, `system`, `plugins`, `reporting` — uses low-level symbols *exclusively*, today, with zero exceptions. The architecture is already layered; the hub is the one place the layering is not expressible, and therefore the one place it silently rots.
-
-3. **It replaces one god-object with two objects that have genuinely different lifecycles.** The low half is process-scoped: constructed once at boot from config + plugin registration, never changes. The high half is *library-scoped* — it already has contextvar machinery for exactly that (`set_current_library`, `clear_current_library`, `scoped_current_library`). Today those two lifecycles share one container and one setup path, which is why boot interleaves `set_library_manager` between `set_secrets_provider` and `set_models_manager` with no way to tell that the ordering is meaningful.
-
-4. **It cuts import cost for every consumer.** Anything that wants the console, a secret, or the model deck currently pays for the interpreter. That is `pipelex-api`'s health check, the CLI's `--version`, every plugin's registration module, and every test that touches `get_console`.
-
-5. **It reduces the blast radius of changes to the interpreter.** Today a change to a pipe blueprint's module-level imports can perturb the import graph of `cogt`. After the split it structurally cannot.
-
-## Target shape
-
-Delete `pipelex/hub.py`. Create two modules, each with its own container class and its own module-level accessor functions:
-
-**`pipelex/runtime_hub.py`** — process-scoped infrastructure. Config, console, secrets provider + `get_secret`, class registry, func registry, storage provider, telemetry manager + OTel tracer, models manager + model deck, SDK client manager, inference manager + the three worker getters, content generator (+ its scoped override), report delegate, the isolated-execution probe, the dry-run-forced flag, the event-log override, and the plugin registries (`inference_backend`, `model_lister`, `orchestrator`, `bundle_validator`, `storage_provider`, `secrets_provider`).
-
-**`pipelex/interpreter_hub.py`** — library-scoped method machinery. Library manager + `Library`, the domain/concept/pipe libraries and their lookups (`get_required_pipe`, `get_native_concept`, …), the current-library contextvar family (`set_current_library`, `scoped_current_library`, `resolve_library_dirs`, `get_default_library_dirs`), the pipe router (+ scoped override), pipe run, pipeline manager, observer, and the pipe-func executor (+ its registry and scoped override).
-
-`interpreter_hub` imports `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`.** That single arrow is the whole architecture, and it is what the guard checks.
-
-Deleting the `pipelex.hub` name entirely — rather than keeping it as an alias for either half — is deliberate: every stale import then fails loudly at import time instead of silently resolving to the wrong layer. It is also consistent with the no-backward-compatibility principle.
-
-## Decisions to settle before coding
-
-- **D1 — module names.** Recommended: `pipelex/runtime_hub.py` and `pipelex/interpreter_hub.py`, both flat at the package root, `pipelex/hub.py` deleted. Alternatives considered: keeping `pipelex/hub.py` for one half (rejected — a stale import would silently succeed); `library_hub` for the high one (rejected — it also holds the router, the runner, and the pipeline manager); a `pipelex/hubs/` package (workable, but `pipelex.hubs.services` reads worse than `pipelex.runtime_hub` at 300+ call sites). Note for review: `interpreter_hub` borrows MTHDS's noun for a runtime container — acceptable here because the object genuinely holds the loaded method's libraries, but worth a conscious nod given the brand-boundary rule.
-- **D2 — one container or two.** Recommended: **two** (`RuntimeHub` and `InterpreterHub`, each its own singleton). One container would have to live in the low module, which forces every high-level slot to a quoted `TYPE_CHECKING` annotation — that keeps the god-object and adds a fig leaf. Two is affordable: `PipelexHub()` is constructed in exactly two production sites (`pipelex/pipelex.py:120`, `pipelex/cli/commands/doctor_cmd.py:774`) and three test sites, and `get_pipelex_hub`/`set_pipelex_hub` appear in five files total.
-- **D3 — where `get_pipe_func_executor_registry` lands.** It is a plugin registry (low by kind) whose protocol lives in `pipe_operators/func/` (high by location). Recommended: **high**, with the underlying inversion — `pipelex/plugins/pipe_func_executor_registry.py` importing from `pipe_operators/` — recorded as a follow-up rather than fixed here.
-- **D4 — does `core/` join the low layer in this change?** Recommended: **no, not in phase 1.** Five `core/` modules use high-hub symbols (`stuff_factory`, `memory/input_shaper`, `pipes/stuff_spec/stuff_spec_factory`, `pipes/inputs/input_stuff_specs_factory`, `pipes/output/output_renderer`); converting them means passing resolved concepts in rather than looking them up, which is design work, not mechanical. Phase 4 does it; the guard's low-layer set widens to include those modules only when it lands.
-
-## Phases
-
-### Phase 0 — declare the boundary
-
-- [ ] 0.1 Settle D1–D4.
-- [ ] 0.2 Take the **baseline measurement** below and record it in this file, so phase 1 has a before to compare against.
-- [ ] 0.3 Write `docs/contribute/hub-layering.md` — the two hubs, what lives in each, the one-arrow rule, how the guard enforces it, and how to record an exception. Model it on `docs/contribute/keyword-only-arguments.md`, which is the repo's established shape for a mechanically-enforced convention.
-- [ ] 0.4 Update `docs/under-the-hood/architecture-overview.md` to name the boundary (it currently walks `pipe_controllers` → `pipe_operators` → `core` → `cogt` → `plugins` without ever mentioning the hub).
-
-### Phase 1 — the split
-
-- [ ] 1.1 Create `pipelex/runtime_hub.py`: the `RuntimeHub` container + the low accessors. Verify its module-level imports name nothing from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `core.bundles`, `core.concepts`, or `core.pipes`.
-- [ ] 1.2 Create `pipelex/interpreter_hub.py`: the `InterpreterHub` container + the high accessors, importing `runtime_hub` for anything it needs.
-- [ ] 1.3 Delete `pipelex/hub.py`.
-- [ ] 1.4 Rewrite the call sites — 309 files, 29 of them with parenthesized multi-line import blocks. Script the rewrite from the symbol→module partition, then hand-review the 36 straddling files, which are the only ones that gain a second import line.
-- [ ] 1.5 Re-wire boot: `Pipelex.setup` constructs and populates both hubs; the low one fully before the high one (today the setter calls interleave). Same for `doctor_cmd` and the three test sites.
-- [ ] 1.6 Replace the three `importlib.import_module("pipelex.hub")` hacks in `core/concepts/` with plain `from pipelex.runtime_hub import get_class_registry`, and delete the `_get_class_registry` shims.
-
-**CHECKPOINT H-1** — zero behavior change. Gates: `make agent-check` + **full** `make agent-test` (no test rewrites beyond import lines) + `make drift-check`. Expect the **`cli-docs` drift contract to fire** — 45 CLI files import the hub and `pipelex/cli/**/*.py` is a trigger; review `docs/tools/cli/` and `pipelex/cli/agent_cli/CLAUDE.md`, then `make drift-ack`. Re-take the measurement and record the after.
-
-### Phase 2 — enforce it
-
-- [ ] 2.1 Add `pipelex-dev check-hub-layering` (guard in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`, command in `check_hub_layering_cmd.py`), following the `check-keyword-only` precedent exactly. Rule: a module in the declared low layer may not import `pipelex.interpreter_hub`. It must catch the string-literal `importlib.import_module("pipelex.interpreter_hub")` form too — that is precisely how the current cycle hides.
-- [ ] 2.2 Declare the low layer: `pipelex/tools/**`, `pipelex/system/**`, `pipelex/cogt/**`, `pipelex/plugins/**`, `pipelex/reporting/**`. All five are 100% compliant today, so the guard hard-blocks from day one with an empty exception list.
-- [ ] 2.3 Wire into `make agent-check`, the `make check` aggregate, and CI, with a `chl` alias.
-- [ ] 2.4 Unit tests for the guard (positive, negative, and the `importlib` string form), mirroring `tests/unit/pipelex/cli/dev/test_keyword_only_guard_*.py`.
-- [ ] 2.5 A closure regression test: import `pipelex.cogt.content_generation.content_generator` in a subprocess and assert no `pipelex.libraries.*`, `pipelex.pipe_operators.*`, `pipelex.pipe_controllers.*`, or `pipelex.codegen.*` module is in `sys.modules`. The lint guards the *rule*; this guards the *property*, which is what actually matters and which a future stray import elsewhere could break without touching a hub import.
-
-**CHECKPOINT H-2** — boundary declared, enforced, and regression-tested.
-
-### Phase 3 — the placement residue
-
-Neither of these is coupling; both are types living in the wrong package, and each is independently correct.
-
-- [ ] 3.1 **`JobMetadata`.** It lives in `pipelex/pipeline/job_metadata.py` but is an argument to essentially every cogt call — it accounts for 17 of the 18 `cogt → pipeline` import statements, and it drags `graph.trace_context` → `graph.graph_config` into every closure that touches inference. Move `job_metadata`, and decide whether `trace_context` moves with it or stops depending on `graph_config`. Also move `JobMetadataError` out of `pipeline/exceptions.py` (the sole remaining `cogt → pipeline` edge, in `llm_worker_abstract.py`).
-- [ ] 3.2 **`cogt.templating.*`.** `TemplateCategory`, `TemplatingStyle`, `TextFormat`, and `TagStyle` are imported by eight `tools/jinja2/` and `tools/mermaid/` modules — they are templating primitives sitting under `cogt/`, making `tools` (the intended bottom layer) depend on `cogt`. Decide: move them down to `tools`, or accept `cogt` as below `tools` and document that.
-
-**CHECKPOINT H-3** — placement residue resolved or explicitly deferred with a recorded rationale.
-
-### Phase 4 — `core/` joins the low layer
-
-- [ ] 4.1 Convert the five `core/` straddlers to take resolved concepts/pipes as arguments instead of reaching for `get_concept_library` / `get_native_concept` / `get_required_concept` / `get_required_pipe`. Callers that have a library pass the resolved value; callers that do not are, by construction, in the high layer already.
-- [ ] 4.2 Widen the guard's low layer to include `pipelex/core/**`.
-
-**CHECKPOINT H-4 = done** — update `docs/contribute/hub-layering.md` with the final layer set, and the CHANGELOG with a breaking-change note (`pipelex.hub` is gone; importers must choose `pipelex.runtime_hub` or `pipelex.interpreter_hub`).
-
-## Exit criteria — measured, not asserted
-
-The headline property is that the inference layer must stop importing the interpreter. Measure it directly, from the repo root on a synced venv:
-
-```bash
-.venv/bin/python - <<'PY'
-import sys
-from pathlib import Path
-
-import pipelex.cogt.content_generation.content_generator # noqa: F401
-
-INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
-loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
-interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
-sloc = 0
-for mod in loaded.values():
- file = getattr(mod, "__file__", None)
- if file:
- sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
-print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
-print("offenders:", interpreter)
-PY
-```
-
-| | today | target after phase 1 |
-| --- | --- | --- |
-| interpreter modules loaded | 50 | **0** |
-| pipelex modules loaded | 357 | ≤ 260 |
-| SLOC loaded | 29,193 | ≤ 19,000 |
-
-The module/SLOC targets come from importing exactly the types a low-only hub would annotate — 236 modules / 17,683 SLOC, with the interpreter subpackages at zero — plus headroom for cogt's own modules. If phase 1 lands and `interpreter modules` is not 0, the snippet prints the offenders: something imports the interpreter outside the hub, and the shortest import path to it is what to fix. Swap the imported module in the snippet to measure any other entry point (`pipelex.pipelex`, `pipelex.runtime_hub`, …).
-
-## Risks and containment
-
-- **Big mechanical diff (309 files).** Contained by: the rewrite is scriptable from a symbol→module table; `pipelex.hub` ceasing to exist means any missed site is an import error, not a silent wrong-layer resolution; and the full `make agent-test` suite is the zero-behavior-change bar.
-- **Two singletons, two lifecycles, two teardowns.** Contained by the tiny construction surface (five sites total). Watch `Pipelex.teardown` / `teardown_if_needed` and the test fixtures that reset hub state — a half-reset hub between tests is the realistic failure mode, and it shows up as cross-test pollution rather than a clean failure. Worth an explicit "both hubs reset" assertion in the shared fixture.
-- **Cross-repo breakage.** `pipelex.hub` is imported by our plugins and by consumers of the runtime. Grep `pipelex-api/`, `pipelex-worker/`, our orchestrator plugins, and `pipelex-mistralai-workflows/` before merging, and stage the follow-ups as a release-gated sweep. `scoped_pipe_router` / `set_pipe_router` / `teardown_current_pipe_router` are documented as depended upon by our Mistral Workflows plugin, so their new home is a published contract change.
-- **`plugins/` reaching up.** `plugins/pipe_func/pipe_func_plugin.py` and `plugins/pipe_func_executor_registry.py` import from `pipe_operators/`, and `plugins/direct/direct_plugin.py` from `pipeline/`. These do not import the hub, so the guard will not flag them — but they mean "plugins is a low layer" is not yet unconditionally true. Named here so the claim in the docs stays honest; fixing them is out of scope.
-
-## Explicitly out of scope
-
-- **A general layering ratchet** ("no low module may import any high module", with an allowlist). The measured inversion set is real but larger than this change should carry — `tools → cogt` (15 statements), `cogt → core` (21), `system → cogt` (8), `plugins → runtime_bridge` (6), and one genuine wart, `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. Phase 3 removes the two biggest clusters; the general rule is a sequel worth considering once they are gone.
-- **Eager optional-SDK imports.** `pipelex/tracing/event_log_factory.py` imports `dynamodb_event_log` at module level, which runs a module-level `try: import boto3`, so `boto3`/`botocore`/`jmespath`/`dateutil`/`six` load in every process that touches the tracing factory — including runs that will never touch DynamoDB. A three-line fix (import `DynamoDBEventLog` inside the factory branch, the pattern already used for `pypdfium2` in `cogt/content_generation/render_generate.py`), entirely independent of this plan. Note that most other heavy roots (`posthog`, `pypdfium2`, `pillow`, `polyfactory`, `datamodel-code-generator`) are **base** dependencies, not extras — so they are not the same kind of finding.
diff --git a/wip/hub/hub-split-tracker.md b/wip/hub/hub-split-tracker.md
deleted file mode 100644
index 0e3f5fed3..000000000
--- a/wip/hub/hub-split-tracker.md
+++ /dev/null
@@ -1,743 +0,0 @@
-# TODOS — split `pipelex.hub` into `runtime_hub` + `interpreter_hub` (archived plan)
-
-**Worktree:** `_hub/` · **Branch:** `refactor/Hub-2` (off `6fbdcb2fd`, the #1062 merge) · **PR #1062:** [merged to `dev`](https://github.com/Pipelex/pipelex/pull/1062) 2026-07-27.
-
-**Status: ARCHIVED — track complete.** All phases, the rename, and the full `/review` follow-up (Phases A, B and the F1 remedy) are done and merged, gates green. Archived from the repo-root `TODOS.md` tracker to this file on 2026-07-27, once `_hub/` moved on to the `refactor/Modularity-3` track (see [`wip/refactoring/modularity-refactors.md`](../refactoring/modularity-refactors.md)). What is left is not a phase — it is the release-gated [cross-repo sweep](#cross-repo-sweep), still open. **Jump to [Checkpoint A1](pr-1062-review-followups.md#checkpoint-a1-record--the-f1-remedy) first**, then [Checkpoint B record](#checkpoint-b-record--test-hardening), [Checkpoint A record](#checkpoint-a-record--pr-1062-review-follow-ups), then [▶ Resume here](#-resume-here-the-rename-is-landed) for the state they build on.
-
-> ✅ **The `/review` follow-ups are applied except the release-gated Phase C.** The executable plan is [`wip/hub/pr-1062-review-followups.md`](pr-1062-review-followups.md) — read it before touching this branch. **Phase A** (A1's doc-honesty fix + A2–A8) at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups); **Phase B** (test hardening, B1–B7, every item mutation-verified) at [Checkpoint B](#checkpoint-b-record--test-hardening); **the F1 remedy** (D-R4 = (d)+(c)) at [Checkpoint A1](pr-1062-review-followups.md#checkpoint-a1-record--the-f1-remedy). **Phase C (release-wave additions) is not started** and is gated on the release.
->
-> **F1 is fixed, not just documented.** The layer rule used to be enforced one hop deep, so four modules of the *declared runtime-layer* `pipelex.plugins` package loaded `interpreter_hub` (plus 57–67 interpreter modules) with both gates green. The two leaves — the plugins whose job is to *construct* interpreter-layer objects — now live in **`pipelex/interpreter_plugins/`**, `builtins.py` is split by layer with the composition in the interpreter half, `build_registrar` takes the plugin list and the core-unconditional names as **parameters**, and the guard grew a **transitive rule** that resolves the module-level import graph of `pipelex/` and flags any runtime-layer module that *reaches* the interpreter hub. Measured after: **0 of 473** declared runtime-layer modules breaching, down from 4 of 477; `plugins.discovery` and `plugins.builtins` both load 0 interpreter modules, down from 67. The new rule was verified by re-running it against the pre-remedy tree, where it reproduces F1 exactly. The shipped 0-interpreter-modules headline property was never damaged by the defect and is unchanged.
->
-> The plan also carries additions the [cross-repo sweep](#cross-repo-sweep) tables below are missing — five consumer repos, and the `docs/specs/` + `conformance/` governed surface that names `pipelex.hub` explicitly. Those are Phase C, folded into the release-gated sweep per D-R1. **One addition from the remedy belongs in that sweep too:** any external repo that calls `build_registrar` directly must now pass `builtin_plugins=` and `core_unconditional_plugin_names=`, and anything importing `pipelex.plugins.direct.direct_plugin` or `pipelex.plugins.pipe_func.pipe_func_plugin` must retarget to `pipelex.interpreter_plugins.*`.
-
-The split is landed, the boundary is mechanically enforced (`make check-hub-layering` + a subprocess import-closure test over eight entry points), the misplaced types are moved, and core's data model has joined the runtime layer behind injected providers. Every runtime-layer entry point measures **0 interpreter modules**. Docs and the CHANGELOG breaking-change note are written, and the [runtime/interpreter rename](layer-and-hub-renaming.md) is applied throughout.
-
-**What is left is not a phase** — it is the release-gated [cross-repo sweep](#cross-repo-sweep) (three waves). Nothing else is open.
-
-### Cold start — read in this order
-
-1. [The one rule](#the-one-rule) and [Symbol partition](#symbol-partition) — the settled boundary.
-2. [Checkpoint H-4 record](#checkpoint-h-4-record) — **start here**: why the plan's "all of `core/` goes low" premise was wrong, the `if it names a Pipe, it is high` rule that replaced it, and the injected-provider pattern.
-3. [Checkpoint H-3 record](#checkpoint-h-3-record) — the two type moves, why `TraceContext` had to travel with `JobMetadata`, and why the templating primitives split across two packages.
-4. [Checkpoint H-2 record](#checkpoint-h-2-record) — what the guard actually enforces (two rules, not one), its two carve-outs, and two CI wiring traps.
-5. [Checkpoint H-1 record](#checkpoint-h-1-record) — the split itself, including the two places reality forced a change to the plan (the D5 slot could not live on `RuntimeHub`; boot was deliberately not reordered).
-6. [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md) — the shipped specification: the two halves, "Where core splits", enforcement, and "Placement, not coupling".
-
-Three notes for whoever picks this up:
-
-- **The cross-repo sweep is the only substantial work remaining, and it is release-gated.** Three waves now: the `pipelex.hub` split ([table](#cross-repo-sweep)), the Phase 3 type moves ([table](#cross-repo-impact-added-by-phase-3)), and the Phase 4 moves + signature changes ([table](#cross-repo-impact-added-by-phase-4)). Do all three in one pass per repo.
-- **The `hub-layering-convention` drift contract is now in the manifest.** Louis gave explicit say-so; it was added, reviewed, and acked — see [Proposed, reverted, then landed](#proposed-reverted-then-landed).
-- **`core.pipes.pipe_output → pipeline.pipeline_models` was NOT removed.** H-3 predicted Phase 4 would take it out; it did not. It remains one of the two edges pulling non-inference modules into the inference closure, which is why the module/SLOC rows are flat at H-4. The reason recorded at H-4 — "`pipe_output` is on the Pipe-touching (high) side of the core split" — was **wrong**, and the PR #1062 review corrected it: `pipe_output` names no `Pipe`, imports zero interpreter modules, and sits inside `runtime_hub`'s own closure. It is runtime-layer. What survives is the edge itself: `SpecialPipelineId` is a leaf constant filed in an interpreter-named package. See [`wip/pr-1062-review-notes.md`](../pr-1062-review-notes.md).
-- **The PR #1062 agent-review pass is recorded in [`wip/pr-1062-review-notes.md`](../pr-1062-review-notes.md).** It fixed the `pipe_output` misclassification above, widened the import-closure predicate to name core's Pipe machinery (closing a real `core.pipes.pipe_blueprint` blind spot), and deferred one item: `pipeline` / `pipe_run` / `graph` leak leaf models into every runtime closure, so the predicate cannot name them yet.
-
-Design rationale, alternatives considered, and the full measured argument live in [`wip/hub/hub-split-refactor.md`](hub-split-refactor.md). This file is the executable tracker: what to do, in what order, with the concrete tables the work needs. Where the two disagree, this file wins — it carries the settled decisions and the re-measured numbers.
-
-ℹ **The names in this document are the final ones.** Louis challenged the Phase 0–4 naming at the close of H-4 and settled on a rename, which has since **landed as its own commit**: the layers are **runtime** / **interpreter**, and the hubs are `runtime_hub` (`RuntimeHub`) / `interpreter_hub` (`InterpreterHub`). This tracker has been swept to those names — including the cross-repo tables, so the sweep rewrites external repos exactly once, straight to the final names. The intermediate `service_hub` / `method_hub` names never shipped. The decision, the rejected alternatives, and the mechanical plan are in [`wip/hub/layer-and-hub-renaming.md`](layer-and-hub-renaming.md); [D1](#decisions) keeps the original naming decision's reasoning verbatim.
-
-Note that the prose below still uses "low layer" / "high layer" in the historical checkpoint records (H-1 through H-4), because that was the vocabulary at the time. Read *low* as **runtime** and *high* as **interpreter**; the shipped code, tests, guard and docs use only the new terms.
-
-## The one rule
-
-`interpreter_hub` may import `runtime_hub`. **`runtime_hub` must never import `interpreter_hub`.** That single arrow is the whole architecture, and it is what the Phase 2 guard checks.
-
-> At H-1 only the forbidden direction is load-bearing; the permitted one turned out to be unused, because the one low-layer thing `interpreter_hub` needs (the class-registry scoping slot) lives below *both* hubs. Importing either hub loads the other in neither direction — stronger than the rule requires. Phase 2's guard should still check the forbidden direction, not assert the permitted one exists.
-
-`pipelex/hub.py` is deleted outright — not kept as an alias for either half. A stale import must fail loudly at import time rather than silently resolve to the wrong layer.
-
-## Baseline — measured on the base commit
-
-Reproduce with the snippet in [Exit criteria](#exit-criteria--measured-not-asserted). Re-taken at CHECKPOINT H-1 — the after is in [Measured after](#measured-after).
-
-| | baseline | target after Phase 1 |
-| --- | --- | --- |
-| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | **0** |
-| pipelex modules loaded | 357 | ≤ 260 |
-| SLOC loaded | 29,193 | ≤ 19,000 |
-
-Call-site inventory (`ast`-parsed over `pipelex/` + `tests/`, zero symbols left unclassified by the partition below):
-
-| | count |
-| --- | --- |
-| files importing `pipelex.hub` | 309 |
-| — low-only | 134 |
-| — high-only | 139 |
-| — straddling (gain a second import line) | 36 |
-| parenthesized multi-line import blocks | 29 |
-| `PipelexHub()` construction sites | 5 (2 production, 3 test) |
-| `importlib.import_module("pipelex.hub")` hacks | 3 |
-
-## Decisions
-
-**D1 — module names. SUPERSEDED by the [runtime/interpreter rename](layer-and-hub-renaming.md); the modules are now `pipelex/runtime_hub.py` + `pipelex/interpreter_hub.py`.** The original decision, kept because its rejected alternatives are still live reasoning: *SETTLED: `pipelex/service_hub.py` + `pipelex/method_hub.py`, both flat at the package root, `pipelex/hub.py` deleted. Rejected: keeping `hub.py` for one half (a stale import would silently succeed); `library_hub` (the high half also holds the router, the runner, and the pipeline manager); a `pipelex/hubs/` package (`pipelex.hubs.services` reads worse than `pipelex.service_hub` at 300+ call sites). Noted for review: `method_hub` borrows the MTHDS noun for a runtime container — acceptable because the object genuinely holds the loaded method's libraries, but it is a conscious call against the brand-boundary rule.* That last note is exactly what Louis acted on at the close of H-4: the flat-at-the-root shape and the no-alias deletion survive unchanged, only the two names moved. `library_hub` was re-proposed and re-rejected during the rename, on the same grounds plus one more — a library is inert, while the container is active machinery.
-
-**D2 — one container or two. SETTLED: two** — `RuntimeHub` and `InterpreterHub`, each its own singleton, each with its own module-level accessors. One container would have to live in the low module, forcing every high-level slot to a quoted `TYPE_CHECKING` annotation — that keeps the god-object and adds a fig leaf. Two is affordable: the construction surface is five sites total.
-
-**D3 — where `get_pipe_func_executor_registry` lands. SETTLED: high (`interpreter_hub`).** It is a plugin registry by kind but its protocol lives in `pipe_operators/func/`. The underlying inversion — `pipelex/plugins/pipe_func_executor_registry.py` importing from `pipe_operators/` — is recorded as a follow-up (see [Known inversions](#known-inversions-not-fixed-here)), not fixed here.
-
-**D4 — does `core/` join the low layer now? SETTLED: no, not in Phase 1.** Five `core/` modules use high-hub symbols; converting them means passing resolved concepts in rather than looking them up, which is design work, not mechanical. Phase 4 does it, and the guard's low-layer set widens only when that lands.
-
-**D5 — `get_class_registry` is low but reads the library manager. SETTLED: callable resolver slot, defaulting to "no scoping", installed downward at boot.** Not in the design doc; surfaced while building the partition table. It is the decision that makes Phase 1.6 possible at all, so it is recorded here in full.
-
-> **Amended at implementation (H-1): the slot does not live on `RuntimeHub`.** It lives in a new leaf module, `pipelex/system/registries/class_registry_access.py`, reached through the `class_registry_scoping` module singleton. The mechanism, the default, and the downward-at-boot crossing are all exactly as designed below — only the physical home moved, and it was forced by a measured cycle rather than chosen. See [Checkpoint H-1 record → D5 amendment](#d5-amendment-the-resolver-slot-could-not-live-on-servicehub).
-
-Today's body reaches straight into the high layer:
-
-```python
-def get_class_registry() -> ClassRegistryAbstract:
- library_id = _library_id.get()
- if library_id is not None:
- registry = get_library_manager().get_library_class_registry(library_id) # ← HIGH
- if registry is not None:
- return registry
- return KajsonManager.get_class_registry()
-```
-
-`get_class_registry` is the single symbol all three `importlib` hacks want, and it has 29 importers spread across both layers — so it must be low, and it must keep its library scoping (Phase 1 is zero-behavior-change).
-
-Resolution: `RuntimeHub` grows a `Callable[[], ClassRegistryAbstract | None]` slot — default returns `None`, and boot installs the library-scoped resolver once `InterpreterHub` is populated. `get_class_registry` calls the slot and falls back to `KajsonManager.get_class_registry()`. The `_library_id` ContextVar stays in `interpreter_hub` with the rest of its family; the resolver closure is what crosses, and it crosses downward at boot, not as an import.
-
-This is not a new pattern — it is exactly how `_isolated_execution_probe` already works (`HubSlot.ISOLATED_EXECUTION_PROBE`, defaulting to `_never_in_isolated_execution`), so the precedent, the naming, and the plugin-claim machinery are all in place.
-
-Alternative considered and rejected: move the whole `_library_id` contextvar family down into `runtime_hub`. Simpler (no indirection) but it splits the "current library" concept across both modules and makes `pipelex.runtime_hub` export `set_current_library`, which reads wrong. Also rejected: drop the scoping from `get_class_registry` and expose a separate high `get_scoped_class_registry` — that is a behavior change, and `tests/unit/pipelex/test_class_registry_scoping.py` pins the current semantics.
-
-`tests/unit/pipelex/test_class_registry_scoping.py` is the regression guard for D5 — it must keep passing unmodified except for its import lines.
-
-## Symbol partition
-
-Complete and verified: an `ast` sweep of every `from pipelex.hub import …` across `pipelex/` and `tests/` classified every imported name against these two sets with nothing left over.
-
-### → `pipelex/runtime_hub.py` (runtime layer)
-
-| group | symbols |
-| --- | --- |
-| container | `RuntimeHub`, `get_runtime_hub`, `set_runtime_hub` |
-| config | `get_required_config`, `get_optional_config` |
-| console | `get_console` |
-| secrets | `get_secrets_provider`, `get_secret` |
-| system registries | `get_class_registry` (see D5), `get_func_registry` |
-| storage | `get_storage_provider` |
-| telemetry | `get_telemetry_manager`, `get_otel_tracer` |
-| models | `get_models_manager`, `get_model_deck`, `get_sdk_client_manager` |
-| inference | `get_inference_manager`, `get_llm_worker`, `get_img_gen_worker`, `get_extract_worker` |
-| content generation | `get_content_generator`, `scoped_content_generator` |
-| reporting | `get_report_delegate`, `is_in_isolated_execution` |
-| run mode | `is_dry_run_forced` |
-| tracing | `scoped_event_log`, `get_event_log_override` |
-| plugin registries | `get_inference_backend_registry`, `get_model_lister_registry`, `get_orchestrator_registry`, `get_bundle_validator_registry`, `get_storage_provider_registry`, `get_secrets_provider_registry` |
-
-### → `pipelex/interpreter_hub.py` (interpreter layer)
-
-| group | symbols |
-| --- | --- |
-| container | `InterpreterHub`, `get_interpreter_hub`, `set_interpreter_hub` |
-| library manager | `get_library_manager`, `get_library` |
-| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_pipe_source` |
-| current-library contextvar | `set_current_library`, `get_current_library`, `get_current_library_id_or_none`, `clear_current_library`, `scoped_current_library` |
-| library dirs | `resolve_library_dirs`, `get_default_library_dirs` |
-| pipe router | `get_pipe_router`, `set_pipe_router`, `teardown_current_pipe_router`, `scoped_pipe_router` |
-| run | `get_pipe_run`, `get_pipeline_manager`, `get_pipeline` |
-| pipe func (D3) | `get_pipe_func_executor`, `scoped_pipe_func_executor`, `get_pipe_func_executor_registry` |
-
-Setter methods follow their getters onto the matching container. Do **not** delete the accessors with no in-tree importers (`get_bundle_validator_registry`, `get_orchestrator_registry`, `get_pipe_func_executor_registry`, `get_default_library_dirs`, `get_func_registry`, `scoped_pipe_func_executor`) — they are reached internally via the container and several are live external plugin contract (see [Cross-repo sweep](#cross-repo-sweep)). Placement is decided by kind, not by in-tree usage.
-
-### Straddling files — hand-review list for step 1.4
-
-These are the only files that gain a second import line. Everything else is a one-line module swap.
-
-| file | low symbols | high symbols |
-| --- | --- | --- |
-| `pipelex/cli/commands/build/inputs/_inputs_core.py` | `get_telemetry_manager` | `get_library_manager`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
-| `pipelex/cli/commands/build/output/_output_core.py` | `get_telemetry_manager` | `get_library_manager`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
-| `pipelex/cli/commands/build/runner/_runner_core.py` | `get_telemetry_manager` | `get_current_library_id_or_none`, `get_library_manager`, `get_required_pipe` |
-| `pipelex/cli/commands/codegen/inputs_cmd.py` | `get_telemetry_manager` | `get_required_pipe` |
-| `pipelex/cli/commands/show_cmd.py` | `get_console`, `get_models_manager`, `get_secrets_provider`, `get_telemetry_manager` | `get_library_manager`, `get_pipe_library`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
-| `pipelex/cli/commands/validate/_validate_core.py` | `get_console`, `get_telemetry_manager` | `get_library_manager`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
-| `pipelex/cli/commands/which_cmd.py` | `get_console`, `get_telemetry_manager` | `get_library_manager`, `get_optional_pipe`, `get_pipe_source`, `resolve_library_dirs`, `set_current_library` |
-| `pipelex/core/stuffs/stuff_factory.py` | `get_class_registry` | `get_concept_library`, `get_native_concept`, `get_required_concept` |
-| `pipelex/libraries/library_manager.py` | `get_class_registry` | `get_current_library`, `get_current_library_id_or_none`, `scoped_current_library` |
-| `pipelex/pipe_operators/compose/pipe_compose.py` | `get_class_registry` | `get_concept_library`, `get_native_concept` |
-| `pipelex/pipe_operators/extract/pipe_extract.py` | `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
-| `pipelex/pipe_operators/func/pipe_func.py` | `get_class_registry` | `get_pipe_func_executor` |
-| `pipelex/pipe_operators/img_gen/pipe_img_gen.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
-| `pipelex/pipe_operators/llm/helpers.py` | `get_class_registry` | `get_required_concept` |
-| `pipelex/pipe_operators/llm/pipe_llm.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept`, `get_required_concept` |
-| `pipelex/pipe_operators/structure/pipe_structure.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
-| `pipelex/pipe_run/dry_run_in_process.py` | `scoped_content_generator`, `scoped_event_log` | `get_library_manager`, `scoped_pipe_router` |
-| `pipelex/pipeline/bundle_validator.py` | `get_telemetry_manager`, `scoped_content_generator` | `clear_current_library`, `get_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipe_library`, `scoped_pipe_router`, `set_current_library` |
-| `pipelex/pipeline/pipeline_run_setup.py` | `get_event_log_override`, `get_otel_tracer`, `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipeline_manager`, `get_required_pipe`, `set_current_library` |
-| `pipelex/pipeline/runner.py` | `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipe_run`, `get_pipeline_manager`, `set_current_library` |
-| `tests/integration/pipelex/pipeline/test_bundle_validator.py` | `get_telemetry_manager` | `clear_current_library`, `get_library_manager`, `get_required_pipe` |
-| `tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py` | `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipeline_manager`, `set_current_library` |
-| `tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py` | `get_report_delegate` | `clear_current_library`, `get_library_manager` |
-| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
-| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
-| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
-| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py` | `get_class_registry` | `get_native_concept`, `get_pipe_library`, `get_pipe_router` |
-| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py` | `get_content_generator` | `get_pipe_library`, `get_pipe_router` |
-| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py` | `get_content_generator` | `get_pipe_library`, `get_pipe_router` |
-| `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py` | `get_report_delegate` | `get_native_concept`, `get_pipe_router`, `get_required_pipe` |
-| `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py` | `get_report_delegate` | `get_native_concept`, `get_pipe_router`, `get_required_pipe` |
-| `tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
-| `tests/integration/pipelex/system/test_hub_slot_injection_precedence.py` | `get_content_generator` | `get_pipe_router` |
-| `tests/unit/pipelex/core/memory/input_shaper/conftest.py` | `get_class_registry` | `get_concept_library` |
-| `tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py` | `get_class_registry` | `get_concept_library` |
-| `tests/unit/pipelex/test_class_registry_scoping.py` | `get_class_registry` | `clear_current_library`, `get_library_manager`, `set_current_library` |
-
-Note the shape of the `pipe_operators/` rows: every one of them straddles for the same reason — `get_class_registry` / `get_content_generator` / `get_model_deck` (low) next to `get_concept_library` / `get_native_concept` (high). That is the D4 boundary showing through, and it is what Phase 4 dissolves.
-
-## Phases
-
-### Phase 0 — declare the boundary ✅
-
-- [x] 0.1 Confirm **D5**. Settled as recorded above, and amended at implementation (the slot's home moved; the mechanism did not).
-- [x] 0.2 Baseline re-taken on the branch tip and confirmed identical to the table above (357 / 29,193 / 50).
-- [x] 0.3 Wrote [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md) — the two hubs, the partition, how to place a new symbol, the class-registry exception, the measurement, enforcement, and the known inversions. Modelled on `keyword-only-arguments.md`. Its "Enforcement" section describes what is true at H-1 and is rewritten by Phase 2 when the guard lands.
-- [x] 0.4 Updated `docs/under-the-hood/architecture-overview.md` with a "What Keeps The Layers Apart: The Two Hubs" section naming the boundary and the one-arrow rule, linking to the contributor doc. Added both pages to the `mkdocs.yml` nav.
-
-### Phase 1 — the split ✅
-
-- [x] 1.1 Created `pipelex/runtime_hub.py`. Module-level imports verified to name nothing from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `core.bundles`, `core.concepts`, or `core.pipes`.
-- [x] 1.2 Created `pipelex/interpreter_hub.py`, importing `runtime_hub`'s layer for the D5 install. `set_interpreter_hub` installs the resolver, so scoping is live exactly when a InterpreterHub exists and a caller cannot forget to wire it.
-- [x] 1.3 Deleted `pipelex/hub.py`.
-- [x] 1.4 Rewrote all 309 call sites via an `ast` pass over the whole import statement (the 29 parenthesized blocks came through intact). The 36 straddlers each gained a second import line, as predicted. **Two string-literal references the AST pass could not see broke the suite and had to be found by running it** — see the record below.
-- [x] 1.5 Re-wired boot. Both hubs are constructed and installed at the top of `Pipelex.__init__`; every setter was retargeted to its own container. **The setter sequence was deliberately NOT reordered** — see the record below.
-- [x] 1.6 Replaced all three `importlib.import_module("pipelex.hub")` hacks with plain top-level imports and deleted the `_get_class_registry` shims. The import target is the new leaf module, not `runtime_hub` — that is the D5 amendment.
-- [x] 1.7 `Pipelex.teardown` and the `make()` failure path now release both hubs' process-global state. Pinned by `tests/unit/pipelex/test_hub_lifecycle.py`, which asserts a boot installs both singletons and that the reset really drops the scoping a InterpreterHub installed.
-
-**CHECKPOINT H-1** — zero behavior change.
-
-Gates: `make agent-check` + **full** `make agent-test` (no test edits beyond import lines) + `make drift-check`. Expect the **`cli-docs` drift contract to fire** — `pipelex/cli/**/*.py` is a trigger and the rewrite touches many CLI files. Review `docs/tools/cli/` and `pipelex/cli/agent_cli/CLAUDE.md`, then `make drift-ack` with an honest rationale ("import-path-only change, CLI surface unaffected" is legitimate if that is what the review found). Re-take the measurement and record the after against the target table.
-
-### Checkpoint H-1 record
-
-Written at the checkpoint so Phase 2 can start cold. Everything below is what actually happened, including where the plan was wrong.
-
-#### Measured after
-
-| | baseline | target | **after H-1** |
-| --- | --- | --- | --- |
-| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | **0** | **0** ✅ |
-| pipelex modules loaded | 357 | ≤ 260 | 275 |
-| SLOC loaded | 29,193 | ≤ 19,000 | 21,186 |
-
-The headline property is met exactly: the inference layer now loads **zero** `libraries` / `pipe_operators` / `pipe_controllers` / `codegen` / `builder` modules. The module and SLOC targets were missed, and the reason is that the estimate was wrong rather than the change: those targets were derived from "236 modules / 17,683 SLOC *plus headroom for cogt's own modules*", and the real headroom is ~40 modules / ~3,500 SLOC, not the ~24 / ~1,300 assumed. A low-only hub's own closure measures 235 modules / 17,675 SLOC on this branch — within 1 of the estimate — so the partition is exactly as tight as designed; only the headroom guess was low. **Do not treat the module/SLOC rows as open work.** Squeezing them further means attacking `cogt`'s own dependency weight (`system.telemetry.otel_factory` → `core.pipes.pipe_output` → `core.stuffs.stuff` is the fattest edge), which is Phase 3/4 territory, not the hub boundary.
-
-#### D5 amendment: the resolver slot could not live on `RuntimeHub`
-
-D5 assumed `core/concepts/` could reach `get_class_registry` from `pipelex.runtime_hub`. It cannot. `core.concepts.concept` is **inside `runtime_hub`'s own import closure**:
-
-```
-runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factory
- → core.pipes.pipe_output → core.stuffs.stuff → core.concepts.concept
-```
-
-so a module-level `from pipelex.runtime_hub import get_class_registry` in `concept.py` is a hard cycle — and it fails in *both* import orders, which is why it could not simply be ordered around. The design doc's claim that "a hub that does not import `Concept` has no cycle with `concept.py`" was half right: the cycle is not via `Concept`, it is via `cogt → system → core`.
-
-Resolution, which preserves every property D5 was chosen for:
-
-- `pipelex/system/registries/class_registry_access.py` — a new leaf module importing nothing from `pipelex`. Holds the real `get_class_registry` plus the `class_registry_scoping` slot (a module singleton in the `config_manager` style; the resolver default returns `None`, so a RuntimeHub-only process degrades to the global registry rather than raising, exactly as [Risks](#risks-and-containment) requires).
-- `pipelex.runtime_hub.get_class_registry` delegates to it and stays the **public** accessor — so the symbol partition table above is unchanged and the cross-repo contract is still "low symbols come from `runtime_hub`".
-- The three `core/concepts/` modules import the leaf directly, because they are the one place the public accessor is unreachable.
-- `interpreter_hub.set_interpreter_hub` installs the library-scoped resolver; `Pipelex.teardown` calls `class_registry_scoping.reset()`.
-
-`tests/unit/pipelex/test_class_registry_scoping.py` (the D5 regression guard) passes unmodified except for its import lines, as required.
-
-#### Boot was not reordered — deliberately
-
-Step 1.5 predicted the setter sequence would "split cleanly at line 475 with no reordering" once the duplicate pair was deleted. It does not, and cannot: **D3 puts the PipeFunc executor on the high hub**, so `set_pipe_func_executor_registry` and `set_pipe_func_executor` are InterpreterHub calls sitting in the middle of the RuntimeHub run, and `set_isolated_execution_probe` is a RuntimeHub call sitting after the InterpreterHub ones.
-
-Reordering to force a clean split would have moved setters across documented ordering dependencies (the storage-provider block explicitly resolves *after* secrets is on the hub so the GCP factory's secret read works) — a real behavior risk at a checkpoint whose bar is zero behavior change. So: **both hubs are constructed and installed at the top of `__init__`, and the setter sequence is otherwise byte-identical in order.** That delivers what "populate RuntimeHub fully before InterpreterHub" was actually protecting against — no setter can ever run against a missing hub — without touching execution order. Untangling the interleave belongs with D3's inversion, not here.
-
-#### Findings in passing — both resolved, one bigger than recorded
-
-- **Duplicate `set_library_manager` deleted** ✅. Confirmed dead: nothing between the two pairs reads it, and `make tb` plus the full suite pass without it.
-- **`_observer` deleted** ✅ — but the tracker's "confirm no external consumer sets it" check turned up something worse than dead code. `docs/advanced/observer-provider-injection.md` **documented `hub.set_observer()` as the public way to register a custom observer**, and that documented API never worked: the value was written and never read, while the live path is `Pipelex.make(observers={...})` → `MultiObserver` → `PipeRouter`. Anyone following that page got a silently ignored observer. Both that page and `docs/advanced/index.md` (which showed a bare `PipelexHub()` being constructed and configured — equally inert) are rewritten to the mechanism that actually works, with a warning against hand-constructing a hub. Verified across the workspace: no repo sets `set_observer`.
-
-#### One fix outside the plan, required by the exit criterion
-
-After the split the measurement still reported 3 interpreter modules, via `content_generator → pipelex.config → plugins.pipe_func_executor_registry → pipe_operators.func.pipe_func_executor_protocol` — D3's underlying inversion, which [Known inversions](#known-inversions-not-fixed-here) had scheduled as "not fixed here". But the exit criterion demands 0 and instructs that the printed offender is what to fix, and Phase 2.5's closure regression test would fail on it regardless. The import is **type-only**, so it was deferred under `TYPE_CHECKING` with a string annotation on the type alias. The placement inversion itself is untouched and stays recorded.
-
-#### Landmines the AST rewrite could not see
-
-`pipelex.hub` ceasing to exist turns a missed *import* into an immediate `ImportError` — but not a missed **string literal**. Two of those existed, and neither is reachable by an import-graph tool:
-
-- `tests/helpers/init_cmd_helpers.py` — `mocker.patch("pipelex.hub.get_console", ...)`. This broke **36 tests** across the init CLI suites, and the failure surfaced as `AttributeError: module 'pipelex' has no attribute 'hub'` from `pkgutil.resolve_name`, nowhere near the hub.
-- `tests/unit/pipelex/cli/test_agent_cli_output_discipline.py` — `mocker.patch("...agent_cli_factory.PipelexHub.get_optional_instance")`, caught by grep before the run.
-
-If Phase 2's guard is meant to catch "the string-literal `importlib.import_module` form", it should also be pointed at `mocker.patch` targets — that is where this class of reference actually lives in this repo.
-
-#### Housekeeping done at H-1
-
-- **Subject grants migrated**: 54 `pipelex/hub.py::` entries → 55 under `pipelex/runtime_hub.py::` / `pipelex/interpreter_hub.py::` (`set_instance` and `set_pipelex_hub` each split in two; `set_observer` dropped with the state). `make cko` is green, and staleness is symmetric so a missed entry would have failed.
-- **Doc references swept**: `docs/under-the-hood/{pipe-routing-and-execution,runtime-bridge-and-transport,execution-graph-tracing}.md`, `docs/advanced/{index,observer-provider-injection}.md`, `tests/CLAUDE.md`, and in-code docstrings in `signature_walk.py` / the keyword-only guard modules. CHANGELOG history entries were left alone (they are release records). No live `pipelex.hub` reference remains anywhere in `pipelex/`, `tests/`, or `docs/`.
-
-#### Still open at H-1
-
-- **The CHANGELOG breaking-change note is not written yet** — it stays scheduled at H-4 per the plan, but `pipelex.hub` is *already* gone as of this checkpoint. If this branch is ever merged before H-4, write it first.
-- The **cross-repo sweep** is untouched and still release-gated.
-- One semantic edge worth knowing: `class_registry_scoping` is process-global, so the doctor path (which installs a fresh `RuntimeHub` but leaves any existing `InterpreterHub` in place) now keeps library scoping alive where the single hub would have raised. Strictly more coherent — the InterpreterHub genuinely is still installed — and unreachable in practice, since doctor runs in its own process. Noted rather than fixed.
-
-### Phase 2 — enforce it ✅
-
-- [x] 2.1 Added `pipelex-dev check-hub-layering` — guard in `pipelex/cli/dev_cli/commands/hub_layering_guard.py` (stdlib-only AST core), command in `check_hub_layering_cmd.py` (rich presentation), following the `keyword_only_guard.py` / `check_keyword_only_cmd.py` split exactly. Catches imports **and** string literals, and resolves relative imports against the importing module's own package. **The guard grew a second rule beyond the plan** — see the record below.
-- [x] 2.2 Low layer declared as `pipelex.cogt`, `pipelex.plugins`, `pipelex.reporting`, `pipelex.system`, `pipelex.tools`. All five compliant; the guard hard-blocks with an empty exception list (one escape-hatch marker exists, on the guard's own declaration of the forbidden path).
-- [x] 2.3 Wired into `make agent-check`, the `make check` aggregate, and both CI lint workflows, with the `chl` alias.
-- [x] 2.4 `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` — layer membership, both directions of the arrow, every import spelling (plain / aliased / `from pipelex import interpreter_hub` / relative), both string forms, the prose-is-not-a-reference and `runtime_hub`-is-not-`hub` boundary cases, the `TYPE_CHECKING` carve-out and its three non-exempt neighbours, the escape hatch, and the dead-module rule across all three layers.
-- [x] 2.5 `tests/unit/pipelex/test_runtime_layer_import_closure.py` — imports each low-layer entry point in a subprocess and asserts zero interpreter modules **and** no `pipelex.interpreter_hub` in `sys.modules`. Parametrized over two entry points: the inference layer and `runtime_hub` itself.
-
-**CHECKPOINT H-2** — boundary declared, enforced, and regression-tested.
-
-### Checkpoint H-2 record
-
-Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,352 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite) · `make drift-check` ✅ (no contract opened — see below).
-
-#### The guard enforces two rules, not one
-
-The plan specified one rule (no `interpreter_hub` in the low layer). The guard ships with a second: **no module anywhere in `pipelex/` or `tests/` may reference `pipelex.hub`.** That is the H-1 note about `mocker.patch` targets, generalized — and generalizing it is what makes it work. The plan framed the string check as an `importlib.import_module` special case; scanning *every* string constant for an exact-or-boundary match on the module path catches `importlib`, `mocker.patch`, `pkgutil.resolve_name`, and any config-driven dotted path in one mechanism, with no call-site special-casing.
-
-Scope follows from the two rules being different: `tests/` is scanned for the dead-module rule **only**. `tests.*` is in no declared layer, so a test may still freely patch `pipelex.interpreter_hub` — while a stale `pipelex.hub` patch target, the thing that actually broke 36 tests, now fails the check.
-
-Matching is exact-or-boundary (`==`, or a `.`/`:` suffix), which is why `pipelex.runtime_hub` does not match `pipelex.hub` and why a docstring that merely *mentions* a module is not a reference. Two in-tree docstrings do exactly that and are correctly ignored. A path assembled at runtime from f-strings is beyond any AST scan; nothing does that today, and it is noted in the module docstring rather than defended against.
-
-#### Two carve-outs, both deliberate
-
-- **`if TYPE_CHECKING:` is exempt from the layer rule, not from the dead-module rule.** The rule is about what *loads*; a type-only import loads nothing, and H-1's own out-of-plan fix used exactly this deferral. Its `else` branch, `if not TYPE_CHECKING:`, and any `pipelex.hub` import inside a `TYPE_CHECKING` block all stay violations — each is pinned by a test.
-- **`# hub-layering: ignore`** mirrors `# kw-only: ignore`. There is exactly one in `pipelex/` and one in the test suite, both on lines that *declare* the forbidden path as data. The guard flagged its own configuration on first run, which is a good sign about the matcher and the reason the hatch exists.
-
-#### Verified by breaking it, not only by unit tests
-
-Both forms were injected into a real low-layer module (`cogt/content_generation/content_generator.py`) and the CLI was confirmed to report them at the right lines with the right kinds, then the file was restored byte-identically. Snippet-level unit tests would not have caught a filesystem-walk or layer-membership mistake.
-
-#### Two wiring traps worth knowing
-
-- **The CI aggregator gates on an explicit bash result check, not on `needs`.** Adding `lint-hub-layering` to `lint-all`'s `needs` list is *not* enough — `if: always()` means the aggregator runs regardless, and the `[ "${{ needs.<job>.result }}" != "success" ]` chain is what actually fails the build. Both were updated. A new lint job added without touching that chain would be silently advisory.
-- **A new job, not a step on `lint-keyword-only`.** Folding both AST guards into one job would have meant renaming it, and that job name may be a required status check — a rename silently un-requires it. The repo already runs one job per guard; this follows that.
-
-#### Proposed, reverted, then landed
-
-A `hub-layering-convention` drift contract (triggers: the guard + both hub modules; review: `docs/contribute/hub-layering.md`) is the exact analogue of the existing `keyword-only-convention` contract, and it mechanizes the doc obligation Phase 4 and the rename both carried. It was added at H-2, confirmed to open correctly, then **reverted**: `.claude/skills/drift-review` states that during the pilot the manifest must not grow without the user's explicit say-so, because ack friction is the thing being measured. Left as a decision for Louis rather than a silent addition. Note that `cli-docs` legitimately did not fire on this work — it excludes `pipelex/cli/dev_cli/**`.
-
-**Louis approved it after the rename landed, and it is now in `drift.toml`, reviewed and acked.** It carries no verify command, matching `keyword-only-convention`: `check-hub-layering` already gates `make check` and CI, so re-running it before an ack would add the unstaged-file hard error without adding a guarantee. The initial review is mechanical and worth repeating rather than re-reading — extract every public module-level symbol from both hubs and confirm each appears in the doc's partition tables, then import `RUNTIME_LAYER_PACKAGES` from the guard and confirm every declared package is named under Enforcement. The closure test was deliberately left out of the triggers; it is the obvious first addition if the contract ever proves under-triggered.
-
-#### Docs updated
-
-- `docs/contribute/hub-layering.md` — the "Enforcement" section was rewritten from "a guard is the next step" to the shipped two-rule specification: what each rule checks, why the string half is the load-bearing one, both carve-outs, the `tests/` scoping, and the rule-vs-property split.
-- `docs/under-the-hood/architecture-overview.md` — one sentence stating the boundary is mechanically enforced rather than held up by review.
-
-### Phase 3 — the placement residue ✅
-
-Neither item was coupling; both were types living in the wrong package, and each was independently correct. Both are **resolved by moving the type**, not by adding indirection — no resolver slot, no protocol, no `TYPE_CHECKING` deferral was needed for either.
-
-- [x] 3.1 **`JobMetadata`** → `pipelex/system/job_metadata.py` (with `JobCategory`, `UnitJobId`); `JobMetadataError` → `pipelex/system/exceptions.py`. `TraceContext` moved with it → `pipelex/system/trace_context.py`, and `DataInclusionConfig` moved down to `pipelex/system/data_inclusion_config.py` so `trace_context` no longer imports `graph_config`. **`cogt → pipeline` is now 0 statements.**
-- [x] 3.2 **`cogt.templating.*`** → moved down to `tools`. `TextFormat` / `TemplatingStyle` / `TagStyle` → `pipelex/tools/templating/`; `TemplateCategory` → `pipelex/tools/jinja2/`. **`tools → cogt` drops from 15 statements to 3** (the `tools/pdf` renderer only).
-
-**CHECKPOINT H-3** — placement residue resolved.
-
-### Checkpoint H-3 record
-
-Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,354 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite) · `make drift-check` ✅ (no contract opened).
-
-#### Measured after
-
-| | baseline | H-1 | **after H-3** |
-| --- | --- | --- | --- |
-| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | 0 | **0** ✅ |
-| pipelex modules loaded | 357 | 275 | **268** † |
-| SLOC loaded | 29,193 | 21,186 | **20,304** † |
-
-† Recorded from a stale run, caught by the PR #1062 review and re-verified at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups): the tree measures **269 / 20,305**, not 268 / 20,304. The baseline and H-1 rows reproduce to the digit, so the method is sound and only the recording was off. The 0-interpreter-modules row — the one that matters — is exact.
-
-Cross-package import statements, the number Phase 3 was actually aimed at:
-
-| edge | before | after |
-| --- | --- | --- |
-| `cogt → pipeline` | 18 | **0** |
-| `tools → cogt` | 15 | **3** |
-| `graph → cogt` | 2 | **0** |
-| `reporting → graph` | 1 | **0** |
-| `system → graph` | 1 | 1 (by design — see below) |
-
-The module/SLOC rows moved only a little because the fat edge was never `cogt → pipeline` alone. Two edges still pull `graph` and `pipeline` modules into the inference closure, and **both are out of Phase 3's scope by construction**:
-
-- `system.configuration.configs → graph.graph_config` (→ `mermaid_config`, `reactflow_config`): the main config model must name every subconfig, and the repo's convention is that submodels live in their own sub-packages. This is inherent to the one-big-config design, not a layering defect. It is the surviving `system → graph` edge.
-- `core.pipes.pipe_output → pipeline.pipeline_models`: a `core → pipeline` edge, which is **Phase 4 territory**.
-
-Together they account for the 7 `graph.*` and 2 `pipeline.*` modules still in the closure. Do not chase them here.
-
-#### 3.1 — where things landed, and why
-
-`JobMetadata` had to go somewhere `cogt` may import, which means a declared low-layer package. `pipelex/system/` is that package and it already houses `telemetry/otel_context.py` — the sibling transport `JobMetadata` carries alongside `TraceContext`.
-
-`TraceContext` moved **with** it rather than staying in `graph/`. Leaving it would only have renamed the inversion: `system/job_metadata.py → pipelex.graph.trace_context` is a `system → graph` edge, exactly the direction being removed. Its one graph dependency was `DataInclusionConfig`, so that class moved down to `pipelex/system/data_inclusion_config.py` and `graph_config.py` now imports it from there. **The TOML shape is unchanged** — the key is still `[pipelex.pipeline_execution_config.graph_config.data_inclusion]`; only the Python class's home moved. `pipelex.system.trace_context` now has a leaf closure: no `graph`, no `pipeline`.
-
-Two homes were considered and rejected for `TraceContext`: `pipelex/tracing/` (would have created a `system ⇄ tracing` package cycle, since `tracing → system` already exists) and `pipelex/system/telemetry/` (that package is OTel + PostHog; `TraceContext` is the pipelex-native node-tree transport, and conflating them would mislead).
-
-#### 3.2 — why the templating primitives split across two packages
-
-None of the three moved modules named anything from `cogt`, so this was pure misfiling. But they could not all land in one new package:
-
-- `TextFormat`, `TemplatingStyle`, `TagStyle` → `pipelex/tools/templating/`. That package imports nothing from `pipelex` beyond its own sibling — a genuine leaf.
-- `TemplateCategory` → `pipelex/tools/jinja2/`, because its entire payload is a map of jinja2 filters (`jinja2_filters`, `jinja2_models`, `jinja2_with_images_filter`). Filing it in `tools/templating/` would have made that package import `tools/jinja2` while `tools/jinja2` imports it back — a cycle inside one layer. As placed, the edges run one way: `tools/mermaid → tools/jinja2 → tools/templating`.
-
-What stays in `cogt/templating/` — `TemplateBlueprint`, the sigil preprocessor, `template_rendering` — belongs there: a blueprint is language-layer, and the rest imports `tools/jinja2` downward.
-
-#### Housekeeping done at H-3
-
-- **Subject grant migrated**: `pipelex/graph/trace_context.py::TraceContext.copy_for_child` → `pipelex/system/trace_context.py::…`. Recorded **before** running any check, per the `fko`-silently-rewrites warning in `CLAUDE.md`. No grants existed for the moved templating modules (the two that do, on `template_preprocessor` / `template_rendering`, did not move).
-- **Tests**: `tests/unit/pipelex/pipeline/test_job_metadata_request_id.py` → `tests/unit/pipelex/system/` (self-contained, so the move is free). The two `TraceContext` test modules **stayed** in `tests/unit/pipelex/graph/` — they consume `make_trace_context` and the `data_inclusion_config` / `graph_config` fixtures from that directory's `conftest.py`, which the graph tests use heavily. Splitting the fixture module to mirror the source move would cost more than the tidiness is worth.
-- **Docs**: `docs/contribute/hub-layering.md` gained a "Placement, not coupling" section recording both moves and the generalizable lesson, and its "Known inversions" bullet was corrected (`tools → cogt` is now the pdf renderer only). `docs/under-the-hood/execution-graph-tracing.md`'s file-reference table was updated for the two moved modules.
-- **`make cleanderived` deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`**, and pyright then fails on 12 unresolved-import errors that have nothing to do with your change. `make regenerate-test-models-quiet` restores it. Worth knowing before debugging a phantom failure.
-
-#### Cross-repo impact added by Phase 3
-
-These are **new** breakages on top of the `pipelex.hub` split, and they land in the same release-gated sweep:
-
-| repo | files touched by the Phase 3 moves |
-| --- | --- |
-| `pipelex-temporal/` (private) | 22 |
-| `pipelex-mistralai-workflows/` | 6 |
-| `pipelex-api/` | 1 |
-
-The import lines to rewrite, in full:
-
-| old | new |
-| --- | --- |
-| `pipelex.pipeline.job_metadata` | `pipelex.system.job_metadata` |
-| `pipelex.graph.trace_context` | `pipelex.system.trace_context` |
-| `pipelex.graph.graph_config import DataInclusionConfig` | `pipelex.system.data_inclusion_config import DataInclusionConfig` |
-| `pipelex.pipeline.exceptions import JobMetadataError` | `pipelex.system.exceptions import JobMetadataError` |
-| `pipelex.cogt.templating.text_format` | `pipelex.tools.templating.text_format` |
-| `pipelex.cogt.templating.templating_style` | `pipelex.tools.templating.templating_style` |
-| `pipelex.cogt.templating.template_category` | `pipelex.tools.jinja2.template_category` |
-
-Clean (no action): `pipelex-cookbook/`, `cocode/`, `pipelex-worker/`, `pipelex-starter-python/`, `pipelex-relay/`, `sandbox/`.
-
-### Phase 4 — core's data model joins the low layer ✅
-
-- [x] 4.1 Converted the `core/` straddlers to injected providers. **The plan's premise was wrong** — `core/` is two layers, not one, and only its *data model* can be low. See the H-4 record.
-- [x] 4.2 Widened the guard's low layer with core's six data-model packages, and added six `pipelex.core.*` entry points to `RUNTIME_LAYER_ENTRY_POINTS`.
-
-**CHECKPOINT H-4** — the boundary is complete, enforced, and measured.
-
-### Checkpoint H-4 record
-
-Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,356 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite, no test edits beyond the mechanical ones recorded below) · `make drift-check` ✅ (both contracts reviewed and acked — see below).
-
-## ▶ Resume here — the rename is landed
-
-All four phases **and** the runtime/interpreter rename are landed, with all three gates green. The rename's own record is [below](#the-runtimeinterpreter-rename-record); the rest of this section is the H-4 close-out it followed.
-
-The two contracts that were left open on purpose at the H-4 pause were reviewed and acked:
-
-- **`config-docs` — clean-pass.** The only trigger change was one import line in `configs.py` (`TemplatingStyle` moving `cogt.templating` → `tools.templating`, the Phase 3 placement fix); every other trigger file was byte-identical. No config field, default, validator, or TOML key moved. `docs/configuration/` documents no import path, and every Python path the docs *do* cite still resolves.
-- **`cli-docs` — clean-pass.** All 10 triggers changed by exactly one import line each (the Phase 4 renderer regroup). Verified against the **live CLI** rather than by reading alone — `pipelex build inputs pipe`, `pipelex build output pipe`, `pipelex-agent inputs pipe` — arguments, flags, format values and defaults all match `docs/tools/cli/`. The behavior-adjacent half of Phase 4 was checked too: no CLI doc cites a Python import path or calls a factory that gained a required `concept_provider`, and the runner codegen emits none. `agent_cli/CLAUDE.md`'s layout map lists only `agent_cli`'s own modules, none of which moved.
-
-Also swept `docs/` and `wip/` for stale references to the H-4 moves (`core.pipes.output.*`, `codegen.resolved_fields`, `core.pipes.inputs.input_renderer`): every remaining hit is intentional historical prose in `hub-layering.md` or this tracker.
-
-**One observation is worth carrying forward, because it is now a pattern rather than an anecdote.** This refactor opened **four contracts across three different ids**, and every one of them was import-path churn. The narrowing proposed in the earlier `config-docs` dogfood entry (scope the trigger to files that define settings) would **not** have prevented today's opening — `configs.py` is squarely inside that narrowed set. The mechanism that would prevent all four is a content-aware digest that ignores changes confined to import statements (and, for `keyword-only-convention`, to comments/docstrings): one manifest-wide change instead of three separate glob surgeries. Recorded in `wip/drift-contracts/dogfood-log.md` as the thing to weigh before any per-contract narrowing — it is evidence for the pilot's keep/narrow/mechanize verdict, not a change to make now.
-
-**Next: [PR #1062](https://github.com/Pipelex/pipelex/pull/1062) is open against `dev`** (base was still exactly `f23fda7a0` at open time, so no merge was needed). The only thing outstanding after it lands is the release-gated cross-repo sweep, already retargeted to the final names. Louis' drift-contract decision is resolved — `hub-layering-convention` is in the manifest, reviewed and acked.
-
-The PR body carries a **reviewer map**, which this diff needs: 528 files, of which ~490 are mechanical import churn. It names the dozen files where the judgment actually lives, and pre-empts the two things that look wrong at a glance — `subject_grants.toml`'s 221/221 re-sort (the registry is machine-written sorted, and was not in sort order before; the parsed mapping is identical modulo renames) and the deliberately un-swept old names in D1, the checkpoint records, and `.drift/acks/`.
-
-### The runtime/interpreter rename — record
-
-Landed as its own commit after H-4, per [`wip/hub/layer-and-hub-renaming.md`](layer-and-hub-renaming.md). Gates: `make agent-check` ✅ · full `make agent-test` ✅ · `make drift-check` ✅.
-
-**Pre-flight was clean.** Grepping the whole workspace — including the private `pipelex-temporal`, the heaviest consumer — turned up **zero** collisions on `runtime_hub` / `RuntimeHub` / `interpreter_hub` / `InterpreterHub`. The only hits were the plan documents themselves.
-
-**A token substitution was the right tool here, and the plan's AST warning did not apply.** Phase 1 needed an `ast` rewrite because it was *splitting* one module into two: each import line had to be classified symbol by symbol, and 29 parenthesized multi-line blocks were the hazard. This rename is 1:1 — no import splits, no classification — so the question is only whether the four tokens ever appear where they must not. They do not: enumerating every whole word in `pipelex/` and `tests/` containing any of them returned exactly the identifiers that should change (`get_method_hub`, `set_service_hub`, the hub-named test functions, and the bare class names). Substring replacement across 332 files, then a re-parse of every file in both trees, was safer than a formatting-preserving AST rewrite and left zero residuals.
-
-**The string-literal landmine was real again, and pre-enumerated.** The H-1 lesson (a missed `mocker.patch` target is invisible to every import-graph tool) held: `tests/helpers/init_cmd_helpers.py` carried `mocker.patch("pipelex.service_hub.get_console", ...)` — the same file, the same shape that broke 36 tests at H-1. Because the sweep was token-based over the whole file rather than import-based, it was caught for free. The other string references were the guard's own configuration, the closure test's entry-point list, and the guard test's patch-target fixtures.
-
-**What the plan under-specified: the enum members in the *test* file.** Step 4 lists the guard's `HubLayeringViolationKind` renames but step 5 lists only the test's constants and patch targets, so a first pass renamed the members in the source and left `HubLayeringViolationKind.METHOD_HUB_IMPORT` in the test — 7 failures. Mechanical to fix, but worth recording: when an enum member is renamed, its *references* live wherever the enum is asserted on, and the plan's per-file checklists split that pair across two steps.
-
-**Vocabulary, not just identifiers.** `LOW_LAYER_PACKAGES` → `RUNTIME_LAYER_PACKAGES` and `is_low_layer` → `is_runtime_layer` were in the plan; the prose was not, and it was the larger edit. "Low layer" / "high layer" was swept out of the guard, both hub docstrings, `class_registry_access.py`, the guard's success panel (it printed `Low layer: …` to the user), `hub-layering.md`, `architecture-overview.md` and the CHANGELOG. The historical checkpoint records in *this* file deliberately keep the old vocabulary, with a reading key in the header note — rewriting them would falsify what was decided when.
-
-**Judgment calls made while sweeping the docs**, none of them mechanical:
-
-- `hub-layering.md` gained an opening section naming the two layers as the language-implementation split, so a reader meets the vocabulary before the rule. The headline property was restated from "importing the inference layer must not load the interpreter" to **"importing the Pipelex runtime loads zero interpreter modules"** — the same measurement, phrased as the outward-facing claim.
-- The `runtime_bridge` clarifier the plan asked for landed in two places, not one: `hub-layering.md`'s intro and the guard's module docstring, since `plugins → runtime_bridge` appears in that file's Known-inversions list.
-- **D1 was preserved verbatim rather than swept.** Mechanically renaming it would have produced a decision record whose rejected alternatives argued about names that were no longer the subject. It is now marked SUPERSEDED, quotes the original in full, and notes that its own "conscious call against the brand-boundary rule" caveat is precisely what Louis acted on.
-- `.drift/acks/keyword-only-convention.toml` was **left alone** — an ack is an on-the-record review decision, and rewriting the rationale of a past review to mention a module that did not exist at review time would be falsifying the record.
-
-**One trigger file changed, so `keyword-only-convention` re-opened** — `keyword_only_guard.py`'s docstring names the hub. Reviewed and acked as import-path/prose-only; no guard behavior, registry schema, or carve-out changed.
-
-**Cross-repo is retargeted, not extended.** The sweep tables in this file now name `pipelex.runtime_hub` / `pipelex.interpreter_hub` directly. External repos still import `pipelex.hub`, so they are rewritten exactly once — the intermediate names never reach them, and never shipped.
-
-#### The plan's premise was wrong: `core/` is two layers
-
-Phase 4 assumed all of `pipelex/core/` could join the low layer once five straddlers were converted. Measurement said otherwise, and the correction is the main finding of this checkpoint.
-
-Beyond the five hub straddlers, **seven `core/` modules import the interpreter *directly*** — no hub involved, so no amount of dependency injection touches them:
-
-| module | pulls | why it is irreducible |
-| --- | --- | --- |
-| `core/registry_models.py` | every pipe + factory | it *is* the registry of pipe kinds |
-| `core/bundles/pipelex_bundle_blueprint.py` | 12 pipe blueprints | a discriminated union over every pipe kind |
-| `core/interpreter/bundle_elaborator.py` | 4 pipe blueprints | it is the interpreter |
-| `core/pipes/pipe_abstract.py` | `libraries.library_crate`, `pipe_signature.exceptions` | the base class every pipe extends |
-
-Measured: `pipelex.core.pipes.pipe_abstract` alone loads **30** interpreter modules while importing no hub at all. So the honest boundary is not `pipelex.core` — it is **"if it names a `Pipe`, it is high."**
-
-Louis' call (option A of three): declare core's data-model packages low, leave the Pipe-touching remainder high. Rejected: threading a provider through `PipeFactory.make_from_blueprint` too — that is **337 call sites (332 in tests, ~85 files)** and buys *no* additional closure property, since `pipe_factory` stays interpreter-bound either way.
-
-#### What landed
-
-**Two read-side contracts, new in `core/`:**
-
-- `ConceptProviderAbstract` (`core/concepts/concept_provider_abstract.py`) — `get_required_concept`, `get_native_concept`, `get_required_concept_from_concept_ref_or_code`, `is_compatible`.
-- ~~`PipeProviderAbstract` (`core/pipes/pipe_provider_abstract.py`) — `get_required_pipe`.~~ **Deleted at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups) (A5)**: it had zero consumers and its docstring described the opposite of what the code does. `get_required_pipe` is back on `PipeLibraryAbstract`.
-
-`ConceptLibraryAbstract` now **extends** the provider abstract, keeping add/remove/list/setup/teardown high. The split is the point: core depends on resolution, never on a library lifecycle. Both abstracts already named only `core` types, so this was an inverted dependency waiting to be undone.
-
-**Injected, not looked up.** `StuffFactory.{make_stuff_from_stuff_content_or_data, make_from_blueprint, make_from_concept_ref}`, `InputShaper.{shape, resolve_input_kind}`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `InputStuffSpecsFactory.{make_from_blueprint, make_from_string}`, `StuffSpecFactory.make_from_blueprint` all take a required `concept_provider`. Injection happens in the high half: `pipe_factory`, `input_renderer`, `output_renderer` call the hub themselves and hand the result down, as does `pipeline/execution_seams.py`.
-
-**One import was simply wrong**: `stuff_factory.py` imported `ConceptLibraryConceptNotFoundError` from `libraries.concept.concept_library` — a re-export path. The class already lived in `core/concepts/exceptions.py`. A one-line fix deleted a whole interpreter edge.
-
-**Two placement fixes** (the H-3 pattern again):
-
-- `codegen/resolved_fields.py` → `core/concepts/resolved_fields.py`. It names nothing outside `pipelex.core`, yet put `pipelex.codegen` into the closure of every core module reaching structure generation.
-- `core/pipes/inputs/input_renderer.py` + `core/pipes/output/output_renderer.py` → **`core/pipes/rendering/`**. Both render a `PipeAbstract`, so both are high; leaving `input_renderer` beside the low input-spec modules would have forced the low-layer declaration to enumerate *modules* instead of packages. `core/pipes/output/` is gone. Tests mirrored to `tests/unit/pipelex/core/pipes/rendering/`.
-
-#### Measured after
-
-| | baseline | H-1 | H-3 | H-4 | **Checkpoint A** |
-| --- | --- | --- | --- | --- | --- |
-| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | 0 | 0 | 0 | **0** ✅ |
-| pipelex modules loaded | 357 | 275 | 268 † | 268 † | **269** |
-| SLOC loaded | 29,193 | 21,186 | 20,304 † | 20,304 † | **20,299** |
-
-† The H-3 / H-4 module and SLOC cells were recorded from a stale run — the same tree measures **269 / 20,305**, confirmed by re-reading every closure module at both revisions. The Checkpoint A column is a fresh measurement after the [Phase A follow-ups](#checkpoint-a-record--pr-1062-review-follow-ups); the 6-SLOC drop is those edits (chiefly A3's deletion in `runtime_hub.py`, which is itself in the closure), not a module leaving it. Baseline and H-1 reproduce to the digit.
-
-The inference-layer numbers are unchanged by design — Phase 4 widened *which* modules are guaranteed clean, it did not touch `cogt`'s own weight. The new numbers are the six core entry points, each measured at **0 interpreter modules and no `pipelex.interpreter_hub`**, up from 50 each before this phase:
-
-| entry point | interpreter modules before → after |
-| --- | --- |
-| `core.stuffs.stuff_factory` | 50 → **0** |
-| `core.memory.input_shaper` | 50 → **0** |
-| `core.memory.working_memory_factory` | 50 → **0** |
-| `core.pipes.stuff_spec.stuff_spec_factory` | 50 → **0** |
-| `core.pipes.inputs.input_stuff_specs_factory` | 50 → **0** |
-| `core.concepts.structure_generation.generator` | 2 → **0** |
-
-#### Housekeeping done at H-4
-
-- **Grants**: 4 new (the provider-abstract getters), recorded **before** any check ran; 6 migrated with `resolved_fields`; 15 migrated with the two renderers; **4 deleted as dead** (`ConceptLibraryAbstract.get_{native_concept,required_concept,required_concept_from_concept_ref_or_code}`, `PipeLibraryAbstract.get_required_pipe`) — those defs moved to the provider abstracts, and staleness is symmetric so `make cko` hard-failed until the registry was cleaned.
-- **Test call sites**: 74 across 12 files gained `concept_provider=get_concept_library()`, applied by an AST-driven fixer keyed off pyright's own `Argument missing` report so no unrelated `make_from_blueprint` was touched. ⚠ The first pass mangled 3 files: for a multi-line call the closing-paren line is whitespace-only, so a "does the preceding text end in a comma?" check must look back **across newlines**, not within the line. Reverted and redone.
-- **Docs**: `docs/contribute/hub-layering.md` gained a "Where core splits" section (the two halves, the `if it names a Pipe, it is high` rule, and the injected-provider pattern), two new "Placement, not coupling" entries, a corrected low-layer list under Enforcement, and a rewritten `core/` bullet under Known inversions. `docs/under-the-hood/architecture-overview.md` gained a paragraph on core straddling the line. `docs/under-the-hood/codegen-projections.md` updated for the `resolved_fields` move.
-- **CHANGELOG**: the breaking-change note that had been deferred since H-1 is now written under `[Unreleased]`, covering all four phases — the `pipelex.hub` split, the moved types, and the injected providers.
-
-#### Still open
-
-- **The cross-repo sweep is still untouched and release-gated.** It now has a **third** wave on top of the `pipelex.hub` split and the Phase 3 type moves — see [Cross-repo impact added by Phase 4](#cross-repo-impact-added-by-phase-4).
-- ~~**The `hub-layering-convention` drift contract decision is still Louis'**~~ — **resolved: approved and landed** after the rename. See [Proposed, reverted, then landed](#proposed-reverted-then-landed).
-- A plausible sequel, now much cheaper to argue for than at H-2: a general layering ratchet. The remaining measured inversions are in [Known inversions](#known-inversions-not-fixed-here).
-
-#### Cross-repo impact added by Phase 4
-
-| old | new |
-| --- | --- |
-| `pipelex.codegen.resolved_fields` | `pipelex.core.concepts.resolved_fields` |
-| `pipelex.core.pipes.inputs.input_renderer` | `pipelex.core.pipes.rendering.input_renderer` |
-| `pipelex.core.pipes.output.output_renderer` | `pipelex.core.pipes.rendering.output_renderer` |
-
-Plus the signature changes: any external caller of `StuffFactory.make_stuff_from_stuff_content_or_data`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `InputShaper.shape`, `InputStuffSpecsFactory.make_from_*` or `StuffSpecFactory.make_from_blueprint` must now pass `concept_provider=get_concept_library()`. Do all four waves in one pass per repo.
-
-#### Cross-repo impact added by the F1 remedy
-
-| old | new |
-| --- | --- |
-| `pipelex.plugins.direct.direct_plugin` | `pipelex.interpreter_plugins.direct.direct_plugin` |
-| `pipelex.plugins.pipe_func.pipe_func_plugin` | `pipelex.interpreter_plugins.pipe_func.pipe_func_plugin` |
-| `pipelex.plugins.builtins` → `BUILTIN_PLUGINS` / `CORE_UNCONDITIONAL_PLUGIN_NAMES` | `pipelex.interpreter_plugins.builtins` → same names (composed); the runtime half stays in `pipelex.plugins.builtins` as `RUNTIME_BUILTIN_PLUGINS` / `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES` |
-
-Plus one signature change with a **real production call site outside this repo**: `build_registrar` now requires `builtin_plugins=` and `core_unconditional_plugin_names=`.
-
-| repo | site | fix |
-| --- | --- | --- |
-| `pipelex-api` | `api/main.py:110`, `_resolve_http_error_mappers` — `build_registrar(config=config).get_http_error_mappers()` at module import | import the composed lists from `pipelex.interpreter_plugins.builtins` and pass both. Its docstring's "the same standalone pattern `pipelex plugins list` uses" stays true — that command passes the same two lists |
-
-Verified by grep across the workspace: no other repo calls `build_registrar` or imports either relocated module (`pipelex-mistralai-workflows`'s two hits are prose in docstrings). External plugins are unaffected — they arrive through the `pipelex.plugins` entry point and sit in no declared layer.
-
-### Checkpoint A record — PR #1062 review follow-ups
-
-Phase A of [`wip/hub/pr-1062-review-followups.md`](pr-1062-review-followups.md) is applied: A1's doc-honesty fix plus A2–A8. Per **D-R4** the [F1](pr-1062-review-followups.md#f1--the-layer-rule-is-only-enforced-one-hop-deep) *remedy* is deliberately **not** here — it is its own PR after #1062 merges — so this checkpoint makes the shipped documentation true about a defect that still exists, rather than fixing the defect.
-
-#### What landed
-
-- **A1 — the scope claim is corrected.** `docs/contribute/hub-layering.md`'s "Every declared package is compliant" now says what it means: the declaration is compliant *with the direct-import rule*, which the guard does not follow transitively. Known inversions carries the measurement (the four `pipelex.plugins` modules, their interpreter-module counts, and which two are leaves versus aggregators), states plainly that the headline property is unaffected, and describes the decided fix. Re-measured on the working tree before publishing: 57 / 67 / 67 / 58, reproducing the review exactly.
-- **A2 — `pipelex.runtime_hub` joined `RUNTIME_LAYER_PACKAGES`.** The module at the centre of the rule was exempt from it, since no tuple entry was a prefix of it. Verified zero-risk both ways: still 0 violations tree-wide, and an `interpreter_hub` import injected into `runtime_hub.py` in memory is caught at the injected line. `is_runtime_layer`'s docstring now records that matching is exact-or-dotted-prefix, so a bare module is a legal entry beside the packages.
-- **A3 — write-only `RuntimeHub._class_registry` deleted**, with `set_class_registry`, `get_required_class_registry`, the `pipelex.py` call site and the subject grant. Zero callers here or in any sibling repo. It was the twin of the `_observer` state H-1 deleted for exactly this reason, and a live trap besides: it returned the boot-time global while the module-level `get_class_registry()` returns the library-scoped one, so the two diverged under `scoped_current_library(...)`.
-- **A4 — the loop-invariant `get_concept_library()` in `_delighten_template` is hoisted** above the loop.
-- **A5 — `PipeProviderAbstract` deleted; `get_required_pipe` is back on `PipeLibraryAbstract`.** The follow-up plan left this a two-way choice (delete, or keep for symmetry and rewrite the docstring). Deleted, because the abstract had zero consumers, bought no closure property (`core.pipes` is not runtime-layer), and its docstring asserted the opposite of the code — it claimed core takes pipe resolution as a parameter, while the only two sites that follow a pipe reference (`core/pipes/rendering/output_renderer.py:51` and `:84`) call `interpreter_hub.get_required_pipe` directly. Symmetry with `ConceptProviderAbstract` is not a reason to ship an unused abstraction. The absence is now documented where it will be questioned — on `PipeLibraryAbstract` and in `hub-layering.md` — so the next reader does not "restore" it.
-- **A6 — five accuracy fixes.** `runtime_hub.py`'s docstring stopped forbidding `core.concepts` / `core.pipes` wholesale (`core.concepts` is a *declared runtime-layer package* and sits in `runtime_hub`'s own closure); `pipelex.py`'s boot comment stopped claiming the InterpreterHub install "needs a RuntimeHub already in place" (it stores a lazily-resolved callable and needs nothing); the CHANGELOG names the exact templating modules, since `pipelex.tools.templating.__init__` is 0 bytes and the path it printed raised `ImportError` for the external consumers who read that file; and the low/high vocabulary survivors are swept — **four**, not the two the review found (`concept_library_abstract.py` and `pipe_library_abstract.py` carried "stays here, high" too).
-- **A7 — `make generate-error-pages` re-run.** `job-metadata-error.md` had followed neither of Phase 3's moves; it now reports `pipelex.system.exceptions`, and the generator also re-filed its index entry from "execution and runtime" to "platform and tooling", which is the subsystem grouping following the class.
-- **A8 — the class-registry leaf-import rule is restated.** It said "import the leaf only from inside `runtime_hub`'s import closure", which is false for two of the three in-tree importers (verified: `concept.py` is inside, `concept_factory.py` and `structure_generation/generator.py` are not). The real criterion is a module that must stay import-light *with respect to* `runtime_hub`. As written, the rule invited someone to "fix" `concept_factory.py` into re-coupling `core.concepts` to the whole cogt/plugin stack — and neither gate would have noticed, because the closure test measures interpreter modules, not weight.
-- **Batched in:** the published doc's pointer to `wip/pr-1062-review-notes.md` is folded into an in-place sentence. `wip/` is outside `docs_dir`, so it was unreachable for a reader on docs.pipelex.com and would dangle once the file is archived.
-
-#### The measurement
-
-Re-taken here rather than copied — see the [H-4 table](#measured-after-1) for the full row and the stale-recording footnote. The closure is **269 modules / 20,299 SLOC / 0 interpreter modules**. The 6-SLOC drop against the pre-Phase-A tree is A3's deletion in `runtime_hub.py` (itself in the closure), confirmed by re-reading every closure module at both revisions; no module left the closure.
-
-#### Not in this checkpoint
-
-- **The F1 remedy** — (d) split the built-ins by layer + (c) teach the guard the transitive check. Its own PR after #1062 merges, per D-R4. Until it lands, Known inversions is the record that keeps the breach visible.
-- **[Phase C](pr-1062-review-followups.md#phase-c--release-wave-additions)** — folded into the release-gated cross-repo sweep per D-R1. It adds a governed `docs/specs/` + `conformance/` surface and five consumer repos the [sweep tables](#cross-repo-sweep) below are missing, including `pipelex-transport`, whose `bridge.py` calls a changed signature in production code.
-
-[Phase B](#checkpoint-b-record--test-hardening) followed immediately and is now applied too.
-
-### Checkpoint B record — test hardening
-
-Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,358 files, keyword-only PASSED, hub-layering PASSED) · full `make agent-test` ✅ · `make drift-check` ✅ (one contract re-opened, reviewed and acked — see below).
-
-Phase B of [`wip/hub/pr-1062-review-followups.md`](pr-1062-review-followups.md) is applied in full: B1–B7. Three new test modules, three hardened ones, one guard fix.
-
-**Every item was verified by mutation.** Watching a new test go green proves nothing about what it pins, and two of these items exist precisely because an existing test *appeared* to pin something it did not. So for each one the pinned behavior was removed, the new test confirmed to fail, and the mutation reverted. What that turned up is worth keeping:
-
-- **B1's mutation is the finding, restated as a fact.** Deleting `class_registry_scoping.reset()` from `Pipelex.teardown` fails the new test and *only* it — the three other tests in the module, including the pre-existing one that calls `reset()` directly under a `# what Pipelex.teardown does` comment, stay green. That comment was the whole safety net. The simulation test is kept, because it does pin `reset()`'s own semantics; its comment now says so instead of overclaiming.
-- **B2 needed a stronger assertion than the plan specified.** The plan said to assert `returncode == 1` on a known-dirty entry point. That would **not** have worked: the closure script's *second* check (`pipelex.interpreter_hub in sys.modules`) exits 1 for `pipelex.interpreter_hub` whatever the offender predicate does, so the control would have passed over a completely broken detector. The test asserts the offender *message* too. Confirmed by mutation: typo-ing `INTERPRETER_PACKAGES` and emptying `INTERPRETER_CORE` fails the control while all eight real entry points pass vacuously — the exact failure mode the item was written against.
-- **B5's mutation reproduces the regression the finding describes.** Making `resolve_input_kind` accept `concept_provider` and then call `get_concept_library()` anyway fails the new test alone, with the other 69 `input_shaper` tests green. Before it, that regression failed nothing anywhere.
-- **B3 and B4** fail 4-of-6 and 2-of-5 respectively when their gates are removed (`sys.exit(1)` deleted from both command paths; the `__pycache__` skip dropped from `iter_source_files`).
-- **B6 is a fix, not just a test.** `_is_type_checking_test` matched `ast.Attribute(attr=...)` with an unconstrained receiver, so `settings.TYPE_CHECKING:` — an ordinary runtime condition — claimed the layer-rule exemption. Tightened to require the receiver to be `typing`. Verified safe before tightening: nothing in `pipelex/` or `tests/` uses the attributed form at all, so there was no alias (`import typing as t`) to break.
-
-**B6 re-opened the `hub-layering-convention` drift contract**, which the plan had said Phase B would not do — `hub_layering_guard.py` is one of its triggers. Reviewed and acked. Both prescribed mechanical checks were re-run (33 + 32 public module-level hub symbols all present in the partition tables; all 12 declared runtime-layer entries named under Enforcement), and `docs/contribute/hub-layering.md` gained the receiver constraint on its `TYPE_CHECKING` bullet.
-
-**One observation from that ack is worth carrying forward.** The read-through caught staleness the contract's triggers structurally cannot see: B1/B2/B7 changed the two test modules the doc has sections on, and neither test file is a trigger — deliberately, per the contract's initial scoping. So the contract fired on the guard, and the review found the spillover. That is not an argument for widening the triggers (the scoping was Louis' call, and the spillover was caught anyway); it is evidence that a review target's value is bounded by what the reviewer reads, not by what opened the contract. Recorded in `wip/drift-contracts/dogfood-log.md` as this contract's second consecutive `real-catch`.
-
-**Two things caught in passing, both fixed here:**
-
-- **The plan's B2 instruction would not have worked as written** — see the bullet above. Recorded because it generalizes: a negative control that asserts only an exit code is only as strong as the *first* thing that can produce it.
-- **Two dead anchor links in `hub-layering.md`**, pre-existing since the page was written and invisible to every gate the branch runs — `make docs-check` reports them as `INFO`, not a failure. The heading is `### The rule — \`make check-hub-layering\``, and Python-Markdown strips the em dash rather than turning it into a second hyphen, so `#the-rule--make-check-hub-layering` never resolved. Confirmed against the built site's real `id`, and confirmed pre-existing by re-running the check with Phase B stashed.
-
-**No CHANGELOG entry.** Phase B adds tests and tightens a `pipelex-dev` guard, and `pipelex/cli/dev_cli` is excluded from both wheel and sdist — nothing here reaches a release consumer.
-
-The measurement is untouched by Phase B — no production module changed except the guard, which is dev-CLI-only and outside every closure. The [Checkpoint A column](#measured-after-1) stands.
-
-### Checkpoint A1 record — the F1 remedy
-
-Applied on `refactor/Hub-2`, after #1062 merged. **The full record lives with the plan**, at [`wip/hub/pr-1062-review-followups.md` → Checkpoint A1](pr-1062-review-followups.md#checkpoint-a1-record--the-f1-remedy): what landed against what D-R4 planned, the measurements, how the new rule was verified by reproducing the defect on the pre-remedy tree, which existing tests it touched and why, and what it deliberately does not do. Summarized here only so this tracker is not misleading on its own:
-
-- `pipelex/interpreter_plugins/` is the interpreter-side home for `direct/` and `pipe_func/`; `plugins/builtins.py` keeps the runtime half; the interpreter half composes both.
-- `build_registrar` takes `builtin_plugins` and `core_unconditional_plugin_names` as required parameters — see the [sweep row](#cross-repo-impact-added-by-the-f1-remedy) for the one external call site this breaks.
-- The guard gained a **transitive rule** over the module-level import graph; `pipelex.plugins.builtins` gained a closure-test entry point.
-- **0 of 473** declared runtime-layer modules reach `interpreter_hub`, down from 4 of 477. Gates all green, and the headline measurement below is unchanged (nothing that loads at runtime moved — only where the built-ins are filed).
-
-## Exit criteria — measured, not asserted
-
-The headline property is that the inference layer must stop importing the interpreter. Measure it directly, from the repo root on a synced venv:
-
-```bash
-.venv/bin/python - <<'PY'
-import sys
-from pathlib import Path
-
-import pipelex.cogt.content_generation.content_generator # noqa: F401
-
-INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
-loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
-interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
-sloc = 0
-for mod in loaded.values():
- file = getattr(mod, "__file__", None)
- if file:
- sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
-print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
-print("offenders:", interpreter)
-PY
-```
-
-If Phase 1 lands and `interpreter modules` is not 0, the snippet prints the offenders: something imports the interpreter outside the hub, and the shortest import path to it is what to fix. Swap the imported module to measure any other entry point (`pipelex.pipelex`, `pipelex.runtime_hub`, …).
-
-The module/SLOC targets come from importing exactly the types a low-only hub would annotate — 236 modules / 17,683 SLOC with the interpreter subpackages at zero — plus headroom for cogt's own modules.
-
-## Findings in passing
-
-> **Both are resolved as of H-1** — see [Findings in passing — both resolved, one bigger than recorded](#findings-in-passing--both-resolved-one-bigger-than-recorded). The `_observer` one turned out to be more than dead code: a public doc page documented the inert setter as the supported API.
-
-Both surfaced while inventorying the boot sequence. Neither is caused by this refactor; both are in its blast radius, and the repo's flag-and-fix rule applies.
-
-- **Duplicate `set_library_manager` in `Pipelex.setup`.** Lines 364–365 and 474–475 are the identical pair `self.library_manager = library_manager or LibraryManager()` + `self.pipelex_hub.set_library_manager(...)`. Nothing between them touches `library_manager` (verified), so when the caller passes no manager the first `LibraryManager()` is constructed, registered, and then silently discarded and replaced by a second instance. Delete the earlier pair — it is dead, and removing it is what makes the low/high boot split clean with no reordering (step 1.5).
-- **`_observer` is write-only state.** `PipelexHub.set_observer` is called at `pipelex.py:503`, but there is no `get_observer` on the container and no module-level accessor — the live observer reaches its consumer directly via `PipeRouter(observer=multi_observer)` at line 531. The design doc lists "observer" among the `interpreter_hub` contents; it should be **deleted rather than moved**. Confirm no external consumer sets it before removing (see [Cross-repo sweep](#cross-repo-sweep)).
-
-## Risks and containment
-
-- **Big mechanical diff.** Contained by: the rewrite is scriptable from the partition table; `pipelex.hub` ceasing to exist means a missed site is an import error, not a silent wrong-layer resolution; and full `make agent-test` is the zero-behavior-change bar. The 29 multi-line import blocks are the one place a careless script does real damage — rewrite via `ast`, not regex.
-- **Two singletons, two lifecycles, two teardowns.** Contained by the tiny construction surface. Watch `Pipelex.teardown` / `teardown_if_needed` and the fixtures that reset hub state — a half-reset hub between tests is the realistic failure mode, and it surfaces as cross-test pollution rather than a clean failure. Step 1.7 exists for this; make the "both hubs reset" assertion explicit rather than implied.
-- **D5's resolver slot is installed at boot, not imported.** If a consumer builds a `RuntimeHub` without ever populating a `InterpreterHub` (the doctor path, some tests), `get_class_registry` must degrade to the unscoped `KajsonManager` registry rather than raise. Default the slot to a function returning `None`, never to an unset attribute.
-
-## Cross-repo sweep
-
-Release-gated follow-up — `pipelex.hub` is imported outside this repo and every one of these breaks the moment the module disappears.
-
-| repo | files importing `pipelex.hub` |
-| --- | --- |
-| `pipelex-temporal/` (private) | 35 |
-| `pipelex-mistralai-workflows/` | 11 |
-| `pipelex-api/` | 9 |
-| `pipelex-cookbook/` | 2 |
-| `cocode/` | 2 |
-
-Clean (no action): `pipelex-worker/`, `pipelex-starter-python/`, `pipelex-relay/`, `n8n-nodes-pipelex/`, `sandbox/`.
-
-Symbols crossing the repo boundary today, which is the surface whose new home is a published contract change:
-
-`clear_current_library`, `get_bundle_validator_registry`, `get_class_registry`, `get_console`, `get_content_generator`, `get_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_model_deck`, `get_orchestrator_registry`, `get_pipe_func_executor_registry`, `get_pipe_library`, `get_pipe_router`, `get_pipelex_hub`, `get_report_delegate`, `get_required_concept`, `get_required_pipe`, `get_secret`, `get_storage_provider`, `get_storage_provider_registry`, `is_dry_run_forced`, `scoped_current_library`, `set_current_library`
-
-Two notes on that list: `get_pipelex_hub` splits into two accessors, so every external site must pick a half; and `set_pipe_router` / `teardown_current_pipe_router` / `scoped_pipe_router` are documented as depended upon by our Mistral Workflows plugin, so their move is a contract change to announce, not just to make.
-
-**Rewrite straight to the final names — there is no intermediate step.** `service_hub` / `method_hub` never shipped, so external repos go directly from `pipelex.hub` to:
-
-| old | new |
-| --- | --- |
-| `from pipelex.hub import <runtime symbol>` | `from pipelex.runtime_hub import …` — everything in the [`runtime_hub` partition table](#-pipelexruntime_hubpy-runtime-layer) |
-| `from pipelex.hub import <interpreter symbol>` | `from pipelex.interpreter_hub import …` — everything in the [`interpreter_hub` partition table](#-pipelexinterpreter_hubpy-interpreter-layer) |
-| `get_pipelex_hub` | `get_runtime_hub` **or** `get_interpreter_hub` — pick the container the call site actually meant |
-| `PipelexHub` | `RuntimeHub` **or** `InterpreterHub` |
-
-**Phase 3 added a second wave of breakage to the same sweep** — the moved types, not the hub accessors. The per-repo counts and the complete old→new import table are in [Cross-repo impact added by Phase 3](#cross-repo-impact-added-by-phase-3). Do both waves in one pass per repo.
-
-### Third wave — the layer-placement track (`refactor/Layer-boundary`)
-
-Folded in here deliberately rather than opened as a second sweep: it is the same shape, the same repos, and it must go out on the same release. Plan and rationale: [`../layer-placement-completion.md`](../layer-placement-completion.md).
-
-| old | new |
-| --- | --- |
-| `from pipelex.pipe_run.pipe_run_mode import PipeRunMode` | `from pipelex.system.pipe_run_mode import PipeRunMode` |
-| `from pipelex.pipeline.pipeline_models import SpecialPipelineId` | `from pipelex.system.job_metadata import SpecialPipelineId` |
-| `from pipelex.pipe_run.pipe_run_params import PipeRunParamKey` | `from pipelex.system.pipe_run_param_key import PipeRunParamKey` |
-| `from pipelex.pipe_run.exceptions import PipeRunError` | `from pipelex.core.pipes.exceptions import PipeRunError` |
-| `from pipelex.graph.graph_rendering import generate_graph_for_bundle, generate_view_for_bundle` | `from pipelex.pipeline.bundle_graph_rendering import …` |
-
-`pipelex.pipeline.pipeline_models` is **deleted**, not aliased. `GraphFormat` and `render_graph_from_spec` stay in `pipelex.graph.graph_rendering` — only the two bundle-driven helpers moved.
-
-Measured 2026-07-29 (re-run at sweep time — `grep -rn --include='*.py' -E 'pipe_run\.pipe_run_mode|pipeline\.pipeline_models|PipeRunParamKey|pipe_run\.exceptions import.*PipeRunError|graph\.graph_rendering' <repo>`):
-
-| repo | sites | what |
-| --- | --- | --- |
-| `pipelex-temporal/` (private) | 37 | `PipeRunMode` throughout tests + `test_extras`; one `SpecialPipelineId` in `tests/integration/fixtures/pipe_job_helpers.py`. Also two copies of the same `.claude` / `.agents` skill script. |
-| `cocode/` | 6 | `PipeRunMode` in five CLI modules + one test |
-| `pipelex-cookbook/` | 2 | `PipeRunMode` in two tests |
-| `pipelex-mistralai-workflows/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `test-bed/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `pipelex-workshop/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `pipelex-demos/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `pipelex-demo-frostbeam/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `pipelex-demo-mistral/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-| `pipelex-demo-vibe/` | 1 | `PipeRunMode` in `tests/e2e/conftest.py` |
-
-Clean for this wave: `pipelex-api/`, `pipelex-transport/`, `pipelex-daytona-sandbox/`, `pipelex-worker/`, `pipelex-starter-python/`, `pipelex-relay/`, `n8n-nodes-pipelex/`, `sandbox/`.
-
-> **Enumerate the workspace, do not hand-list it.** The first pass at this table iterated a *hardcoded* repo list and silently missed the last six rows — every one of them a real breaking site, and every one invisible because a repo absent from both columns reads exactly like a repo that was checked and cleared. Re-measure with `for repo in $(ls -d */ | tr -d '/')`, and note that the `_*` directories are worktrees of `pipelex/` itself, not consumers.
-
-**`conformance/` and `docs/specs/pipelex-transport-boundary.md` need no edit for *this* wave** — none of the four moved leaves is on `ALLOWED_SURFACE`. They are stale for the **hub track's** wave and were already so before this one: both still pin `pipelex.pipeline.job_metadata` and `pipelex.graph.trace_context`, which moved to `pipelex/system/` when the hub split landed. That is the standing evidence this sweep is still open.
-
-**All of it is `pipe_run` / `pipeline` → runtime-layer homes, none of it is a behavior change.** Every site is a one-line import swap and a missed one is an `ImportError`, never a silent wrong resolution.
-
-## Known inversions — not fixed here
-
-Named so the docs stay honest, not scheduled.
-
-- `plugins/pipe_func_executor_registry.py` imports from `pipe_operators/` — under `TYPE_CHECKING`, so it loads nothing and breaches no rule, but the *placement* is still inverted: a runtime-layer module typed by an interpreter-layer protocol. This is D3's underlying inversion, and it is what is left of it. The two plugins that used to sit beside it — `pipe_func_plugin.py` and `direct_plugin.py`, which imported `pipe_operators/` and `pipeline/` for real — are no longer in `plugins/`: the F1 remedy moved them to `pipelex/interpreter_plugins/`, and the guard's transitive rule would now flag them if they came back.
-- A general layering ratchet ("no low module may import any high module", with an allowlist) is out of scope. The measured inversion set is real but larger than this change should carry. **Re-measured at H-3**, after Phase 3 removed the two biggest clusters: `cogt → core` (21), `system → cogt` (7), `plugins → runtime_bridge` (6), `tools → cogt` (3 — the pdf renderer reaching for `cogt.extract` / `cogt.image` types, the same misfiling pattern Phase 3 fixed elsewhere), and one genuine wart — `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. `cogt → pipeline` (18) is gone. The general rule is now a more plausible sequel than it was at H-2.
-- Eager optional-SDK imports: `pipelex/tracing/event_log_factory.py` imports `dynamodb_event_log` at module level, which runs a module-level `try: import boto3`, so `boto3`/`botocore`/`jmespath`/`dateutil`/`six` load in every process that touches the tracing factory. A three-line fix (import `DynamoDBEventLog` inside the factory branch, the pattern already used for `pypdfium2` in `cogt/content_generation/render_generate.py`), entirely independent of this plan. Most other heavy roots (`posthog`, `pypdfium2`, `pillow`, `polyfactory`, `datamodel-code-generator`) are **base** dependencies, not extras — not the same kind of finding.
diff --git a/wip/hub/layer-and-hub-renaming.md b/wip/hub/layer-and-hub-renaming.md
deleted file mode 100644
index 191c4eef0..000000000
--- a/wip/hub/layer-and-hub-renaming.md
+++ /dev/null
@@ -1,214 +0,0 @@
-# Renaming the layers and the hubs — `runtime` / `interpreter`
-
-**Status: EXECUTED.** Landed as its own commit after H-4, with all three gates green. The outcome record — what the plan got right, the two places it under-specified, and the judgment calls made while sweeping the docs — is in [`TODOS.md` → The runtime/interpreter rename, record](hub-split-tracker.md#the-runtimeinterpreter-rename--record). This document stays as the decision record: it is the *why*, and its old→new tables are deliberately not swept.
-
-Two corrections to the mechanical plan below, for anyone reading it as a template:
-
-- **§2's "rewrite via `ast`, not regex" did not apply.** That warning was inherited from Phase 1, which *split* a module and so had to classify each imported symbol. A 1:1 rename has no classification step, so the safe method is a whole-word audit (enumerate every word in `pipelex/` and `tests/` containing each token, confirm every hit should change) followed by substring replacement and a re-parse of every file. Token-based sweeping also catches the string literals for free, rather than needing §2's separate grep.
-- **§4 and §5 split a pair that must move together.** §4 renames `HubLayeringViolationKind`'s members; §5 lists the test's constants and patch targets but not those members' *references* in `test_hub_layering_guard.py`. Renaming one without the other left 7 failing tests.
-
-Decided by Louis on 2026-07-26, at the close of the hub-split refactor, after challenging the naming that Phases 0–4 shipped. This document is the record of *what* was decided and *why*, plus the mechanical plan. Read [Why](#why-the-current-names-are-wrong) before executing — the rationale is what stops a future session relitigating this or half-applying it.
-
-## The decision
-
-| | was | becomes |
-| --- | --- | --- |
-| the low layer | "low layer" | **the runtime layer** |
-| the high layer | "high layer" (mostly unnamed) | **the interpreter layer** |
-| the low hub | `pipelex/service_hub.py` · `ServiceHub` | `pipelex/runtime_hub.py` · **`RuntimeHub`** |
-| the high hub | `pipelex/method_hub.py` · `MethodHub` | `pipelex/interpreter_hub.py` · **`InterpreterHub`** |
-
-The one rule, restated — and note it now needs no gloss:
-
-> **The interpreter hub may import the runtime hub. The runtime hub must never import the interpreter hub.**
-
-The headline property, restated in the same vocabulary:
-
-> **Importing the Pipelex runtime loads zero interpreter modules.**
-
-That second sentence is both the measurement the closure test pins and the outward-facing claim: *the inference engine does not know the MTHDS language exists — you can embed it without loading a line of the interpreter.*
-
-## Why the current names are wrong
-
-### "Low" / "high" — the tell is that only one side got a name
-
-Low/high is fine for a *lint* (the guard checks arrow direction, and direction is relational). It is wrong as the *conceptual* vocabulary, for three reasons:
-
-1. **Only one side was ever enumerated**, so the other side has no handle. Across the Phase 3 and Phase 4 docs the same concept got coined fresh every time it was needed: "the Pipe-touching remainder", "the high half", "the interpreter". When every author invents a term, the term is missing.
-2. **"Low-level" connotes primitive / plumbing / the boring part.** That is exactly backwards: the low half is the inference engine, arguably the most valuable code in the repo.
-3. **It is contentless.** "Our low layer does not import our high layer" describes our dependency graph. It tells a reader nothing about what either layer *is*, and it sells nothing.
-
-**The codebase had already converged on the right word for one side and nobody noticed.** The measurement snippet, the closure test and the guard docstrings all say *interpreter* (`INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}`), and `pipelex/core/interpreter/` exists. Only the guard identifiers and the doc headings still said "high".
-
-### Rejected alternatives for the low layer, with reasons
-
-Recording these so they are not re-proposed:
-
-- **`inference`** — a subset masquerading as the whole. `tools`, `system`, `reporting` and the entire value data model are not inference. It also collides with live usage: the docs and closure test already say "the inference layer" to mean `cogt` specifically ("importing the inference layer must not load the interpreter"). Widening the term makes that sentence ambiguous.
-- **`INTERPRETER_FREE_*`** — defined by exclusion. Louis' objection, and correct: a layer should be named for what it is.
-- **`foundation`** — genuinely viable, and the fallback if the nesting cost below ever bites. Positive, no collision, sells fine. Passed over only because it is less informative than `runtime` and does not share a word with the hub.
-- **`engine`** — same defect as `inference`: console, secrets, storage and the value data model are not engine.
-- **`platform`** — collides with `pipelex-platform`, our hosted CRUD API.
-- **`core`** — catastrophic: `pipelex/core/` exists and *straddles both layers*.
-- **`kernel`** / **`base`** / **`substrate`** — respectively OS-loaded (and `pipelex/kit/` exists), flat (and `base_exceptions.py` exists), and cold jargon.
-
-### Why `runtime` / `interpreter` won
-
-It is the textbook language-implementation split, so it explains itself to any developer who has implemented a language: the **runtime** is the machinery present at execution time (allocator, stdlib, FFI — here: models, workers, config, values); the **interpreter** reads the program and executes it (here: reads `.mthds`, builds pipes, routes them).
-
-It also gives **one word across layer and hub** rather than two vocabularies: `runtime_hub` lives in the runtime layer, `interpreter_hub` in the interpreter layer.
-
-**Known cost, accepted:** the workspace `CLAUDE.md` calls all of `pipelex/` "the Python runtime", so "the runtime layer" nests inside "the runtime". Mild, and identical to the tension in `runtime_hub`, which Louis accepted explicitly.
-
-### `service_hub` → `runtime_hub`
-
-Two reasons.
-
-1. **Commercial collision.** Once "the Pipelex service" means the hosted product, `from pipelex.service_hub import get_secret` is ambiguous — and after the cross-repo sweep that exact line lands in `pipelex-platform`, `pipelex-api` and `pipelex-api-hosted`, repos that *are* the service. The word means two different things one line apart.
-2. **"Runtime" names the role, "service" named the mechanism.** The container holds config, console, secrets, storage, telemetry, the model deck, the inference workers, the content generator, reporting, run mode, tracing and the plugin registries — ambient machinery that lives for the process and is needed to execute anything, whatever is loaded. That is a runtime. "Service" only described how it is injected.
-
-Louis waved off the proximity to the existing `runtime_bridge` package. Worth one clarifying sentence in `hub-layering.md` anyway, because `plugins → runtime_bridge` appears in the Known-inversions list, so the two names will sit near each other and a reader may infer a relationship.
-
-### `method_hub` → `interpreter_hub`
-
-`method_hub` was **already flagged as a knowing concession** at D1 of the original plan: *"`method_hub` borrows the MTHDS noun for a runtime container — acceptable because the object genuinely holds the loaded method's libraries, but it is a conscious call against the brand-boundary rule."* Three defects:
-
-1. **"Method" is an MTHDS/product noun, not a Pipelex runtime noun.** Inside `pipelex/` the vocabulary is bundle / library / pipe / domain / concept; "method" lives at the language and hosted-product level (`method_id`, `mt_…`, `mthds_run`). The brand rule in the workspace `CLAUDE.md` says MTHDS owns the language nouns and Pipelex owns the runtime ones — this borrows in the forbidden direction.
-2. **It misdescribes the contents** — the container holds a `LibraryManager`, the concept/domain/pipe libraries, a current-library binding, the router, the pipeline manager, the PipeFunc executor.
-3. **The singular is misleading.** Multiple libraries can be open, bound per async context; "method hub" implies one method.
-
-Two alternatives were considered and rejected **in this order**, so do not circle back to either:
-
-- **`library_hub`** — rejected by Louis: a library is *inert*, while the container is active machinery (router, pipeline manager). Naming it for the passive artifact undersells it.
-- **`pipe_hub`** — proposed by Louis, rejected on evidence: it is **narrower than its contents**. A meaningful share of the hub is concepts and domains, not pipes (`get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`), plus the library binding and dirs. `get_native_concept()` on a `pipe_hub` reads wrong, and those concept accessors are load-bearing — they are exactly what the runtime layer consumes through `ConceptProviderAbstract` after Phase 4. `pipe_hub` makes the same class of error as `library_hub`, in the opposite direction: one too passive, the other too narrow.
-
-`interpreter_hub` covers pipes, concepts, domains and the execution machinery under one true idea: *everything bound to the method you loaded, and the thing that runs it.*
-
-**On the `pipelex/core/interpreter/` collision** — this was raised as an objection and then withdrawn, deliberately. It only holds if the layers keep the low/high names. Once the layer is *called* the interpreter layer, `core/interpreter/` sitting inside it is a part-of relationship, exactly as consistent as `runtime_hub` living inside "the runtime". Not a collision.
-
-## Sequencing — why this window matters
-
-**Land H-4 green first** (`make agent-test` + both drift contracts), so there is a known-good commit, then do the rename as its own commit *before* the release and *before* the cross-repo sweep.
-
-The load-bearing fact: **the cross-repo sweep has not happened yet.** External repos still import `pipelex.hub` — they are broken either way and get rewritten exactly once. Renaming now costs **zero** extra cross-repo churn. Renaming after the sweep means doing it twice, and the second time is a published-contract break with no cover story. The CHANGELOG entry is written but unreleased, so the announcement absorbs it for free.
-
-Doing it as a separate commit (not amended into H-4) keeps a clean bisect point, since it touches ~300 files mechanically.
-
-## Before you start — verify no collisions
-
-Not checked exhaustively when the decision was taken. Do this first:
-
-```bash
-# in the workspace root, not just _hub
-grep -rn "runtime_hub\|RuntimeHub\|interpreter_hub\|InterpreterHub" --include="*.py" --include="*.md" .
-```
-
-`pipelex-temporal/` is private — check it out and grep it too; it is the heaviest consumer (35 files import `pipelex.hub` today).
-
-## The mechanical plan
-
-Counts below are files, measured at commit `46e76c953`.
-
-### 1. The two modules
-
-- `git mv pipelex/service_hub.py pipelex/runtime_hub.py`
-- `git mv pipelex/method_hub.py pipelex/interpreter_hub.py`
-- Class renames: `ServiceHub` → `RuntimeHub`, `MethodHub` → `InterpreterHub`.
-- Accessor renames: `get_service_hub` / `set_service_hub` → `get_runtime_hub` / `set_runtime_hub`; `get_method_hub` / `set_method_hub` → `get_interpreter_hub` / `set_interpreter_hub`.
-- Update both module docstrings — they open with the layering rationale.
-
-### 2. Call sites
-
-| import | files in `pipelex/` | files in `tests/` |
-| --- | --- | --- |
-| `pipelex.service_hub` | 113 | 66 |
-| `pipelex.method_hub` | 55 | 135 |
-
-Rewrite via an `ast` pass over whole import statements, **not regex** — the same hazard as Phase 1: parenthesized multi-line import blocks. Phase 1's rewriter is the model.
-
-⚠ **String literals are the landmine, again.** This is the lesson that cost 36 broken tests at H-1: an import rewrite is blind to `mocker.patch("pipelex.service_hub.get_console", ...)`, `importlib.import_module(...)`, and any config-driven dotted path. Sweep for the string forms separately:
-
-```bash
-grep -rn '"pipelex\.service_hub\|"pipelex\.method_hub\|'"'"'pipelex\.service_hub\|'"'"'pipelex\.method_hub' pipelex tests
-```
-
-### 3. Also rename these attributes / locals
-
-- `pipelex/pipelex.py:125-128` — `self.service_hub` / `self.method_hub` instance attributes (and every reader of them).
-- `pipelex/system/registries/class_registry_access.py` — the `class_registry_scoping` slot is installed by `set_method_hub`; its docstring names the hub.
-- `pipelex/plugins/registrar.py` — `HubSlot` is *not* affected (its members are capability names: `CONTENT_GENERATOR`, `PIPE_ROUTER`, …). Leave it. `HubSlotAlreadyClaimedError` likewise.
-
-### 4. The guard — `pipelex/cli/dev_cli/commands/hub_layering_guard.py`
-
-| identifier | becomes |
-| --- | --- |
-| `LOW_LAYER_PACKAGES` | `RUNTIME_LAYER_PACKAGES` |
-| `is_low_layer(...)` | `is_runtime_layer(...)` |
-| `METHOD_HUB_MODULE` | `INTERPRETER_HUB_MODULE` (value `"pipelex.interpreter_hub"`) |
-| `HubLayeringViolationKind.METHOD_HUB_IMPORT` | `INTERPRETER_HUB_IMPORT` (wire value `"interpreter-hub-import"`) |
-| `HubLayeringViolationKind.METHOD_HUB_REFERENCE` | `INTERPRETER_HUB_REFERENCE` (wire value `"interpreter-hub-reference"`) |
-
-`DELETED_HUB_MODULE = "pipelex.hub"` **stays exactly as is** — that rule is about the module that was deleted in Phase 1 and is unrelated to this rename. Keep its `# hub-layering: ignore` marker.
-
-Also update the module docstring (it states both rules and the carve-outs) and `HubLayeringViolationKind.remedy`, whose strings name the hubs.
-
-Leave the escape hatch spelling `# hub-layering: ignore` alone — "hub layering" is still accurate, and changing it would silently un-suppress the two lines that carry it.
-
-### 5. Tests
-
-Contents first — every one of these needs its import lines, constants and patch-target strings swept:
-
-- `tests/unit/pipelex/test_hub_import_closure.py` — `LOW_LAYER_ENTRY_POINTS` → `RUNTIME_LAYER_ENTRY_POINTS`; the module docstring states the property.
-- `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` — `test_low_layer_membership` → `test_runtime_layer_membership`; `test_core_is_split_between_the_layers` keeps its name but its assertions call the renamed predicate.
-- `tests/unit/pipelex/test_hub_lifecycle.py`, `tests/unit/pipelex/test_hub_class_registry.py` — import lines and any patch-target strings.
-
-**Module renames — Louis' call: rename them as part of this work.** Note first that `test_hub_*` is not *stale*: "hub" survives the rename (there are still two hubs, and `hub_layering_guard.py` / `check-hub-layering` / `hub-layering.md` are all unchanged). So apply the repo's actual convention — a test module mirrors its source module, or else names the property it pins — which moves two and leaves two:
-
-| module | action | why |
-| --- | --- | --- |
-| `test_hub_import_closure.py` | → **`test_runtime_layer_import_closure.py`** | It pins a property, not a module: *the runtime layer loads no interpreter*. Naming the layer makes the file findable from the vocabulary. |
-| `test_hub_class_registry.py` | → **`test_class_registry_scoping.py`** | It is the D5 regression guard for the `class_registry_scoping` slot, not a test of "the hub". The current name has always been imprecise. |
-| `test_hub_lifecycle.py` | **keep** | It pins that a boot installs *both* hub singletons and that teardown drops the scoping one installed. "Hub lifecycle" is exactly what that is, and both hubs still exist. |
-| `cli/dev/test_hub_layering_guard.py` | **keep** | Mirrors its source module `hub_layering_guard.py`, which is not renamed. Moving it would break the mirror. |
-
-⚠ **Renaming test modules needs a cache reset.** Per the repo `CLAUDE.md`, moving or deleting tests confuses pytest collection and the linters — run `make cleanderived` afterwards. That deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`, after which pyright fails with unresolved-import errors unrelated to your change; `make regenerate-test-models-quiet` restores it. Do this *before* concluding anything failed.
-
-### 6. `subject_grants.toml`
-
-29 entries under `pipelex/service_hub.py::`, 26 under `pipelex/method_hub.py::`.
-
-⚠ **Migrate the grants BEFORE running any check.** Two independent traps, both hit this session:
-- `make fko` runs early in `agent-check` and will silently make an ungranted subject keyword-only.
-- Staleness is symmetric: a grant whose def moved hard-fails `make cko` until the registry is fixed.
-
-The path prefix and the class name both change (`ServiceHub.` → `RuntimeHub.`, `MethodHub.` → `InterpreterHub.`).
-
-### 7. Build and CI
-
-- `Makefile` — the `check-hub-layering` target's `PRINT_TITLE` says "Enforcing the service_hub / method_hub layering boundary" (line ~362) and the help text at line ~159. The target name and the `chl` alias can stay: "hub layering" is still what it checks.
-- `.github/workflows/lint-check.yml` — job `lint-hub-layering` (line ~137). **Do not rename the job**: it may be a required status check, and a rename silently un-requires it. Nothing to change here unless the target name changes.
-- `.github/workflows/lint-fresh-check.yml` — runs `make check-hub-layering`; unaffected.
-
-### 8. Docs
-
-- `docs/contribute/hub-layering.md` — the largest edit. Retitle the layers throughout, rewrite "The two halves" headings, update the Enforcement rule list, and add the `runtime_bridge` clarifying sentence. Keep the "Where core splits" section's *content* — only its layer vocabulary changes.
-- `docs/under-the-hood/architecture-overview.md` — "What Keeps The Layers Apart: The Two Hubs" section and the paragraph on core straddling the line.
-- `CHANGELOG.md` — amend the `[Unreleased]` breaking-change entry rather than adding a second one. It currently announces `pipelex.hub → pipelex.service_hub / pipelex.method_hub`; it should announce the final names directly, since `service_hub` / `method_hub` will never have shipped.
-- Grep the rest: `docs/under-the-hood/{pipe-routing-and-execution,runtime-bridge-and-transport,execution-graph-tracing}.md`, `docs/advanced/`, `tests/CLAUDE.md` (its "root-level modules" trigger list names both hubs), and in-code docstrings.
-- `tests/CLAUDE.md` also lists `pipelex/service_hub.py` / `pipelex/method_hub.py` under "When to run full `make agent-test`".
-
-### 9. This branch's own tracker
-
-`TODOS.md` and `wip/hub/hub-split-refactor.md` are dense with `service_hub` / `method_hub`. They are historical records of the refactor, so a mechanical sweep is fine — but keep D1's rejected-alternatives reasoning intact and add a pointer to this document.
-
-## Gates
-
-`make agent-check` · full `make agent-test` (a rename of this size touches root modules, so per `tests/CLAUDE.md` the full suite is the correct gate) · `make drift-check`.
-
-Expect **`cli-docs` to fire** — the rename touches many CLI modules' import lines. `config-docs` will likely fire too. Both are import-path-only for this change, but review honestly against the targets before acking, per the `drift-review` skill.
-
-## Cross-repo
-
-This **replaces**, not adds to, the first wave of the [cross-repo sweep](hub-split-tracker.md#cross-repo-sweep): external repos go straight from `pipelex.hub` to `pipelex.runtime_hub` / `pipelex.interpreter_hub`, never touching the intermediate names. Update the sweep tables in `TODOS.md` to the final names as part of this work, so the sweep is done once with the right target.
-
-Affected: `pipelex-temporal` (35 files, private), `pipelex-mistralai-workflows` (11), `pipelex-api` (9), `pipelex-cookbook` (2), `cocode` (2). `get_pipelex_hub` splits into `get_runtime_hub` / `get_interpreter_hub`.
diff --git a/wip/hub/pr-1062-review-followups.md b/wip/hub/pr-1062-review-followups.md
deleted file mode 100644
index 56bd86f43..000000000
--- a/wip/hub/pr-1062-review-followups.md
+++ /dev/null
@@ -1,511 +0,0 @@
-# PR #1062 — `/review` follow-ups
-
-**Status: [Phase A](#phase-a--in-pr-fixes), [Phase B](#phase-b--test-hardening) and the [F1](#f1--the-layer-rule-is-only-enforced-one-hop-deep) remedy (the A1-PR) are APPLIED.** PR [#1062](https://github.com/Pipelex/pipelex/pull/1062) merged to `dev` on 2026-07-27 (squash `6fbdcb2fd`), carrying Phases A and B — recorded at [Checkpoint A](hub-split-tracker.md#checkpoint-a-record--pr-1062-review-follow-ups) and [Checkpoint B](hub-split-tracker.md#checkpoint-b-record--test-hardening). The A1-PR — remedy (d)+(c) per [D-R4](#decisions-taken) — is applied on branch `refactor/Hub-2` and recorded at [Checkpoint A1](#checkpoint-a1-record--the-f1-remedy). **[Phase C](#phase-c--release-wave-additions) is the only phase left**, and it is release-gated. This document is the executable follow-up plan from a full `/review` pass, written so it can be picked up cold in a new session.
-
-**Related:** [`../pr-1062-review-notes.md`](../pr-1062-review-notes.md) records the earlier Codex thread triage (the closure-predicate widening, the `pipe_output` reclassification, and one deliberately-deferred item). That file is about *one* review thread; this one is the whole review. They do not overlap except where noted.
-
-## Cold start — read in this order
-
-1. This section, then [Decisions taken](#decisions-taken) — what was chosen and what was declined. Every decision is taken, including [D-R4](#decisions-taken) (decided 2026-07-27, applied the same day).
-2. [Checkpoint A1](#checkpoint-a1-record--the-f1-remedy) — **start here for the current state**: what the remedy actually did, what it measured, and where it differed from the plan.
-3. [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) — the finding the remedy closed. Kept in full as the record: the measurement, the three routes, and why the headline property was never damaged. It is history now, not open work.
-4. [Phase A](#phase-a--in-pr-fixes) and [Phase B](#phase-b--test-hardening) — applied, every Phase B item mutation-verified. [Phase C](#phase-c--release-wave-additions) is the only phase left here, and it is release-gated.
-
-Every finding below was **verified by running it**, not by reading alone. The reproduction command is quoted with each one; re-run it first if you doubt a claim, because several of them contradict what the tracker and the shipped docs currently say.
-
-## What the review confirmed as sound
-
-Recorded so nobody re-audits it. Each of these was independently re-measured, not taken on trust:
-
-- `make check-hub-layering`, `make drift-check`, `make tb`, the new hub tests, and all PR CI checks pass.
-- **The headline property reproduces exactly**: importing `cogt.content_generation.content_generator` loads **0** interpreter modules, down from 50. All eight closure-test entry points measure 0.
-- **`subject_grants.toml`'s 221/221 churn is a faithful re-sort.** 1758 → 1759 grants; the six dropped and six added pair up exactly as the tracker documents (four library-abstract methods moving to the provider abstracts, `set_observer` deleted, `set_pipelex_hub` splitting in two). No grant lost, no rationale silently rewritten.
-- **The TOML config shape is unchanged** — `pipelex.toml` is byte-identical to base.
-- Enum completeness is clean: one new enum (`HubLayeringViolationKind`), exhaustive `match`, no unhandled consumer.
-- Of 498 changed `.py` files, 437 are pure import-line churn. The reviewer map in the PR body is accurate about where judgment lives.
-
-## Decisions taken
-
-- **D-R1 — the cross-repo/spec work is recorded, not done.** Louis' call: keep PR #1062 as-is and fold [Phase C](#phase-c--release-wave-additions) into the existing release-gated sweep rather than widening this PR. The sweep tables in `TODOS.md` stay as they are for now; this document is the delta.
-- **D-R2 — the in-PR fixes ([Phase A](#phase-a--in-pr-fixes)) and the full test hardening ([Phase B](#phase-b--test-hardening)) are approved to apply.** They were deferred out of this session only because they want a cold context, not because they were declined.
-- **D-R3 — `Pipelex.teardown`'s process-global scoping reset is accepted as designed.** See [Considered and not changed](#considered-and-not-changed).
-- **D-R4 — DECIDED 2026-07-27: the [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) remedy is [(d)](#remedy-d--split-the-built-ins-by-layer) paired with a minimal (c), in its own PR after #1062 merges.** Rationale: (d) is the only option that *removes* the defect — (a) re-describes it (enumerate ~24 subpackages and maintain the list forever), (b) hides it behind deferred imports with the false claim standing, (c) alone cannot land (red on today's tree). (d) deletes a weld rather than adding machinery, and moves the built-ins onto the seam external plugins (Temporal, Daytona) already use from outside the repo. (c) rides along because this exact failure mode — transitive breach with both gates green — already occurred invisibly in the PR that introduced the guard, so prevention is not speculative; at ~0.8 s it is cheaper than the guard's current run. The two formerly-blocking questions are settled: **the relocated plugins get one interpreter-side home** (e.g. `pipelex/interpreter_plugins/`, matching the `runtime_hub`/`interpreter_hub` vocabulary) — see [Resolutions](#remedy-d--resolutions-2026-07-27) under Remedy (d) for why "next to what they adapt" was never actually available and how the two-places-to-look smell dissolves; and **(d)+(c) is its own PR** — #1062 carries only [A1](#phase-a--in-pr-fixes)'s doc-honesty fix. A1.1's broad entry-point additions are **superseded by (c)** and consciously skipped; the (d) PR adds a single `pipelex.plugins` entry point as a runtime-truth check. All four candidates and their measurements remain under [Remedy options](#remedy-options-with-what-was-measured-about-each) for the record.
-
-## F1 — the layer rule is only enforced one hop deep
-
-> ✅ **RESOLVED 2026-07-27** by remedy (d)+(c) — see [Checkpoint A1](#checkpoint-a1-record--the-f1-remedy). Everything below is kept verbatim as the record of what was measured and why; the tree now reports **0 of 473** declared runtime-layer modules reaching `interpreter_hub`, and the guard follows the import graph so this class of breach cannot recur silently. Read it for the reasoning, not for open work.
-
-**This is the finding that matters most, and it is not what the earlier review thread was about.**
-
-The guard checks whether a runtime-layer module *directly* imports `pipelex.interpreter_hub`. It does not follow the import graph. `pipelex.plugins` is a declared runtime-layer package, and four of its modules reach `interpreter_hub` transitively. Both gates stay green.
-
-> **Re-verified 2026-07-26**, two independent ways — runtime import measurement, and a static module-level import graph over all of `pipelex/`. The defect is confirmed, but three specifics in the original write-up were wrong and are corrected below. Re-read this section rather than the first draft; the corrections change what the remedy has to cover.
-
-Measured on the branch tip:
-
-```
-pipelex.plugins.direct.direct_plugin interpreter_hub=True interp_modules= 57 total=462
-pipelex.plugins.discovery interpreter_hub=True interp_modules= 67 total=516
-pipelex.plugins.builtins interpreter_hub=True interp_modules= 67 total=515
-pipelex.plugins.pipe_func.pipe_func_plugin interpreter_hub=True interp_modules= 58 total=371
-
-$ .venv/bin/pipelex-dev check-hub-layering --quiet
-✓ Hub-layering check: PASSED
-```
-
-### F1.a — the blast radius is exactly `pipelex.plugins`
-
-A static sweep of **every** declared runtime-layer module (module-level imports only, `TYPE_CHECKING` and function-body imports excluded, matching what actually loads):
-
-```
-declared runtime-layer modules scanned: 476
-reaching pipelex.interpreter_hub transitively: 4
-
- pipelex.cogt 0 / 130 pipelex.core.concepts 0 / 18
- pipelex.plugins 4 / 131 ← pipelex.core.domains 0 / 6
- pipelex.reporting 0 / 6 pipelex.core.memory 0 / 7
- pipelex.system 0 / 46 pipelex.core.pipes.inputs 0 / 4
- pipelex.tools 0 / 96 pipelex.core.pipes.stuff_spec 0 / 4
- pipelex.core.stuffs 0 / 28
-```
-
-Ten of the eleven declared packages are clean across 345 modules; the uncovered ones were also spot-checked at runtime (`reporting.reporting_manager`, `system.configuration.configs`, `core.domains.domain_factory` — all `interp=0`). **The remedy decision is only ever about `plugins`.**
-
-### F1.b — there are three routes, not one
-
-The original write-up named `pipelex.runtime_bridge` as *the* intermediary. It is one of three, and **cutting it alone fixes nothing**:
-
-```
-plugins.direct.direct_plugin → runtime_bridge.direct_orchestrator → interpreter_hub
-plugins.direct.direct_plugin → pipeline.direct_bundle_validator → pipeline.validate_in_process → interpreter_hub
-plugins.pipe_func.pipe_func_plugin → pipe_operators.func.direct_pipe_func_executor → interpreter_hub
-plugins.builtins → both plugins above (builtins.py:6, builtins.py:16)
-plugins.discovery → builtins (discovery.py:5; on the boot path, pipelex.py:53)
-```
-
-`direct_plugin` has **two independent routes** (`direct_plugin.py:1` and `:4`), so severing the `runtime_bridge` one leaves it breaching through `pipeline`. And `pipe_func_plugin.py:1-2` imports `pipe_operators` **directly** — no hub, no `runtime_bridge`, never touched by that cut.
-
-The structure simplifies the remedy, though: **only two modules are leaves.** `builtins` and `discovery` breach purely as aggregators — `builtins.py` imports every built-in plugin, `discovery.py` imports `builtins` — so they carry no edge of their own. Fix `direct_plugin` and `pipe_func_plugin` and all four clear; leave either one and both aggregators stay breached.
-
-### F1.c — the headline property is *not* damaged
-
-The original write-up called this "a live breach of the property the guard exists to protect," which reads as if the shipped 0-interpreter-modules measurement is invalidated. It is not:
-
-```
-pipelex.config interp=0 plugins.builtins loaded=False
-pipelex.cogt.content_generation.content_generator interp=0 plugins.builtins loaded=False
-pipelex.runtime_hub interp=0 plugins.builtins loaded=False
-```
-
-Nothing on the inference-layer or `runtime_hub` path reaches the four modules; they are reachable only from full boot, where the interpreter loads anyway. What is actually wrong is narrower and still worth fixing:
-
-- **The scope claim is false.** `docs/contribute/hub-layering.md:184` — *"Every declared package is compliant"* — is true of the direct-import rule only, and reads as a claim about the property. The Known-inversions preamble at `:217` is honest that *"`plugins` is a runtime layer is not yet unconditionally true"*, but files it as placement; it does not say the inversion loads `interpreter_hub` and 67 interpreter modules today. It also understates both instances: `pipe_func_plugin` is described as *"typed by protocols from `pipe_operators/`"* when it imports the concrete `DirectPipeFuncExecutor` at module level, and `direct_plugin` is described as importing *"from `pipeline/`"* with no mention of the `runtime_bridge` route. `plugins/discovery.py` and `plugins/builtins.py` are not listed at all.
-- **The guard cannot see this class of breach at all.** Any future runtime-layer module can reach `interpreter_hub` through any undeclared intermediary (`runtime_bridge`, `pipeline`, `pipe_run`, `graph`, `observer`, `tracing`, `config`, `libraries`) with both gates green. This is the generalizable defect; the four modules are just today's instance.
-
-### F1.d — why it was invisible: the closure test covers 6 of 11 packages
-
-The closure test is the only thing that checks the property, and it does so at eight hand-picked entry points. Mapped against the declaration:
-
-```
-pipelex.cogt COVERED pipelex.core.concepts COVERED
-pipelex.plugins NO ENTRY POINT pipelex.core.domains NO ENTRY POINT
-pipelex.reporting NO ENTRY POINT pipelex.core.memory COVERED
-pipelex.system NO ENTRY POINT pipelex.core.pipes.inputs COVERED
-pipelex.tools NO ENTRY POINT pipelex.core.pipes.stuff_spec COVERED
- pipelex.core.stuffs COVERED
-```
-
-`pipelex.plugins` is the largest declared package (131 modules) and has no entry point. The four uncovered-but-clean packages are a latent gap, not a live one — but they are the reason nothing caught `plugins`.
-
-### The structural read that should inform the remedy
-
-The two leaf modules ([F1.b](#f1b--there-are-three-routes-not-one)) are precisely the ones whose job is to **construct interpreter-layer objects**: `direct_plugin` registers a `DirectOrchestrator` + `DirectBundleValidator`, `pipe_func_plugin` registers a `DirectPipeFuncExecutor`. The other ~127 modules in `plugins/` are inference backends (anthropic, openai, bedrock, gateway, …) and are genuinely runtime. That is not an arbitrary line — it is the same one as *"if it names a `Pipe`, it belongs to the interpreter layer."*
-
-The repo already sanctions the deferral pattern one level down: `pipe_func_executor_registry.py:7-14` defers its `pipe_operators` protocol under `TYPE_CHECKING`, with a comment stating exactly this reasoning. The *plugin* cannot use that trick — it needs the concrete class at runtime, because it constructs it.
-
-### Remedy options, with what was measured about each
-
-**Decided 2026-07-27 — (d) paired with a minimal (c); see [D-R4](#decisions-taken).** The four candidates and their measurements are kept for the record.
-
-- **(a) Declare `plugins` subpackage-by-subpackage**, the treatment `pipelex.core` already got for the same reason. Honest about what the package is, and the structural read above says the split falls on a real line. Wrinkle the original draft did not mention: `builtins.py` imports *every* plugin, so it cannot be runtime-layer while any built-in plugin is interpreter-touching, and `discovery.py` imports `builtins`. So (a) means enumerating `plugins`' ~14 backend subpackages + ~10 registry modules and excluding `direct/`, `pipe_func/`, `builtins.py`, `discovery.py` — noticeably more churn than `core`'s six lines.
-- **(b) Defer the imports in the four modules.** Largely **cosmetic**: the modules still load at boot, in the same process, one call later — `register()` runs on the boot path either way. Nothing that does not already import the interpreter would import less; the closure test would go green on an unchanged property. Also needs ~4 function-level imports with `# noqa`, against the house import rule, and must cover all three routes from F1.b.
-- **(c) Teach the guard the transitive check** — resolve each runtime-layer module's module-level `pipelex` import closure and flag any path reaching `interpreter_hub`. The only option that closes the generalizable hole. **Cheaper than "a real feature" suggests**: a prototype builds the whole graph and does reachability over all 476 modules in **0.83 s**, against the current guard's own 2.79 s run. It does not stand alone — it would fail on the four modules today, so it forces (a), (b) or (d) alongside it.
-- **(d) Split the built-ins by layer and move the weld to the composition root** — Louis' proposal, and a strictly better (a). See [Remedy (d) in full](#remedy-d--split-the-built-ins-by-layer) below; it is the leading candidate.
-
-Whichever is chosen, `docs/contribute/hub-layering.md:184` and the Known-inversions preamble at `:217` need correcting per F1.c.
-
-### Remedy (d) — split the built-ins by layer
-
-**The smell it names.** `builtins.py` is a *composition root smuggled into a leaf package*. Welding the two layers is legitimate work — something has to do it — but it belongs at the boot entrypoint, which sits in no declared layer and is free to weld. Instead it happens inside a module the declaration claims is runtime, which is exactly why both gates stay green while the claim is false.
-
-**The boundary already exists in the code; (d) only makes it visible.** The registrar's slots are *ports* — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live in runtime-layer modules under `plugins/*_registry.py` — and `pipelex.py:427-433` sets every derived registry, orchestrators and bundle validators included, on **`self.runtime_hub`**. So the runtime hub already holds slots whose *adapters* are interpreter-layer. That is ports-and-adapters, and it is what the guard's own remedy text already prescribes: *"have the interpreter layer install it downward at boot"* (`hub_layering_guard.py:130-132`).
-
-**The consistency argument that clinches it.** External plugins already use this seam: our Temporal plugin contributes an orchestrator and our Daytona plugin a PipeFunc executor — both interpreter-touching, both living entirely outside this repo, both arriving through the entry-point mechanism without welding anything. The in-tree built-ins are the *only* ones welding. (d) makes them use the seam externals already use.
-
-**Four moves.** Splitting `builtins.py` alone is *not* enough — `direct/` and `pipe_func/` still sit under `pipelex.plugins` and still breach on their own ([F1.b](#f1b--there-are-three-routes-not-one)):
-
-1. Split `builtins.py`; the runtime half keeps the seventeen backend / storage / secrets plugins.
-2. Relocate `plugins/direct/` and `plugins/pipe_func/` to the interpreter side (3 modules).
-3. Invert `discovery`'s dependency: `build_registrar` takes the plugin list as a **parameter** instead of importing `BUILTIN_PLUGINS` — the same injection pattern this refactor already applied to `concept_provider` in `core`.
-4. `pipelex.py` composes both halves. It is in no declared layer (verified) — the composition root, where welding belongs.
-
-**Simulated against the real import graph** (same graph builder as the [F1.a sweep](#reproduction-commands), with those edges rewritten):
-
-```
-AFTER the simulated split+relocation:
- pipelex.plugins modules in scope : 128 (relocated out: 3)
- still reaching interpreter_hub : 0
- interpreter-package leaks : 0
-```
-
-That is the payoff over (a): it converts *"drop `pipelex.plugins` and enumerate ~24 subpackages"* into **"keep the one declared line and make it true."** Three modules move instead of two dozen getting enumerated.
-
-**Honest counterarguments, so this is not adopted on enthusiasm:**
-
-- **The immediate payoff is honesty and enforceability, not a smaller closure.** `pipelex.py` is the only caller of `build_registrar` and needs everything, so nothing loads less on day one — the same criticism levelled at (b). The difference is real but should be stated precisely: (b) hides the weld behind a deferred import and leaves the false claim standing; (d) removes the weld and makes the claim true. Removing a false claim is not a speculative addition — but do not expect boot to get faster.
-- **Where the relocated plugins live was unresolved, and was the weakest part.** A `pipelex/interpreter_plugins/` sibling creates two places to look for a plugin, which is its own smell; housing them next to what they adapt scatters them. **Resolved — see [Resolutions](#remedy-d--resolutions-2026-07-27) below.**
-- **`CORE_UNCONDITIONAL_PLUGIN_NAMES` splits along the same line** — `{direct, pipe_func}` interpreter, `{storage, secrets, openai}` runtime — and is consumed by `discovery._skip_if_disabled`, so it must be injected or split alongside move 3. A second thing welded in the same file.
-- **It constrains the plugin contract.** (d) assumes no single plugin contributes both a runtime and an interpreter adapter. True today; one that wanted both would have to become two plugin classes. Probably healthy, but it is a real constraint and should be written into the contract rather than left implicit.
-- **It does not replace (c).** Nothing in (d) stops the *next* runtime-layer module from welding the same way. (d) fixes today's instance properly; (c) prevents recurrence. Pair them.
-- **Scope.** Relocating packages is a real refactor with import churn across the tree. #1062 is already 498 files and green, so (d) most likely wants its own PR rather than widening this one.
-
-### Remedy (d) — resolutions (2026-07-27)
-
-The decisions that unblocked D-R4, so the (d) PR starts from settled ground:
-
-- **Location: one interpreter-side home, not scattered next to the adapters.** The "house them next to what they adapt" option was never actually available — `DirectOrchestratorPlugin` spans two packages (its orchestrator lives in `runtime_bridge`, its bundle validator in `pipeline`), so it has no single adapter-adjacent home. A small dedicated package (e.g. `pipelex/interpreter_plugins/`, consistent with the `runtime_hub`/`interpreter_hub` vocabulary) is the right shape.
-- **The two-places-to-look smell dissolves.** The interpreter-side package is *allowed* to import downward, so its builtins module imports the runtime half and exports the single composed list. Exactly one place still answers "what are the built-in plugins" — it just lives in the layer permitted to do the welding. Both callers of `build_registrar` (boot in `pipelex.py`, and the `pipelex plugins list` diagnostic) consume that one list, so the composition is not duplicated.
-- **`CORE_UNCONDITIONAL_PLUGIN_NAMES` is passed as a parameter** alongside the plugin list — the same inversion as move 3, two lines more. No split constant left behind in a runtime module.
-- **The one-plugin-one-layer constraint is one sentence in `contract.py`'s docstring**, not machinery. If a plugin ever genuinely needs adapters in both layers, decide then.
-- **(c) stays minimal**: module-level imports only, with today's `TYPE_CHECKING` carve-outs — matching what actually loads, per the sweep script that found F1. No exclusion/allowlist machinery in the guard to keep `direct/`/`pipe_func/` under `pipelex.plugins`; relocation is the fix, not declaration surgery.
-- **Entry points: one, not five.** With (c) doing static transitive coverage of all declared runtime-layer modules, the broad A1.1 additions are redundant cost. The (d) PR adds a single `pipelex.plugins` closure-test entry point as a runtime-truth check (static analysis cannot see dynamic imports) for the package that bit us, and skips the other four uncovered packages.
-- **Own PR, after #1062 merges.** #1062 is 498 files, green, and reviewed; widening it re-opens the review for no benefit. #1062 carries only the A1.3 doc-honesty fix; the (d) PR rewrites that doc section again when the inversion actually disappears — a few sentences, acceptable churn.
-
-## F2 — the guard does not enforce its own rule on `runtime_hub.py`
-
-Narrower than F1 and independent of it. `RUNTIME_LAYER_PACKAGES` omits `pipelex.runtime_hub`, so `is_runtime_layer(module_qname="pipelex.runtime_hub")` is `False` and the module at the centre of the rule is exempt from it. Verified by injecting the forbidden import in memory (the file on disk was not touched):
-
-```
-runtime_hub.py WITH a forbidden interpreter_hub import -> NONE (guard says PASS)
-same import in a real runtime-layer module -> [(35, 'interpreter-hub-import')]
-```
-
-18 modules in `runtime_hub`'s real 225-module closure sit outside the layer rule. The closure test does catch this one (`pipelex.runtime_hub` is an entry point asserting `pipelex.interpreter_hub not in sys.modules`), so the architecture holds — the hole is in the fast, well-named gate.
-
-The fix is one tuple entry and was verified zero-risk: with `"pipelex.runtime_hub"` added, violations across `pipelex/` + `tests/` are still **0**, and the injected import is caught at line 35.
-
-Also correct `docs/contribute/hub-layering.md:110`, which says `pipe_output` is *"the one runtime-layer module the guard's declaration does not cover"*. `runtime_hub` itself is another, and it is the load-bearing one.
-
-## Phase A — in-PR fixes
-
-Ordered so each step leaves the tree green. **A1, A2 and A6 touch `hub-layering-convention` drift triggers** (`pipelex/cli/dev_cli/commands/hub_layering_guard.py`, `pipelex/runtime_hub.py`), so the contract re-opens: `git add` the trigger files, then `make drift-ack CONTRACT=hub-layering-convention RATIONALE="…"` with an honest sentence.
-
-**A1 is the only item that changes what the boundary actually guarantees. Per [D-R4](#decisions-taken) (decided 2026-07-27) it is now split: only the doc-honesty fix below stays in #1062; the remedy — (d)+(c) — is its own follow-up PR.** Everything else in the phase is independent of A1 and of each other, and can be done in any order.
-
-- [x] **A1 (in #1062) — correct the doc.** ✅ Applied. Per [F1.c](#f1c--the-headline-property-is-not-damaged): `docs/contribute/hub-layering.md:184` ("Every declared package is compliant") is true only of the direct-import rule and reads as a claim about the property — the branch must not merge shipping a claim the measurement contradicts; the Known-inversions preamble at `:217` needs the measurement (the inversion loads `interpreter_hub` and 67 interpreter modules today), not just the placement note, and understates both listed instances; `plugins/discovery.py` + `plugins/builtins.py` are not listed there at all despite pulling `builder` and `codegen`. State that the fix is decided and planned ([D-R4](#decisions-taken)). Do **not** repeat the original draft's framing that the headline property is broken — it is not.
-- [x] **A1-PR (own branch `refactor/Hub-2`, off the #1062 merge commit) — apply remedy (d)+(c).** ✅ Applied 2026-07-27, exactly the scope [D-R4](#decisions-taken) and the [Resolutions](#remedy-d--resolutions-2026-07-27) set, with no scope added. Full record at [Checkpoint A1](#checkpoint-a1-record--the-f1-remedy).
-- [x] **A2 — close the [F2](#f2-the-guard-does-not-enforce-its-own-rule-on-runtime_hubpy) guard gap.** ✅ Applied; re-verified both ways (0 violations tree-wide, injected import caught). Add `"pipelex.runtime_hub"` to `RUNTIME_LAYER_PACKAGES`; fix the `:110` sentence in `hub-layering.md`. Note the tuple is named `..._PACKAGES` but `is_runtime_layer` matches a bare module fine (`==` or `startswith(pkg + ".")`); add a line to its docstring saying so. Verified zero-risk: still 0 violations, and it catches an injected `interpreter_hub` import at line 35.
-- [x] **A3 — delete write-only `RuntimeHub._class_registry`.** ✅ Applied, grant dropped. Remove the field, `set_class_registry`, `get_required_class_registry`, the `pipelex/pipelex.py:339` call, and the now-stale grant `pipelex/runtime_hub.py::RuntimeHub.set_class_registry` (grant staleness is symmetric — `make cko` hard-fails until the registry is cleaned). `get_required_class_registry` has **zero callers** in this repo or any sibling repo; verified. It is pre-existing, but this PR deleted `_observer` for exactly this reason, so the twin is a missed sweep. It is also a live trap: it returns the boot-time global while the module-level `get_class_registry()` returns the **library-scoped** registry, so under `scoped_current_library(...)` the two differ — and the PR's own new test pins that divergence.
-- [x] **A4 — hoist the loop-invariant lookup.** ✅ Applied. `pipelex/core/pipes/rendering/input_renderer.py:134` calls `get_concept_library()` once per `_delighten_template` iteration. Hoist it above the `for`. It also defeats `resolve_input_kind`'s `DYNAMIC` early return, which used to skip the lookup entirely.
-- [x] **A5 — resolve `PipeProviderAbstract`.** ✅ **Deleted** (the first of the two options), `get_required_pipe` back on `PipeLibraryAbstract`, grant re-recorded there, docstring + `hub-layering.md` + CHANGELOG updated to state the absence is deliberate. Rationale in the [Checkpoint A record](hub-split-tracker.md). It has zero consumers, and its docstring describes the opposite of what the code does: it says core declares pipe resolution *"as a parameter instead of reaching for `interpreter_hub.get_required_pipe`"*, while `core/pipes/rendering/output_renderer.py:51` (a condition's mapped pipes) and `:84` (a sequence's last step) — the two cases the docstring names — both call `interpreter_hub.get_required_pipe` directly. It buys no closure property either, since `core.pipes` is not runtime-layer. **Either delete it** and put `get_required_pipe` back on `PipeLibraryAbstract` (smallest correct surface, consistent with the repo's no-speculative-additions rule), **or** keep it for symmetry with `ConceptProviderAbstract` and rewrite the docstring to say it is not consumed yet. Deleting also means dropping its subject grant.
-- [x] **A6 — doc/comment/CHANGELOG accuracy.** ✅ Applied. Five independent one-liners:
- - `pipelex/runtime_hub.py:9-11` forbids naming `core.concepts` and `core.pipes`, but `core.concepts` is a **declared runtime-layer package** and is in `runtime_hub`'s own closure — as line 415 of the same file says. Match the canonical doc: `core.bundles`, `core.interpreter`, and the Pipe-touching modules of `core.pipes`.
- - `pipelex/pipelex.py:122-124` claims RuntimeHub must be installed first because the scoping install *"needs a RuntimeHub already in place"*. It does not — `class_registry_scoping.install` lives in a module that imports nothing from `pipelex`, and `_resolve_scoped_class_registry` reads only the contextvar and the library manager, lazily. State the real reason (runtime is the lower layer, so it reads first) or drop the clause.
- - `CHANGELOG.md:8` maps `TextFormat` / `TemplatingStyle` / `TagStyle` to `pipelex.tools.templating`, whose `__init__.py` is **0 bytes**: `from pipelex.tools.templating import TextFormat` raises `ImportError`. Name the exact modules, as every other entry in the same sentence does. This is the artifact external consumers read.
- - `concept_provider_abstract.py:5` and `pipe_provider_abstract.py:8` still say *"stays high"* — the only two survivors of the low/high → runtime/interpreter vocabulary sweep. **Correction found while applying: there were four.** `libraries/concept/concept_library_abstract.py:11` and `libraries/pipe/pipe_library_abstract.py:11` carried "stays here, high"; the grep that found the first two did not match that phrasing. All four are swept (`pipe_provider_abstract.py` via A5's deletion).
- - `TODOS.md:339` and `:500-501` are off by one. Measured at HEAD: **269 modules / 20,305 SLOC** (claimed 268 / 20,304). The base and H-1 rows reproduce to the digit, so this is a stale re-take, not environment drift. The 0-interpreter-modules row is exact. **Confirmed at Checkpoint A** by re-reading every closure module at both revisions; both tables now carry the correction plus a fresh post-Phase-A column (269 / 20,299).
-- [x] **A7 — regenerate the stale error page.** ✅ Applied; the generator also re-filed the index entry into "platform and tooling", following the class's new subsystem. `JobMetadataError` moved to `pipelex/system/exceptions.py`, but `docs/errors/job-metadata-error.md:16` still reports `pipelex.pipeline.exceptions`. It is the only stale page in the set, i.e. `make generate-error-pages` (alias `gep`) was never run in this PR. That page is the `type_uri` target users land on from a runtime error.
-- [x] **A8 — restate the class-registry leaf-import rule.** ✅ Applied; the three-importer split was re-verified at HEAD (`concept.py` inside the closure, the other two outside). `docs/contribute/hub-layering.md:164` says to import `class_registry_access` directly *"only from inside `runtime_hub`'s import closure"* — but two of the three in-tree importers are **not** in that closure (`concept_factory.py` and `structure_generation/generator.py`; only `concept.py` is). The code is right and the rule is wrong: the real criterion is "a module that must stay import-light with respect to `runtime_hub` uses the leaf". As written the rule invites someone to "fix" `concept_factory.py` to import from `runtime_hub`, silently re-coupling `core.concepts` to the whole cogt/plugin stack. Nothing checks this mechanically.
-
-> **CHECKPOINT A** — run `make agent-check`, then the full `make agent-test`, then `make drift-check` and ack the re-opened contract. Re-take the two `Measured after` tables in `TODOS.md` at that point rather than copying A6's numbers, since A2–A5 may move them. Push and let CI confirm before starting Phase B.
->
-> Per [D-R4](#decisions-taken), the checkpoint covers A1's doc fix plus A2–A8 only — **no red entry point is added in #1062**; the remedy lands in the A1-PR after merge. [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) plus the corrected Known-inversions section are the record that keeps the breach visible in the meantime.
-
-## Phase B — test hardening
-
-Additive; landed in one commit after Checkpoint A. B1 and B2 are the two that pin things the current tests only *appear* to pin.
-
-**Every item was verified by mutation, not by watching it go green** — the pinned behavior was removed, the new test was confirmed to fail, and the mutation reverted. What each mutation showed is recorded per item.
-
-- [x] **B1 — test the real teardown, not a simulation.** ✅ Applied. `tests/unit/pipelex/test_hub_lifecycle.py:70` calls `class_registry_scoping.reset() # what Pipelex.teardown does`. Nothing pinned that the production lines in `Pipelex.teardown` / `teardown_if_needed` do anything — delete them and the suite stayed green, because a stale `_library_id` resolves to `None` and falls back to the global registry rather than raising. Added a real boot → pin a scoped library → `Pipelex.teardown_if_needed()` → assert unscoped → fresh `Pipelex.make()` → assert the resolver is re-installed. The simulation test is kept (it pins `reset()`'s own semantics) with its comment corrected so it no longer claims to cover the wiring. **Mutation-verified**: deleting `class_registry_scoping.reset()` from `Pipelex.teardown` fails the new test and *only* it — the other three in the module still pass, which is exactly the finding.
-- [x] **B2 — give the closure detector a negative control.** ✅ Applied. `_CLOSURE_SCRIPT` is a `textwrap.dedent` string, so no linter sees `INTERPRETER_PACKAGES` / `is_interpreter`; a typo makes all entry points pass vacuously, forever. Parametrized `(entry_point, expected_returncode)` with `pipelex.interpreter_hub` as the dirty case. **One thing the plan did not anticipate, and it changes the assertion**: asserting `returncode == 1` alone would *not* have pinned the predicate, because the script's second check (`pipelex.interpreter_hub in sys.modules`) exits 1 for that entry point regardless. The test asserts the **offender message** as well, so the control fails when `is_interpreter` stops working. **Mutation-verified**: typo-ing `INTERPRETER_PACKAGES` and emptying `INTERPRETER_CORE` fails the control while all eight clean entry points pass vacuously — the exact failure mode.
-- [x] **B3 — cover `check_hub_layering_cmd`.** ✅ Applied as `tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py`, mirroring `test_check_keyword_only_cmd_fix.py`'s mocked-console/mocked-scanner shape. Covers both `sys.exit(1)` paths, the quiet/panel split both ways, the per-kind grouping with its remedy, and that the success panel names every declared runtime-layer package. The missing-root case asserts the scanner is **never called** — scanning nothing must not read as a pass. **Mutation-verified**: removing both `sys.exit(1)` calls fails four of the six tests.
-- [x] **B4 — cover the guard's filesystem surface.** ✅ Applied as `tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py`, a tmp tree in the style of `test_keyword_only_guard_single_file.py`. Covers `collect_all_violations` over both roots (a runtime-layer breach reported, the identical import in `pipeline/` correctly *not*, a `tests/` dead-hub string reported), `iter_source_files`' `__pycache__` exclusion, and `module_qname_for`'s `__init__`-stripping both directly and end to end through a real scan. **Mutation-verified**: dropping the `__pycache__` skip fails two tests.
-- [x] **B5 — test `concept_provider` as an actual injection.** ✅ Applied as `tests/unit/pipelex/core/memory/input_shaper/test_provider_injection.py`. A `mocker.Mock(spec=ConceptProviderAbstract)` whose `is_compatible` only ever matches `Number` moves a `Text` concept from the TEXT arm to the NUMBER arm — an outcome unreachable through the real library. **Mutation-verified**: making `resolve_input_kind` accept the parameter and then call `get_concept_library()` anyway fails this test alone, with all 69 other `input_shaper` tests green.
-- [x] **B6 — tighten the `TYPE_CHECKING` carve-out.** ✅ Applied — tightened, not pinned-as-deliberate. `_is_type_checking_test` now requires the receiver to be `Name(id="typing")` (new `TYPING_MODULE_NAME` constant), with a test asserting three unrelated receivers stay violations. Verified safe first: nothing in `pipelex/` or `tests/` uses the attributed form at all, let alone under an alias. **Mutation-verified**: reverting to `ast.Attribute(attr=attr)` fails the new test and nothing else.
-- [x] **B7 — bound the closure subprocess.** ✅ Applied. `subprocess.run` gained `timeout=SUBPROCESS_TIMEOUT_SECONDS`, wrapped in a `_run_closure` helper that turns `TimeoutExpired` into an `AssertionError` naming the entry point and the bound.
-
-> **CHECKPOINT B** ✅ **CLEARED** — `make agent-check` ✅ · full `make agent-test` ✅ · `make drift-check` ✅.
->
-> **Correction to this plan: B6 *does* re-open a drift contract.** `pipelex/cli/dev_cli/commands/hub_layering_guard.py` is a `hub-layering-convention` trigger, so the note that said "nothing here re-opens a drift contract" was wrong. Reviewed and acked: `docs/contribute/hub-layering.md`'s `TYPE_CHECKING` bullet now states the receiver constraint, and its two test-module sentences were refreshed for B1/B2/B7. Worth carrying forward — the review caught staleness the contract's own triggers **cannot** see: the two test modules are deliberately not triggers, so the contract fired on the guard and the read-through found the spillover. Logged in `wip/drift-contracts/dogfood-log.md` as the second consecutive `real-catch` for this contract.
->
-> Per [D-R4](#decisions-taken) the property-side fix is in the A1-PR, not here: no new green entry point landed in #1062, and B2's control is dirty by definition so it survives the remedy unchanged.
-
-## Checkpoint A1 record — the F1 remedy
-
-Branch `refactor/Hub-2`, off `6fbdcb2fd` (the #1062 merge). Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,361 files, keyword-only PASSED, hub-layering PASSED) · full `make agent-test` ✅ · `make tb` ✅ · `make drift-check` ✅ (two contracts reviewed and acked — see below).
-
-### What landed, against what was planned
-
-The [four moves of (d)](#remedy-d--split-the-built-ins-by-layer) plus [(c)](#remedy-options-with-what-was-measured-about-each), and nothing else:
-
-- **`pipelex/interpreter_plugins/`** is the new interpreter-side home. `plugins/direct/` and `plugins/pipe_func/` moved there wholesale (`git mv`, subpackage shape preserved, so the only churn is the parent path). Its `builtins.py` imports the runtime half — downward, which the interpreter layer may do — and exports the composed `BUILTIN_PLUGINS` / `CORE_UNCONDITIONAL_PLUGIN_NAMES`.
-- **`pipelex/plugins/builtins.py`** keeps the seventeen runtime adapters as `RUNTIME_BUILTIN_PLUGINS` / `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES`. The composed list keeps the canonical names, so exactly one symbol still answers "what are the built-in plugins".
-- **`build_registrar` takes both as required keyword parameters.** No default, so a caller cannot silently boot with half the plugins. Both call sites — `pipelex.py` and the `pipelex plugins list` diagnostic — pass the composed lists.
-- **The guard learned the transitive rule** (`collect_transitive_violations`): build the module-level import graph of `pipelex/`, reverse-BFS once from `interpreter_hub` to find every module that reaches it, then report the runtime-layer ones with the shortest chain and the line of the first hop. Module-level imports only, `TYPE_CHECKING` and function bodies excluded; a *direct* import is left to rule 1 rather than double-reported; no escape hatch.
-- **`pipelex.plugins.builtins` joined the closure test's entry points** — one, as decided, not the broad five-package addition.
-- **`PipelexPlugin`'s docstring carries the one-plugin-one-layer invariant**, as a sentence, not machinery.
-
-### Measured
-
-```
- before after
-declared runtime-layer modules 477 473 (4 relocated)
- ... reaching interpreter_hub 4 0
-pipelex.plugins modules 131 127
-pipelex.plugins.discovery interp= 67 0
-pipelex.plugins.builtins interp= 67 0
-```
-
-The plan's simulation predicted **128** modules left in `pipelex.plugins`, not 127: its `RELOCATED` filter used the prefix `pipelex.plugins.pipe_func.` with a trailing dot, which misses the package's own `__init__`. Four files moved, not three.
-
-The *before* figure is **477**, not the 476 the [F1.a sweep](#f1a--the-blast-radius-is-exactly-pipelexplugins) printed: that table has one row per declared runtime-layer **package** and so omits `pipelex.runtime_hub`, which is a bare *module* entry in `RUNTIME_LAYER_PACKAGES` — and the one module the whole rule exists to protect. Its reaching count was 0 either way, so no conclusion moves; the sweep's own rows are kept verbatim above as the record. Re-measured on the base commit with the shipped guard's helpers: per-entry sum and distinct count both 477, `pipelex.runtime_hub → 1`. 477 → 473 is the same four relocated modules the `pipelex.plugins 131 → 127` row already counts.
-
-**What the transitive rule costs, measured honestly.** Do not difference against the 2.79s in the [remedy options](#remedy-options-with-what-was-measured-about-each) — that was taken in an earlier session on a different tree, and comparing to it understates the cost. Measured back-to-back on this tree, same binary, with the transitive pass enabled and then disabled:
-
-```
-with 3.06s / 2.87s / 2.83s in-process: per-file rules (both roots) 1.50s
-without 2.46s / 2.48s / 2.47s transitive rule (pipelex/) 0.38s
-```
-
-**+0.38s, or +15% of the command** (+25% of the scan work; the remaining ~1.0s is process startup). Under the 0.83s the prototype suggested, but not free.
-
-**All of it is re-parsing.** Over 956 modules and 4,403 edges: the reverse-BFS reachability is **0.5ms**, and the graph visitor is cheaper than the per-file collector (it skips function bodies and walks no string constants). So the honest description is not "reachability is cheap because it runs once in reverse" — it is "the pass parses the tree a second time, and parsing is the whole bill."
-
-That is also where the optimization is, if the cost ever matters: the per-file pass already parses every `pipelex/` module, so feeding one parse to both collectors would recover most of the 0.38s. **Deliberately not done.** It would couple two passes that are currently independent and independently testable — `find_violations_in_source` takes *source text* and is what the snippet tests drive, while the graph builder needs an AST plus a resolved qname per file — and 0.38s on a gate whose parent (`make agent-check`) is dominated by pyright and mypy is not worth that. Revisit only if `pipelex/` grows enough to make the guard a felt cost in CI.
-
-### Verified by reproducing the defect, not only by going green
-
-A rule that reports nothing is indistinguishable from a rule that sees nothing. So the new check was run against **`HEAD` — the pre-remedy tree** (`git archive HEAD pipelex`, scanned with the new guard from the working tree): it reproduces F1 exactly — the same four modules, with the same three routes [F1.b](#f1b--there-are-three-routes-not-one) documented, including both of `direct_plugin`'s independent routes. On the fixed tree it reports 0. The ten unit tests in `tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py` were mutation-verified: dropping the function-body skip fails the two deferred-import cases, dropping the runtime-layer filter fails two more, and reporting direct imports fails the no-double-report case.
-
-### The existing tests this touched, and why
-
-- `test_plugin_discovery.py` patched `discovery.BUILTIN_PLUGINS`, a module global that no longer exists. Its helper now passes the list in — which is the honest shape anyway, since that is how production calls it. It gained one test pinning that the composed list *is* both halves in order, with unique names: the failure mode the split introduces is a half silently dropping out, which would present as a plugin quietly missing at boot rather than as an import error.
-- `test_import_light_boot.py` imports the composed list inside its blocked-SDK subprocess. Loading it pulls the interpreter, which is expected and is exactly why discovery takes the list as a parameter; the assertion — that registering the built-ins imports no backend SDK — is unchanged and still passes.
-- `test_check_hub_layering_cmd.py` now mocks **both** scans. Mocking only the per-file one would have left the transitive pass walking the real tree inside a unit test. Two tests were added: the merged report, and a transitive finding failing the gate on its own.
-
-### Drift
-
-Both re-opened contracts were reviewed for real and acked, with entries in `wip/drift-contracts/dogfood-log.md`:
-
-- **`hub-layering-convention` — real-catch (third consecutive non-import-churn opening).** This one is a new mode worth naming: the doc honestly recorded the defect *and* announced the planned fix, so landing the fix falsified two of its sections by design. A doc that records a known defect accrues a debt only a trigger can call in. The contract's two prescribed mechanical checks both passed unchanged (33 + 32 hub symbols covered, 12 declared packages named) and again saw none of it — three for three.
-- **`cli-docs` — clean-pass, but the first on a genuinely behavior-adjacent trigger** rather than an import sweep: `plugins_cmd.py`'s call actually changed shape. Reviewed against the live CLI: same subcommand, same options, same five columns, all 19 built-ins in the same order.
-
-### What this does *not* do
-
-- **Nothing loads less.** `pipelex.py` is still the only caller that needs everything, so boot's closure is unchanged — as [the counterargument](#remedy-d--split-the-built-ins-by-layer) said it would be. The payoff is that the declaration is now true and mechanically kept true.
-- **`plugins/pipe_func_executor_registry.py`'s placement inversion is still unfixed** — it is type-only under `TYPE_CHECKING`, so it breaches neither rule. Still recorded in Known inversions.
-- **Phase C is untouched** and still release-gated.
-
-## Phase C — release-wave additions
-
-Per **D-R1**, none of this lands in PR #1062. Fold it into the existing release-gated cross-repo sweep in `TODOS.md`.
-
-### C1 — `pipelex.hub` is a governed, spec'd, conformance-tested surface
-
-`docs/specs/pipelex-transport-boundary.md` §A declares it: *"The `pipelex.hub` module is the intended cross-boundary seam; these accessors are stable by design."* It is verified by `conformance/tests/pipelex_transport/test_provider_surface.py`, which carries **no skip marker** — it is active. Running that suite's own `ALLOWED_SURFACE` against this branch:
-
-```
-governed surface entries: 41
-BROKEN by this branch: 7
- MODULE DELETED pipelex.hub::get_orchestrator_registry
- MODULE DELETED pipelex.hub::get_required_pipe
- MODULE DELETED pipelex.hub::get_library_manager
- MODULE DELETED pipelex.hub::scoped_current_library
- MODULE DELETED pipelex.hub::get_current_library_id_or_none
- MODULE DELETED pipelex.pipeline.job_metadata::JobMetadata
- MODULE DELETED pipelex.graph.trace_context::TraceContext
-```
-
-The workspace `CLAUDE.md` rule is explicit: *"When you change a documented surface in `docs/specs/` or its verifying test in `conformance/`, update both sides in the same change and run `make check-spec-links`."* Strictly, this PR is already out of compliance with that rule; D-R1 accepts that consciously because the whole consumer sweep is release-gated and splitting spec-from-consumers would be worse. **The release wave must update section A of the spec** (all five accessors are interpreter-layer), retarget the `JobMetadata` / `TraceContext` rows to `pipelex.system.*`, update `conformance/tests/pipelex_transport/test_data.py` in lockstep, and run `make check-spec-links` in `conformance/`.
-
-### C2 — five consumer repos are missing from the sweep tables
-
-Every count the tables *do* list reproduces exactly (temporal 35, mistralai-workflows 11, api 9, cookbook 2, cocode 2). They are simply incomplete:
-
-| repo | `pipelex.hub` files | moved-type files | pipelex pin | why it matters |
-| --- | --- | --- | --- | --- |
-| `pipelex-transport` | **8** (2 production) | 7 | `>=0.40.0` | `pipelex_transport/bridge.py:165` calls `WorkingMemoryFactory.make_from_pipeline_inputs` **without the now-required `concept_provider`** — the only production call site of a changed signature outside this repo |
-| `pipelex-daytona-sandbox` | 1 | 3 | `>=0.40.0` | **entry-point plugin** (`[project.entry-points."pipelex.plugins"]`), so it fails inside a *host* pipelex process at registration, not in its own tests |
-| `pipelex-demo-mistral` | 9 | 5 | `>=0.35.0` | 4+ example workflows call the changed signature |
-| `pipelex-demo-vibe` | 9 | 5 | `>=0.35.0` | same (both are checkouts of `pipelex-demos.git`) |
-| `conformance` | — | 1 | dynamic | C1 above |
-
-All unbounded `>=` pins, so all resolve to the new release. `pipelex-workshop` (`==0.20.3`) and `pipelex-demos` / `pipelex-demo-frostbeam` (`==0.34.0`) also import `pipelex.hub` but are version-pinned, so they are safe — list them for completeness, not urgency. `test-bed` has one test-only import at `>=0.18.3`.
-
-Note that `pipelex-transport` and `pipelex-daytona-sandbox` are **absent from the workspace `CLAUDE.md` repo table too**, which is why they were missed. Adding them there is the durable fix; otherwise the next sweep misses them again.
-
-### C3 — the moved types are a wire-format change, not only an import change
-
-`CHANGELOG.md:8` says *"only the Python homes moved."* For `JobMetadata` and `TraceContext` that undersells it: kajson embeds `__module__` in the serialized payload, and the Temporal data converter kajson-encodes every `BaseModel` crossing the workflow/activity boundary — `PipeJob.job_metadata: JobMetadata` is on that path. Verified: encoding now emits `"__module__": "pipelex.system.job_metadata"`, and decoding an old payload raises `KajsonDecoderError`.
-
-**This is not a bug** — Temporal has never shipped to production, and the repo's no-backward-compat policy is explicit. It is worth one changelog sentence so a plugin maintainer knows the runner and worker must roll forward together rather than independently.
-
-## Considered and not changed
-
-Recorded so these are not re-litigated. Each was investigated and is a deliberate tradeoff, not an oversight:
-
-- **`class_registry_scoping.reset()` in `Pipelex.teardown` is process-global while `_library_id` is a ContextVar.** A run still in flight when teardown fires loses its per-run scoped registry and falls back to the shared one (which `KajsonManager.teardown()`, twelve lines earlier, has already re-minted empty). Pre-refactor this window did not exist. Reachability is narrow — process shutdown or a failed boot with concurrent in-flight runs — and everything else is being demolished at that moment anyway. **D-R3: accepted as designed**; the reset is what makes a torn-down library unreachable, which is the property step 1.7 was written for.
-- **boto3 loads eagerly in every booted process.** `pipelex/tracing/event_log_factory.py:5` imports `dynamodb_event_log`, which runs a module-level `try: import boto3` unconditionally — even for the default NDJSON backend. It is **not** in the guarded runtime closure, so the headline property is unaffected, but it *is* in `import pipelex.pipelex`'s closure: ~41 ms and ~150 modules, against the ~27 ms this entire refactor buys on full boot. A three-line fix (move the import into the `case TracingBackend.DYNAMODB:` branch, the pattern `render_generate.py` already uses for pypdfium2). Out of scope here, but the tracker should stop filing it under "not scheduled" when it dominates the number the tracker headlines.
-- **The D5 indirection costs ~32 ns per `get_class_registry()` call** (213 ns → 245 ns, three frames instead of one). Not on any hot path — the call sites are per-concept-resolution, not per-item. No action; recorded so nobody collapses the layering later on a hunch, since the indirection is what makes the zero-interpreter closure possible.
-- **Wall-clock is a smaller win than the module count suggests.** `content_generator` improves 412 ms → 359 ms (-13%), but `import pipelex.pipelex` only 718 ms → 691 ms (-4%), because third-party imports dominate and are untouched (767 non-pipelex modules remain: pydantic 70, faker 66, rich 63, markdown_it 62, polyfactory 28). Nothing in the PR overstates this; the tracker simply does not state it. The win is architectural and accrues to runtime-only embedders, not to CLI startup.
-- **The published `hub-layering.md` points at `wip/pr-1062-review-notes.md`**, and two test docstrings do the same. `wip/` is outside `docs_dir`, so the reference is unreachable for a reader on docs.pipelex.com, and the file is by convention archived once the PR lands. Fold the wart into one in-place sentence in the published doc and keep the pointer only in `TODOS.md`. Low priority; batch it with A5 if convenient.
-- **`drift.toml`'s `hub-layering-convention` omits `pipelex/system/registries/class_registry_access.py`** from its triggers, though the doc it protects devotes a named section to that module. Renaming `class_registry_scoping` or changing the default-resolver semantics would silently falsify it. One line to add whenever the contract is next touched.
-- **`hub_layering_guard` duplicates two filesystem helpers from `keyword_only_guard`.** The stated rationale is half right: `keyword_only_guard` genuinely is stdlib-only and has a by-path `__main__` entry, so a shared third module would defeat its cold-start budget — but that does not explain why `hub_layering_guard` could not import *from* it, since it has no `__main__` and its only importer already pulls `pipelex.runtime_hub`. The copies have already drifted (positional vs keyword-only signatures). Either import them or correct the docstring.
-
-## Reproduction commands
-
-Everything above was measured with these. Run from `_hub/`.
-
-```bash
-# F1 — a declared runtime-layer module reaching interpreter_hub transitively.
-# Swap in pipelex.config / pipelex.cogt.content_generation.content_generator / pipelex.runtime_hub
-# for the F1.c control: those measure interp=0 and never load plugins.builtins.
-for m in pipelex.plugins.direct.direct_plugin pipelex.plugins.discovery; do
- .venv/bin/python -c "
-import sys, importlib
-importlib.import_module('$m')
-INTERP={'libraries','pipe_operators','pipe_controllers','codegen','builder'}
-mods=[n for n in sys.modules if n.startswith('pipelex.')]
-print('$m', 'interpreter_hub=', 'pipelex.interpreter_hub' in sys.modules,
- 'interp=', len([n for n in mods if n.split('.')[1] in INTERP]),
- 'builtins=', 'pipelex.plugins.builtins' in sys.modules)"
-done
-.venv/bin/pipelex-dev check-hub-layering --quiet # still PASSED
-
-# F1.b — the shortest real import path to each offender, traced rather than guessed
-.venv/bin/python -c "
-import importlib, sys
-chain, stack = {}, []
-real = importlib._bootstrap._find_and_load
-def traced(name, import_):
- if stack and name not in chain: chain[name] = stack[-1]
- stack.append(name)
- try: return real(name, import_)
- finally: stack.pop()
-importlib._bootstrap._find_and_load = traced
-importlib.import_module('pipelex.plugins.discovery')
-for target in ('pipelex.interpreter_hub', 'pipelex.libraries', 'pipelex.builder', 'pipelex.codegen'):
- path, cur = [target], target
- while cur in chain: cur = chain[cur]; path.append(cur)
- print(' <- '.join(path))"
-
-# F1.a / F1.d — the static sweep: which declared runtime-layer modules reach interpreter_hub,
-# and which declared packages have no closure-test entry point.
-.venv/bin/python - <<'PY'
-import ast, sys
-from collections import deque
-from pathlib import Path
-sys.path.insert(0, ".")
-from pipelex.cli.dev_cli.commands.hub_layering_guard import RUNTIME_LAYER_PACKAGES, is_runtime_layer
-
-def qname(p):
- parts = list(p.with_suffix("").parts)
- return ".".join(parts[:-1] if parts[-1] == "__init__" else parts)
-
-class V(ast.NodeVisitor):
- def __init__(self, pkg): self.pkg, self.out, self.tc = pkg, set(), 0
- def visit_If(self, n):
- t = n.test
- if (isinstance(t, ast.Name) and t.id == "TYPE_CHECKING") or (isinstance(t, ast.Attribute) and t.attr == "TYPE_CHECKING"):
- self.tc += 1
- for s in n.body: self.visit(s)
- self.tc -= 1
- for s in n.orelse: self.visit(s)
- else: self.generic_visit(n)
- def visit_FunctionDef(self, n): pass # deferred imports do not load
- def visit_AsyncFunctionDef(self, n): pass
- def visit_Import(self, n):
- if not self.tc:
- self.out.update(a.name for a in n.names if a.name.startswith("pipelex"))
- def visit_ImportFrom(self, n):
- if self.tc: return
- if n.level:
- parts = self.pkg.split(".") if self.pkg else []
- base = ".".join(parts[: len(parts) - (n.level - 1)])
- base = f"{base}.{n.module}" if n.module else base
- else: base = n.module or ""
- if base.startswith("pipelex"):
- self.out.add(base); self.out.update(f"{base}.{a.name}" for a in n.names)
-
-edges, all_mods = {}, set()
-for p in sorted(Path("pipelex").rglob("*.py")):
- if "__pycache__" in p.parts: continue
- q = qname(p); all_mods.add(q)
- v = V(".".join(p.parent.parts)); v.visit(ast.parse(p.read_text(encoding="utf-8")))
- edges[q] = v.out
-
-def resolve(c):
- while c:
- if c in all_mods: return c
- if "." not in c: return None
- c = c.rsplit(".", 1)[0]
-
-TARGET = "pipelex.interpreter_hub"
-runtime_mods = sorted(m for m in all_mods if is_runtime_layer(module_qname=m))
-
-# --- Remedy (d) simulation: uncomment the four edits to measure the split+relocation ----
-# Must run BEFORE the BFS below, since it rewrites the edges the BFS walks.
-# Expect: 128 scanned, 0 reaching interpreter_hub (against 476 / 4 unsimulated).
-# RELOCATED = {m for m in all_mods if m.startswith(("pipelex.plugins.direct", "pipelex.plugins.pipe_func."))}
-# edges["pipelex.plugins.builtins"] = {e for e in edges["pipelex.plugins.builtins"]
-# if not e.startswith(("pipelex.plugins.direct", "pipelex.plugins.pipe_func."))} # builtins splits
-# edges["pipelex.plugins.discovery"] = {e for e in edges["pipelex.plugins.discovery"]
-# if not e.startswith("pipelex.plugins.builtins")} # discovery takes a param
-# runtime_mods = [m for m in runtime_mods if m.startswith("pipelex.plugins") and m not in RELOCATED]
-
-bad = {}
-for start in runtime_mods:
- seen, q = {start}, deque([(start, [start])])
- while q and start not in bad:
- cur, path = q.popleft()
- for raw in edges.get(cur, ()):
- m = resolve(raw)
- if m is None or m in seen: continue
- if m == TARGET: bad[start] = path + [m]; break
- seen.add(m); q.append((m, path + [m]))
-
-print(f"scanned {len(runtime_mods)} declared runtime-layer modules; {len(bad)} reach {TARGET}")
-EPS = ["pipelex.cogt.content_generation.content_generator", "pipelex.runtime_hub",
- "pipelex.core.concepts.structure_generation.generator", "pipelex.core.memory.input_shaper",
- "pipelex.core.memory.working_memory_factory", "pipelex.core.pipes.inputs.input_stuff_specs_factory",
- "pipelex.core.pipes.stuff_spec.stuff_spec_factory", "pipelex.core.stuffs.stuff_factory"]
-for pkg in RUNTIME_LAYER_PACKAGES:
- inside = lambda m: m == pkg or m.startswith(pkg + ".")
- n = len([m for m in bad if inside(m)])
- tot = len([m for m in runtime_mods if inside(m)])
- ep = "COVERED" if any(inside(e) for e in EPS) else "NO ENTRY POINT"
- print(f" {pkg:38s} {n:4d} / {tot:4d} breaching {ep}")
-for m, path in sorted(bad.items()): print(" ", " -> ".join(path))
-PY
-
-# F2 — the guard exempts runtime_hub.py from its own rule
-.venv/bin/python -c "
-import sys; sys.path.insert(0, '.')
-from pipelex.cli.dev_cli.commands.hub_layering_guard import is_runtime_layer
-print('runtime_hub is runtime layer:', is_runtime_layer(module_qname='pipelex.runtime_hub'))"
-
-# C1 — the governed surface, broken
-.venv/bin/python -c "
-import ast, importlib
-from pathlib import Path
-p = Path('/Users/lchoquel/repos/Pipelex/conformance/tests/pipelex_transport/test_data.py')
-for node in ast.walk(ast.parse(p.read_text())):
- if isinstance(node, ast.AnnAssign) and getattr(node.target, 'id', '') == 'ALLOWED_SURFACE':
- surface = [tuple(ast.literal_eval(e)) for e in node.value.elts]; break
-for mod, sym, _ in surface:
- try: importlib.import_module(mod)
- except ModuleNotFoundError: print('MODULE DELETED', f'{mod}::{sym}')"
-
-# The headline property (unchanged, still exact) — full snippet in TODOS.md 'Exit criteria'
-```
diff --git a/wip/inputs/README.md b/wip/inputs/README.md
index ec658c60e..918b66287 100644
--- a/wip/inputs/README.md
+++ b/wip/inputs/README.md
@@ -23,7 +23,7 @@ The mechanism: one shaper (`pipelex/core/memory/input_shaper.py`, `InputShaper`)
Shared across YesNo + Date + Smart Inputs, done **per-release, not per-feature**:
- **D10 protocol widening** — `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` widens to admit bare scalars / lists-of-dicts / empty lists ("any JSON value | StuffContent forms"), with the interpretation semantics spec'd MTHDS-side. Release-gated (Optionals/TOML-inputs de-gate pattern). Runtime already works; this is type-honesty for typed SDK/API callers.
-- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, conformance rows, JSON-schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.
+- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, cross-repo spec-suite rows, JSON-schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.
- **Authoring-guidance surfaces** — `mthds-plugins` skills (`mthds-inputs`, `mthds-build`), `vscode-pipelex` completion lists, and the `ConceptSpec.refines` native-list hint (derive from `NativeConceptCode` — see `refines-hint-native-list-drift.md`).
- **Off critical path** — LLM-assisted input adaptation (design §8, opt-in); the shared YesNo/Date scalar-native LLM-output ergonomics.
diff --git a/wip/inputs/datetime-design.md b/wip/inputs/datetime-design.md
index 528fdd4c5..ea7fa119b 100644
--- a/wip/inputs/datetime-design.md
+++ b/wip/inputs/datetime-design.md
@@ -66,7 +66,7 @@ departure = 2026-07-07T15:40:00+02:00 # a Date — with time and offset, faithf
`NativeConceptCode.DATE = "Date"`, concept ref `native.Date`, description: *"A calendar date, optionally with a time of day — as precise as its source states."* One new native, not two or three (§2). The track keeps its colloquial "Datetime" name in the roadmap; the concept an author sees is `Date`.
-Breaking consequence (native codes are reserved): a bundle declaring its own `[concept.Date]` becomes an error. Workspace grep (pipelex, cookbook, methods, test-bed) finds no such concept today. Changelog: breaking.
+Breaking consequence (native codes are reserved): a bundle declaring its own `[concept.Date]` becomes an error. Workspace grep across every repo finds no such concept today. Changelog: breaking.
### DT2 — Content shape: `DateContent` with `date` + optional `time`
@@ -130,7 +130,7 @@ Discovered while grounding this design: the structure-field type `date` (`Concep
- Schema regen (`pipelex-dev generate-mthds-schema`) — note the native ref itself doesn't change the schema shape; DT8 does (field-type enum).
- Docs: `docs/building-methods/concepts/native-concepts.md` table entry; inputs docs mention of TOML literals; `inline-structures.md` if DT8 ships.
- Tests: content-class unit tests (render matrix, offset round-trip), inputs-loader tests replacing the four-flavor rejection parametrization (date ✓, local datetime ✓, offset datetime ✓, local time ✗ narrowed), e2e `.mthds` with TOML date inputs, LLM-output smoke via existing structured-gen harness.
-- Downstream wave (per-release, shared with YesNo/Smart Inputs): MTHDS spec native table (`mthds/docs/language/concepts.md`, `spec/mthds-format.md`), schema sync, mthds-python/mthds-js mirrors, conformance, skills, editor tooling completion lists.
+- Downstream wave (per-release, shared with YesNo/Smart Inputs): MTHDS spec native table (`mthds/docs/language/concepts.md`, `spec/mthds-format.md`), schema sync, mthds-python/mthds-js mirrors, the cross-repo spec suite, skills, editor tooling completion lists.
## 7. Abandonability check
diff --git a/wip/inputs/datetime-implementation-plan.md b/wip/inputs/datetime-implementation-plan.md
index 641f58d2b..196c1167e 100644
--- a/wip/inputs/datetime-implementation-plan.md
+++ b/wip/inputs/datetime-implementation-plan.md
@@ -35,7 +35,7 @@ Status: **COMPLETE 2026-07-07.** All phases shipped, gates green. Design: `datet
**The one guard worth understanding** (`date_content.py` `_reject_lax_temporal`): pydantic's lax mode would silently corrupt data against the concept's own fidelity contract — a bare `int`/`float` or an **all-digit string** read as epoch seconds, and a `datetime` on the `date` field silently truncated (dropping its time + offset). The validator rejects all three (raising `ValueError` so pydantic wraps it into a `ValidationError` the input path catches). The factory's ISO parser rejects all-digit strings too, for consistency.
-**Deferred (nothing lost):** `wip/inputs/scalar-envelope-arm-asymmetry.md` and `wip/inputs/loader-vs-factory-date-split-duplication.md` (design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the per-release cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, conformance, skills, cookbook `type = "date"` regen). See "Deferred to the release-wave sweep" at the bottom.
+**Deferred (nothing lost):** `wip/inputs/scalar-envelope-arm-asymmetry.md` and `wip/inputs/loader-vs-factory-date-split-duplication.md` (design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the per-release cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, the cross-repo spec suite, skills, cookbook `type = "date"` regen). See "Deferred to the release-wave sweep" at the bottom.
How the log below reads: each phase is checked off, and each CHECKPOINT's "state" line records what landed, the commit, decisions taken, and anything that fought back.
@@ -120,7 +120,7 @@ State: **LANDED 2026-07-07.** DT8 shipped (not dropped). `type = "date"` → `da
### CHECKPOINT 4 — track complete, hand off to the next train car
-State: **track complete 2026-07-07.** The native `Date` concept ships end to end on `feature/Smart-inputs` (Phases 1–4, commits `0b6d201bb` → `6dd17e452`, plus this Phase 5 docs/wrap commit). All gates green. Deferred (in `wip/inputs/`): the scalar-envelope arm asymmetry and the loader-vs-factory date-split duplication (both design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the release-wave cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, conformance, skills, cookbook `type = "date"` regen). Next train car: the Smart Inputs step (`smart-inputs-design.md`).
+State: **track complete 2026-07-07.** The native `Date` concept ships end to end on `feature/Smart-inputs` (Phases 1–4, commits `0b6d201bb` → `6dd17e452`, plus this Phase 5 docs/wrap commit). All gates green. Deferred (in `wip/inputs/`): the scalar-envelope arm asymmetry and the loader-vs-factory date-split duplication (both design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the release-wave cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, the cross-repo spec suite, skills, cookbook `type = "date"` regen). Next train car: the Smart Inputs step (`smart-inputs-design.md`).
### PR round — #1029 (stacked on YesNo #1028), bot-review pass
@@ -140,9 +140,9 @@ The plan's finalize step ran: gstack `/review` (Opus 4.8) with a testing + maint
## Deferred to the release-wave sweep (NOT this plan's scope — listed so nothing is lost)
-Shared per-release wave with YesNo + Smart Inputs (see `README.md`): MTHDS spec native-concepts tables (`mthds/docs/language/concepts.md`, `mthds/docs/spec/mthds-format.md`); schema-copy sync via the `mthds-schema-sync` skill; `mthds-python` protocol widening for bare temporal scalars (rides Smart Inputs D10) + any native-list mirrors; `mthds-js` mirrors; conformance rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); editor tooling completion lists (vscode-pipelex). Plus the YesNo/Date shared follow-up: LLM-output ergonomics for scalar natives.
+Shared per-release wave with YesNo + Smart Inputs (see `README.md`): MTHDS spec native-concepts tables (`mthds/docs/language/concepts.md`, `mthds/docs/spec/mthds-format.md`); schema-copy sync via the `mthds-schema-sync` skill; `mthds-python` protocol widening for bare temporal scalars (rides Smart Inputs D10) + any native-list mirrors; `mthds-js` mirrors; cross-repo spec-suite rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); editor tooling completion lists (vscode-pipelex). Plus the YesNo/Date shared follow-up: LLM-output ergonomics for scalar natives.
-`pipelex-temporal` (private plugin repo): **no code change expected** — its codec serializes the `dump_for_transport` dict via kajson and binds classes through the registry, so `DateContent` flows in with the pipelex version-pin bump. At pin-bump time, add a `Date` case to its converter round-trip tests anyway: the failure mode over there is a hang, not an error, so coverage is cheap insurance.
+Our Temporal plugin (private repo): **no code change expected** — its codec serializes the `dump_for_transport` dict via kajson and binds classes through the registry, so `DateContent` flows in with the pipelex version-pin bump. At pin-bump time, add a `Date` case to its converter round-trip tests anyway: the failure mode over there is a hang, not an error, so coverage is cheap insurance.
## Micro-decisions log
diff --git a/wip/inputs/smart-inputs-design.md b/wip/inputs/smart-inputs-design.md
index 9aa7bcb79..7a5ee4186 100644
--- a/wip/inputs/smart-inputs-design.md
+++ b/wip/inputs/smart-inputs-design.md
@@ -150,7 +150,7 @@ When `YesNo` lands, the D5 matrix gains a row (YesNo-refining concept + JSON `tr
### D10 — Protocol widening (MTHDS-brand surface)
-`StuffContentOrData` / `PipelineInputs` live in `mthds/protocol/pipeline_inputs.py` — MTHDS-brand, spec territory. The type must widen to admit scalars, lists of dicts, and empty lists; honestly it converges toward "any JSON value | StuffContent forms". The interpretation semantics (this design's matrix) should be spec'd on the MTHDS side (docs/specs + the mthds repo), since signature-driven reading is a property of the protocol's inputs format, not a Pipelex quirk — no `pipelex_` naming anywhere wire-visible. Downstream mirrors (mthds-python, mthds-js `PipelineInputs` types, conformance rows, JSON schema if any) sweep after the pipelex release, same de-gate pattern as Optionals/TOML-inputs.
+`StuffContentOrData` / `PipelineInputs` live in `mthds/protocol/pipeline_inputs.py` — MTHDS-brand, spec territory. The type must widen to admit scalars, lists of dicts, and empty lists; honestly it converges toward "any JSON value | StuffContent forms". The interpretation semantics (this design's matrix) should be spec'd on the MTHDS side (the protocol spec + the mthds repo), since signature-driven reading is a property of the protocol's inputs format, not a Pipelex quirk — no `pipelex_` naming anywhere wire-visible. Downstream mirrors (mthds-python, mthds-js `PipelineInputs` types, cross-repo spec-suite rows, JSON schema if any) sweep after the pipelex release, same de-gate pattern as Optionals/TOML-inputs.
### D11 — Interactions with adjacent features
diff --git a/wip/inputs/smart-inputs-implementation-plan.md b/wip/inputs/smart-inputs-implementation-plan.md
index 9ee3c6bf5..f3e35b84b 100644
--- a/wip/inputs/smart-inputs-implementation-plan.md
+++ b/wip/inputs/smart-inputs-implementation-plan.md
@@ -165,8 +165,8 @@ State: **REACHED (2026-07-08).** Smart Inputs track complete. **Docs** rewritten
Shared per-release wave with YesNo + Date (see `wip/inputs/README.md`), done once, not per-feature:
-- **D10 protocol widening** — `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` widens to admit bare scalars / lists-of-dicts / empty lists (converges to "any JSON value | StuffContent forms"), with the interpretation semantics spec'd MTHDS-side (`docs/specs/` + the `mthds` repo). Release-gated (Optionals/TOML-inputs de-gate pattern). Runtime already works; this is type-honesty for typed callers.
-- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, conformance rows, JSON schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.
+- **D10 protocol widening** — `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` widens to admit bare scalars / lists-of-dicts / empty lists (converges to "any JSON value | StuffContent forms"), with the interpretation semantics spec'd MTHDS-side (the protocol spec + the `mthds` repo). Release-gated (Optionals/TOML-inputs de-gate pattern). Runtime already works; this is type-honesty for typed callers.
+- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, cross-repo spec-suite rows, JSON schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.
- **Authoring-guidance surfaces** — `mthds-plugins` skills (`mthds-inputs`, `mthds-build`), `vscode-pipelex` completion lists, and the `ConceptSpec.refines` native-list hint (derive from `NativeConceptCode` — `refines-hint-native-list-drift.md`).
- **Off critical path** — LLM-assisted input adaptation (design §8, opt-in); the shared YesNo/Date scalar-native LLM-output ergonomics.
diff --git a/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md b/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md
index 0fdf5d253..edf4ae5d5 100644
--- a/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md
+++ b/wip/inputs/unresolvable-structure-class-escapes-the-validate-sweep.md
@@ -48,4 +48,4 @@ Migrating `_run_core.py`'s `--save-csv` step to `get_concept_library()` broke `t
The old code did not notice because `concept.get_structure_class()` read the process-global class registry, which is never unregistered at teardown — the exact wart `pipe_io_contracts.py`'s module docstring documents for its own rendering. Phase 2 resolves through `ConceptLibrary.make_empty()` instead, which reads the same process-global registry but keeps the single typed "name → `StuffContent` subclass, or `ConceptStructureClassNotFoundError`" implementation.
-That is correct for the CLI (direct execution puts generated classes in the process-global registry) but it is a lifecycle smell, not a design: a post-run step that needs the method's *declarations* is running after the method is gone. The real fix is to give `_execute_run` a result object that carries what the post-run steps need, or to hold the library window open across them — both larger than this branch. Tracked in the workspace-root `wip/library-lifecycle-hygiene.md` alongside the registry-teardown question.
+That is correct for the CLI (direct execution puts generated classes in the process-global registry) but it is a lifecycle smell, not a design: a post-run step that needs the method's *declarations* is running after the method is gone. The real fix is to give `_execute_run` a result object that carries what the post-run steps need, or to hold the library window open across them — both larger than this branch. Tracked at workspace level alongside the registry-teardown question.
diff --git a/wip/inputs/yesno-implementation-plan.md b/wip/inputs/yesno-implementation-plan.md
index a8cd4cdad..dd65156b0 100644
--- a/wip/inputs/yesno-implementation-plan.md
+++ b/wip/inputs/yesno-implementation-plan.md
@@ -86,11 +86,11 @@ State: **reached 2026-07-07.** All four phases committed on `feature/Smart-input
## Deferred to the release-wave sweep / follow-ups (NOT this plan's scope — listed so nothing is lost)
-Shared per-release wave with Datetime + Smart Inputs (see `README.md`): the Smart Inputs D5 matrix row (bare `true`/`false` against a YesNo-declared input) and D10 protocol widening (`mthds-python` `StuffContentOrData`); schema-copy sync via the `mthds-schema-sync` skill; MTHDS spec merge (drafted in Phase 4); `mthds-js` mirrors; conformance rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); vscode-pipelex completion lists; the `ConceptSpec.refines` authoring-hint native list (drifts from `NativeConceptCode` — derive it from the enum during this sweep; see `refines-hint-native-list-drift.md`).
+Shared per-release wave with Datetime + Smart Inputs (see `README.md`): the Smart Inputs D5 matrix row (bare `true`/`false` against a YesNo-declared input) and D10 protocol widening (`mthds-python` `StuffContentOrData`); schema-copy sync via the `mthds-schema-sync` skill; MTHDS spec merge (drafted in Phase 4); `mthds-js` mirrors; cross-repo spec-suite rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); vscode-pipelex completion lists; the `ConceptSpec.refines` authoring-hint native list (drifts from `NativeConceptCode` — derive it from the enum during this sweep; see `refines-hint-native-list-drift.md`).
Follow-up off the critical path (shared with Date): **LLM-output ergonomics for scalar natives** — how PipeLLM produces a `YesNo`/`Date` more leanly than the generic object path (cousin of the Optionals maybe-wrapper).
-`pipelex-temporal` (private plugin repo): no code change expected — `bool` is JSON-native and the codec binds classes through the registry. At pin-bump time, add a `YesNo` case to its converter round-trip tests anyway (the failure mode over there is a hang, not an error; coverage is cheap insurance).
+Our Temporal plugin (private repo): no code change expected — `bool` is JSON-native and the codec binds classes through the registry. At pin-bump time, add a `YesNo` case to its converter round-trip tests anyway (the failure mode over there is a hang, not an error; coverage is cheap insurance).
## Micro-decisions log
diff --git a/wip/inputs/yesno-pr-reviewers-guide.md b/wip/inputs/yesno-pr-reviewers-guide.md
index 7617afb0f..d4362e91f 100644
--- a/wip/inputs/yesno-pr-reviewers-guide.md
+++ b/wip/inputs/yesno-pr-reviewers-guide.md
@@ -31,8 +31,8 @@ The change is small and purely **additive** — it adds one native code and the
## Cross-repo (release-wave, not in this PR)
- **MTHDS spec:** the `YesNo` native-concept rows + field listing are drafted in the sibling **`mthds`** repo (`docs/language/concepts.md`, `docs/spec/mthds-format.md`) on side branch `feature/native-yes-no-concept` (not pushed). Merge vehicle is the shared release wave.
-- **Deferred to the per-release downstream sweep:** schema-copy sync (`mthds-schema-sync` skill), `mthds-js`/`mthds-python` mirrors, conformance rows, skills, editor completion lists — all shared with the Datetime + Smart Inputs tracks per `wip/inputs/README.md`.
-- **`pipelex-temporal`** (private plugin): no code change expected (`bool` is JSON-native, classes bind via the registry); add a `YesNo` converter round-trip test at pin-bump time as cheap insurance.
+- **Deferred to the per-release downstream sweep:** schema-copy sync (`mthds-schema-sync` skill), `mthds-js`/`mthds-python` mirrors, cross-repo spec-suite rows, skills, editor completion lists — all shared with the Datetime + Smart Inputs tracks per `wip/inputs/README.md`.
+- **Our Temporal plugin** (private repo): no code change expected (`bool` is JSON-native, classes bind via the registry); add a `YesNo` converter round-trip test at pin-bump time as cheap insurance.
## Breaking change
diff --git a/wip/kernel/README.md b/wip/kernel/README.md
deleted file mode 100644
index b02a6057d..000000000
--- a/wip/kernel/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Pipelex kernel — working notes
-
-Extraction of operator-execution semantics out of the interpreter's operator classes into a public, hub-free `pipelex/kernel/` subpackage, with the interpreter re-pointed onto it — zero behavior change, single-sourced semantics, callable on a `RuntimeBoot`-only process with no `.mthds` loaded.
-
-| Doc | What it holds |
-| --- | --- |
-| [`kernel-extraction-plan.md`](kernel-extraction-plan.md) | The execution plan: goal, doctrine, target API sketch, phases 0–3 with checkpoints, decisions, non-goals, gates. **Start here**; its status block is updated at every checkpoint. |
-| [`deferred-follow-ups.md`](deferred-follow-ups.md) | Items surfaced in review and deliberately kept out of this branch's scope, with pick-up-cold context. |
-| [`kernel-plugin-groups-and-distribution-plan.md`](kernel-plugin-groups-and-distribution-plan.md) | The sequel plan: the "kernel layer" naming ruling, layer-split plugin entry-point groups (Part A), and the in-repo `pipelex_kernel/` package split beside `pipelex/` (Part B, unpublished — the committed end-state). A hypothetical Part C (the published `pipelex-kernel` distribution) is sketched but requires an explicit greenlight. |
-| [`plugin-group-split-deferred-items.md`](plugin-group-split-deferred-items.md) | Items raised by the Checkpoint A review of the group split and deliberately left out of Part A, plus three open questions for Louis (the `TASK_MANAGER` tier, whether the retired-group probe should be permanent, and whether `PluginGroup` belongs in the SPI list). |
-| [`kernel-distribution-footprint.md`](kernel-distribution-footprint.md) | The B0 measurement: what the kernel package would contain, what it would require, and how big it would be — module set, cross-layer leak census, third-party dependency closure, install size. Drives B1's content line and the extras question a Part C would face. |
-| [`a2-pipelex-temporal-branch-question.md`](a2-pipelex-temporal-branch-question.md) | **RESOLVED** — which branch takes pipelex-temporal's entry-point-group migration, given its open PR #18. Kept for the rationale trail behind decision D-A2-2. |
diff --git a/wip/kernel/a2-pipelex-temporal-branch-question.md b/wip/kernel/a2-pipelex-temporal-branch-question.md
deleted file mode 100644
index 353373b27..000000000
--- a/wip/kernel/a2-pipelex-temporal-branch-question.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# A2: which branch takes pipelex-temporal's entry-point-group migration
-
-**Status: RESOLVED — Louis, 2026-08-10: base on `refactor/Topology`.** Recorded as D-A2-2 in the [plan](kernel-plugin-groups-and-distribution-plan.md#a2--as-built). Built as commit `1ed047a` on a `refactor/plugin-layer-groups` branch **stacked on** `refactor/Topology`, rather than added to PR #18 itself — that keeps #18 untouched and preserves one Part-A commit per repo, while still giving the pointer fix the base it needs. When #18 merges to `dev`, the branch retargets to `dev` cleanly. The analysis below is kept for the rationale trail.
-
-## What the commit has to contain
-
-1. `pyproject.toml` — `[project.entry-points."pipelex.plugins"]` → `[project.entry-points."pipelex.plugins.interpreter"]`. Temporal contributes an orchestrator, a bundle validator and hub-slot claims: all interpreter-layer, and after A1 a kernel-group plugin registering any of them fails loud at register time.
-2. `tests/unit/pipelex_temporal/test_temporal_plugin_http_error_mapper.py` — two `begin_plugin(...)` calls need the now-required `group=` argument.
-3. **The A0 pointer fix (D-A0-2).** `tests/unit/pipelex_temporal/test_plugin_interpreter_import_closure.py` names the core-side canonical list's file twice — its `#:` comment and its failure message — and both still say `test_runtime_layer_import_closure.py`, which A0 renamed to `test_kernel_layer_import_closure.py`. The plan deliberately parked this fix here so the repo takes exactly one Part-A commit.
-4. Changelog entry (same shape as the other two repos).
-
-## Why the base branch is not obvious
-
-`refactor/Topology` is **PR #18, still open**. It is ahead of `dev` and not behind it, and it is where the "Keep the interpreter out of an import-light register, and gate it" commit lives — the fix that closed the 104→0 contamination, and the commit that *introduced* `test_plugin_interpreter_import_closure.py`.
-
-That file **does not exist on `dev`** (`git cat-file -e dev:…` fails).
-
-So:
-
-| Base | Consequence |
-| --- | --- |
-| `dev` | Item 3 is impossible — the file is not there. The stale pointer then arrives on `dev` the moment #18 merges, and nobody is watching for it. Items 1, 2 and 4 land cleanly. |
-| `refactor/Topology` | All four items land. But a kernel-track commit now sits on an unmerged branch from the Temporal-topology track, so Part A's plugin migration can only ship when #18 ships. Two release trains coupled. |
-| Both (split the commit) | Items 1/2/4 on a `dev`-based branch, item 3 folded into #18 itself. Costs the "exactly one Part-A commit per repo" property that D-A0-2 was written to preserve, and touches someone else's open PR. |
-
-## What is not in question
-
-- The migration itself: Temporal is interpreter-layer, no ambiguity.
-- The release gate: whichever branch takes it, the commit is not pushable until the pipelex release carrying layer-split discovery exists, because CI would install released pipelex (which reads only the retired group) and go red. The pipelex pin floor bump is owed in the same window.
-
-## Recommendation
-
-Base on `refactor/Topology` **if #18 is expected to merge before the pipelex release that carries Part A** — which is likely, since the A2 commit is release-gated anyway and cannot ship first. The entanglement is then only nominal: both land in the same window regardless. If #18 is expected to sit open for a while, prefer the split, and accept that D-A0-2's one-commit property was the weaker constraint.
diff --git a/wip/kernel/deferred-follow-ups.md b/wip/kernel/deferred-follow-ups.md
deleted file mode 100644
index d97d6984f..000000000
--- a/wip/kernel/deferred-follow-ups.md
+++ /dev/null
@@ -1,223 +0,0 @@
-# Kernel extraction — deferred follow-ups
-
-Items surfaced during the plan's engineering review that are deliberately **not** in this branch's scope. Each carries enough context to pick up cold, and stays here once resolved elsewhere — marked done, rewritten to say what actually landed and what it changes for the plan.
-
-## ✅ KF-1 — Tree-wide mechanical ban on importing from `pipelex.exceptions` in runtime-layer packages — DONE
-
-**What landed.** Done on `dev` (#1080) and merged into this branch — and it went in *tree-wide first* rather than kernel-first, which inverts the dependency this item recorded. `tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py` AST-walks every package declared in `RUNTIME_LAYER_PACKAGES` and fails on any reference to the aggregate: module-level or function-local, absolute or relative, plus any bare string naming it — the `import_module` / `__import__` / `mocker.patch` shape, which no import node records and which this item had not asked for. The feared sweep was empty (the vendor-adapter cleanup had already fixed the only violators), so the gate hard-blocks from day one; the scoping decision came out as predicted — the aggregate stays a legitimate public surface *outside* the runtime layer, and only the layer whose closure it would silently widen is banned. `docs/contribute/hub-layering.md`'s aggregate section now states the rule as mechanical rather than prose.
-
-**What it changes for this branch.** The gate's domain *is* `RUNTIME_LAYER_PACKAGES`, so task 0.1a's declaration of `pipelex.kernel` puts the kernel under it with no kernel-specific test to write — which is why task 0.1c shrank to its prose half. Its negative control survives with a different job: the gate resolves each declared entry to files and silently yields nothing when the path does not resolve, so a mis-declared package is covered by *zero* modules without complaining. That is the "an undeclared package is unpoliced" hazard in a new shape, and the control is what proves the declaration actually bought coverage.
-
-## KF-2 — A library-free caller has no way to mint a `Concept` for its own class
-
-**Surfaced by** writing task 1.7's tests. `llm_object` takes a `concept: Concept` alongside `output_class`, which is the right shape — the kernel must not do a registry hop. But on a process with zero `.mthds` loaded, the only concept a caller can build through a public factory is a native one (`ConceptFactory.make_native_concept`), because everything else resolves through a loaded library. So a caller handing over its own `StuffContent` subclass pairs it with `Native.Anything`, which is what both the unit tests and the boot-contract test do.
-
-**Why it is not a bug today.** For a kernel-only caller the concept is metadata on the produced `Stuff`; nothing in the LLM kernel ops reads it, and nothing answers a compatibility question about it (see the 0.1e vacuity deviation in the plan). The pairing is *loose*, not wrong.
-
-**Why it is deferred rather than fixed here.** The fix is a caller-facing memory-boundary concern, and Phase 3 is where that boundary gets shaped for real (3.1 `shape_inputs`, 3.2 result extraction). Adding a concept-minting factory in Phase 1 would be designing that surface from one test's convenience rather than from the caller experience Phase 3 defines. Revisit at 3.2: if result extraction stays typed on the class, this may need nothing at all; if it keys on concepts, a library-free minting path becomes load-bearing and should be designed then.
-
-**Phase-3 verdict: nothing is owed, and the deferral was right.** Result extraction stayed typed on the class — `extract_main_content` / `extract_named_content` take a `content_type`, never a concept — so no kernel *read* path asks a concept question, and the branch KF-2 was watching for ("if it keys on concepts") did not happen. The input side turned out to have a shape the item did not anticipate: `shape_inputs` takes a `ConceptProviderAbstract` explicitly, so a library-free caller supplies its own, and `test_kernel_boot_contract.py` now carries the smallest one that works (native concepts from `ConceptFactory`, compatibility from `Concept.are_compatible_by_declaration`, structure classes from the class registry a boot fills). That is a *provider*, not a concept-minting factory — a caller wanting a genuinely non-native concept for its own class still has to declare one, which is what an author writing `.mthds` does. Nothing in the kernel needs it, so nothing is built. Revisit only if a kernel path ever answers a compatibility question about a caller's own concept, which the 0.1e routing rule would then govern.
-
-## KF-3 — `LLMPromptBlueprint.make_llm_prompt` is now production-dead, held up entirely by its tests
-
-**Surfaced by** the Checkpoint-A cold review, which reported the narrower symptom: the `log.verbose(f"User text with {output_concept_ref=}:\n {user_text}")` diagnostic inside it no longer fires on a live run. That is true, but it is a consequence, not the finding. Verified the real shape: `make_llm_prompt` is defined at `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:63` and called from **tests only** — 38 call sites across `tests/integration/pipelex/pipes/llm_prompt_inputs/` and `tests/unit/pipelex/pipe_operators/pipe_llm/`, and zero in `pipelex/`. The re-point is what killed it: `PipeLLM._live_run_operator_pipe` now calls `to_prompt_content()` and hands that to the kernel, so the blueprint's own assembly method is bypassed.
-
-**Why it is not a bug today.** The method still works and its tests still pass — they are simply testing a path production no longer takes. The equivalent production path is `LlmPromptContent` in the kernel, which those same behaviors are exercised through by the re-pointed interpreter suite. So there is no coverage cliff, only a duplicate.
-
-**Why it is deferred rather than fixed here.** Two reasons, and the second is the load-bearing one. First, deleting a method plus re-homing 38 test call sites is a substantial change inside a PR whose contract is *zero behavior change* — it would make the diff much harder to read against exactly the claim reviewers need to check. Second, and more importantly, **Phase 2 decides the question for us**: `LLMPromptBlueprint` is still a live field on `PipeLLM` (`llm_prompt_spec`, which the operator reads through `to_prompt_content()`), and the img-gen blueprint shares its reference-extraction shape, so what remains of the blueprint after every operator is re-pointed is not knowable yet. Deleting now risks deleting the wrong half. Revisit at the end of Phase 2, when the blueprint's surviving role is settled: at that point either the method is genuinely dead and goes (with its tests re-pointed at `LlmPromptContent`), or it has re-acquired a caller and stays.
-
-**Scope note, because this item is about a method and not a class.** What is production-dead is `make_llm_prompt`, the assembly method — *not* `LLMPromptBlueprint` itself, which `PipeLLM` holds as a field and which parse-and-validate still needs. An earlier revision of this paragraph named `PipeStructure` as the blueprint's remaining consumer. That was never true on any branch, including `dev` before this work: `pipe_structure.py` has never referenced `LLMPromptBlueprint`. Whoever picks this up should look at `PipeLLM`, and should be deleting one method, not a model.
-
-**Scheduling note after Phase 3.** Its trigger — "the end of Phase 2, when the blueprint's surviving role is settled" — passed unexercised, and Phase 3 touches neither the blueprint nor its tests, so nothing schedules this now. The blueprint's role *is* settled (Phase 2 moved no prompt assembly onto it, and `PipeLLM` still holds it as `llm_prompt_spec`), so the question is answerable: `make_llm_prompt` is genuinely dead in production and its tests belong on `LlmPromptContent`, while the blueprint model itself stays. Do it in the same standalone tidy as KF-4, after this series lands — both are mechanical, both are cheaper once no PR is claiming a verbatim move.
-
-**If the diagnostic itself is wanted back sooner** — independent of the above — it is a one-line addition in `run_llm_text`/`run_llm_object` in `pipelex/kernel/llm_ops.py`. It was dropped deliberately (recorded under the plan's Deviations: moving it meant either duplicating it or carrying a log-only parameter across the layer boundary), and no one has asked for it; the kernel would log without the `output_concept_ref` the old line carried, since the text arm has no concept ref to name.
-
-## KF-4 — Two `TestClass`es per module in the moved reference-type tests
-
-**Surfaced by** the Checkpoint-A cold review. `tests/unit/pipelex/kernel/test_document_reference.py` holds both `TestDocumentReference` and `TestDocumentReferenceKind`; `test_image_reference.py` has the analogous split. The repo's pytest standards say, twice and in caps, never to put more than one `TestClass` in a module.
-
-**Why it is deferred rather than fixed here.** It is pre-existing — both files moved at 97% similarity with only the import line changed, so the violation was inherited, not introduced. And fixing it *now* has a specific cost that will not apply later: splitting each file into two destroys git's rename detection, turning a reviewable "this moved verbatim" into a delete-plus-add in a PR whose entire claim is that the move is behavior-preserving. That is a bad trade in this PR and a free change in any later one. Do it as a standalone tidy after this series lands — it is mechanical, and `.test_durations` will need the same node-id sweep the plan already records for Phase 2 moves.
-
-## KF-5 — What kernel results do at a serialization boundary is a Phase-3 question
-
-**Surfaced by** Codex on PR #1081, as a P1 against `LlmObjectResult.content`: the field is annotated with the base `StuffContent`, so pydantic v2 serializes it by the annotation and a `NumberContent(number=3)` dumps as `{}`.
-
-**The behavior is real; the framing as a new defect is not.** Verified empirically, and the decisive comparison is `Stuff.content` — the codebase's canonical polymorphic content holder, annotated identically, and the one that genuinely crosses Temporal boundaries today:
-
-```
-Stuff.content plain model_dump : {}
-Stuff.content serialize_as_any : {'number': 3}
-Stuff kajson round-trip type : NumberContent 3
-```
-
-So the kernel result is behaving exactly like the type it mirrors, and the project's answer at both sites is already in place: `kajson` (which records the class and reconstructs it) is what actually crosses process boundaries, and `model_dump(serialize_as_any=True)` covers a one-off dump. There are **zero** `SerializeAsAny` annotations in the tree — adding one here alone would introduce a pattern that exists nowhere else and would make the kernel result inconsistent with `Stuff`.
-
-**Why nothing is changed beyond a docstring.** Nothing serializes `LlmObjectResult` or `LlmTextResult` today: they are built in `llm_ops.py` and unwrapped inline by `PipeLLM`/`PipeStructure`, and there is no `model_dump`/`kajson` call anywhere in `pipelex/kernel/`. Fixing a corruption on a path no caller takes is guarding an impossible scenario. What *was* added is a note in the module docstring, because the kernel is aimed at programmatic callers and "call `model_dump()` on the result you were handed" is a plausible caller mistake in a way it is not for an internal type.
-
-**When it becomes real.** Phase 3 shapes the caller-facing boundary (3.1 `shape_inputs`, 3.2 result extraction). If kernel results are ever handed across a process, API or cache boundary there, this is the moment to decide deliberately — and the answer should almost certainly be "serialize with `kajson`, like everything else that crosses", not a bespoke annotation on one field. Revisit at 3.2 alongside KF-2, which is the same boundary seen from the input side.
-
-**Phase-3 verdict: unchanged, because 3.2 read the results in-process.** `extract_main_content` / `extract_named_content` narrow a result's content by type on the caller's own stack; nothing in Phase 3 dumps or transports a kernel result, so the path this describes still has no caller. The docstring note stays as the caller-facing warning it was. The trigger is now genuinely external — the first time a host hands a kernel result across a process, API or cache boundary — rather than a phase of this plan.
-
-## ✅ KF-6 — `StructuringPath` owns three quarters of the tracer's `structuring_path` vocabulary — SETTLED IN PHASE 3
-
-**Surfaced by** the PR #1081 arbitration pass, reviewing the re-pointed operators for behavior parity. `StructuringPath`'s docstring calls itself "the tracer's vocabulary, owned here rather than at each caller", but `PipeStructure` writes a bare `"structure"` into the same `execution_data["structuring_path"]` key (`pipelex/pipe_operators/structure/pipe_structure.py:172`), and that value has no enum member. So the key the tracer consumes is fed from an enum on one path and a string literal on another.
-
-**Why it is not a bug today.** The literal is pre-existing — it read `"structure"` on `dev` too, and this branch did not touch it. The consumer chain is `dict[str, Any]` end to end (`_register_execution_data` → `GraphTracerManager.register_execution_data` → `node_data.execution_data`), and `StructuringPath` is a `StrEnum`, so both forms serialize to the same JSON string and nothing downstream can tell them apart. Verified: no test data, snapshot or renderer keys on the value.
-
-**Scheduling note — this has no trigger unless one is added.** An earlier draft said "when Phase 2 re-points `PipeStructure` fully, the answer falls out". Phase 2's task list (2.1–2.5) has no `PipeStructure` task, and the plan's own Deviations argue *against* routing it through `run_llm_object`. So nothing currently schedules this. Fold it into whichever Phase-2 task touches `PipeStructure`'s execution data, or settle it at Phase 3 when the kernel docs page has to describe the vocabulary. Extra evidence for leaving the value alone: our graph UI removed its Structuring row on the grounds that `structuring_path` never carried information, so no renderer branches on it in any repo.
-
-**Why it was deferred rather than fixed then.** The right fix depended on a question Phase 2 answers: is `"structure"` a *fourth kernel structuring path*, or a pipe-level label that merely shares a dict key? Either it starts flowing through a kernel entry point that legitimately returns a fourth path (add the member, drop the literal), or it stays a caller-side label (narrow the enum's docstring to say it names the *LLM* paths, not the whole key). Cheap either way; wrong to guess before the answer was in.
-
-**What landed (Phase 3).** The second arm, because Phase 2 settled the premise: its Deviations record `PipeStructure` riding the kernel's *pieces* rather than `run_llm_object`, so it calls `generate_object_content` and builds its own execution data — no kernel op can return `"structure"`, and adding the member would put a value into a "what the kernel op did" type that nothing here produces. `StructuringPath`'s docstring now says it names the LLM paths and states why the sibling literal has no member. The literal in `pipe_structure.py` is untouched: the key is `dict[str, Any]` end to end, `StructuringPath` is a `StrEnum`, and nothing downstream can tell the two forms apart — our graph UI removed its Structuring row precisely because the value never carried information.
-
-## KF-7 — `PipeCompose`'s construct mode is not kernel-covered, and covering it means relocating an MTHDS blueprint
-
-**Surfaced by** task 2.4 itself. The task read "kernel templating + structured-composition ops"; only the templating half landed.
-
-**Why the construct half did not.** Its semantics are `StructuredContentComposer` over a `ConstructBlueprint`, both under `pipelex/pipe_operators/compose/` — an interpreter package by the closure test's own `INTERPRETER_PACKAGES` predicate, so the kernel cannot import either. There is no adapter shape that avoids this: the composer's *input* is the blueprint. Covering construct mode therefore means moving `construct_blueprint.py` (315 lines of MTHDS field-composition model, with its serializers and validators) and `structured_content_composer.py` (840 lines) into `pipelex/kernel/`, plus the `PipeComposeError` family they raise — which is a `PipelexError` subtree, so it drags `make generate-error-pages` and the `tests/data/errors/error_identity.txt` snapshot with it.
-
-Phase 1's `LLMPromptBlueprint` precedent looks like it points the other way, and does not: there the kernel needed a *small* runtime-layer input model (`LlmPromptContent`) that the blueprint maps down onto. The equivalent here is a near-verbatim second copy of a 315-line blueprint, which is duplication, not layering.
-
-**What the caller loses.** Close to nothing. A programmatic caller holds real Python — it builds its structured object directly rather than describing the construction in a blueprint. The blueprint exists so that `.mthds` can express composition declaratively, which is a language concern with a language-side consumer.
-
-**What was done instead.** The one thing genuinely shared between the two paths — the three-layer context ordering (memory stuffs → run params → step `extra_context`) that both the template path and the construct path's TEMPLATE fields render against — is now single-sourced in `build_compose_context` and called from both. That is the drift this extraction exists to kill; the rest of construct mode was never at risk of forking, because it has exactly one caller.
-
-**When to revisit.** If a second caller of construct-mode composition ever appears, or if `pipelex/kernel/` is packaged as a standalone distribution (a stated non-goal today) and the MTHDS blueprint models get a layer verdict of their own. Note the precedent that would support the move when it comes: `TemplateBlueprint` is also a `.mthds`-parsed artifact and already lives in the runtime layer, under `pipelex/cogt/templating/`.
-
-## KF-8 — `PipeFunc`'s executor seam is not kernel-carried, so a kernel `run_func` always runs in this process
-
-**Surfaced by** task 2.5 itself. The task read "kernel function-call op over the `PipeFuncExecutorProtocol` seam ... the kernel op must carry **both arms**"; the call and the write-back landed, the seam did not.
-
-**Why the seam did not.** Neither arm's type survives the layer boundary. `PipeFuncExecutorProtocol.run_pipe_func` declares `pipe_run_params: PipeRunParams` and `run_pipe_func_transported` is typed on `PipeFuncExecutionRequest`, which carries a `LibraryCrate`. `pipe_run` and `libraries` are both interpreter packages, and the task's own analysis rules out moving those two models as far outside Phase 2. So the kernel cannot name the protocol it was told to take as an argument.
-
-**The two ways to satisfy the letter, and why neither was taken.**
-
-- *Re-type the protocol off `PipeRunParams`.* Cheap in this tree — nothing in it reads the parameter, including `DirectPipeFuncExecutor` — but it is not a cleanup, it is a wire-format change: both out-of-tree implementers (our Daytona sandbox plugin and our Temporal plugin) thread `pipe_run_params` straight onto `PipeFuncExecutionRequest`, which crosses a process boundary. Two repos this tree's CI cannot see would break at the same time, and the honest first question — *does anything downstream ever read it?* — is not answerable from here.
-- *A kernel-side narrow protocol plus an interpreter-side adapter.* Buys a second protocol for one seam, an adapter class binding `pipe_run_params`, and a result-model conversion at the boundary — to compose two calls. Against a "no over-engineering" bar that is the more expensive of the two, not the safer one.
-
-**What was done instead.** The split follows what is actually shared. `call_registered_function` holds what running a function *means* — registry lookup, async-vs-sync dispatch, the str/list→`StuffContent` coercion — and both the in-process executor and the kernel's own `run_func` ride it, so the executor and a programmatic caller cannot fork on it. `store_result` holds the write-back, which `PipeFunc` now rides too. What stays interpreter-side is *where the function runs*, which is configured deployment machinery rather than operator semantics.
-
-**What the caller loses, stated plainly.** A programmatic caller cannot ask the kernel to run its function in a sandbox: `run_func` is the in-process path, full stop. And `run_func` has no in-tree caller — `PipeFunc` rides the pieces, not the composition — which is why it carries its own kernel unit tests rather than leaning on the zero-behavior-change suite.
-
-**When to revisit.** Whenever `pipe_run_params` on the executor seam is settled on its own merits — the question is whether a serialized PipeFunc request needs the run params at all, and it wants an answer coordinated across the three repos, not a drive-by narrowing here. Phase 3's `JobMetadata` task (3.3) is the natural moment: it is already the task that asks what run-scoped state a kernel call carries, and this is the same question asked at the one seam that serializes it.
-
-**Phase-3 verdict: still deferred, and 3.3 sharpened the argument rather than answering it.** 3.3 settled what run-scoped state a kernel call carries — a per-step `JobMetadata` (identity plus an optional `TraceContext`) and a `CogtRunParams`, and *not* a `PipeRunParams`. That is a point in favour of narrowing the executor protocol, since the pipe-tier params on it are the one thing the kernel could never supply — but it does not answer the question the narrowing rests on ("does anything downstream read them?"), which is only answerable from the two out-of-tree implementers. Unchanged: this is a cross-repo wire-format decision, not a kernel one. The trigger is a coordinated pass over pipelex + our Daytona and Temporal plugins.
-
-## KF-9 — Two constructors build `ImgGenJobParams` from the same config defaults with different derivation rules
-
-**Surfaced by** cubic on PR #1082, against `build_img_gen_job_params` in `pipelex/kernel/img_gen_ops.py`: a transparent background with no step-level `output_format` builds params that fail `ImgGenJobParams.validate_background_vs_output_format`.
-
-**The asymmetry is real.** `ImgGenJobParamsDefaults.make_img_gen_job_params` (`pipelex/cogt/img_gen/img_gen_job_components.py`) derives `output_format = ImageFormat.PNG` when `self.background.is_certainly_transparent`; the kernel's `build_img_gen_job_params` passes `output_format` straight through. Both read the same `img_gen_param_defaults`, and both are live — the defaults constructor is the fallback in `content_generator.py` and `img_gen_job_factory.py`.
-
-**Why it is not a regression.** The pre-refactor `PipeImgGen._live_run_operator_pipe` constructed `ImgGenJobParams(...)` inline with the identical `output_format=self.output_format`; the operator path never went through `make_img_gen_job_params`. Verified against `git show refactor/Kernel:pipelex/pipe_operators/img_gen/pipe_img_gen.py`. The behavior moved unchanged.
-
-**Reachability.** The shipped default is `background = "auto"`, so it does not fire out of the box. It fires under a `.pipelex/pipelex.toml` override of `[cogt.img_gen_config.img_gen_param_defaults] background = "transparent"`, which would then break every `PipeImgGen` that omits `output_format`. Note the same failure is already reachable today with no config override at all, via a step-level `background = "transparent"` with no `output_format` — so a fix confined to the config path would not close the case.
-
-**Why it is deferred rather than fixed here.** Re-deriving PNG inside `build_img_gen_job_params` would make a currently-failing configuration start working — a behavior change inside a zero-behavior-change PR — and it is the wrong-shaped fix. The defect is that *two* constructors of the same type read the same defaults with divergent rules, which is precisely the duplication this extraction exists to kill. Single-source them; do not patch one side. Failure today is loud and well-worded, not silent corruption, so nothing is at risk in the meantime.
-
-## KF-10 — `max_results` reaches a provider unvalidated because the constraint sits on the wrong model
-
-**Surfaced by** cubic on PR #1082, against `resolve_search_setting` in `pipelex/kernel/search_ops.py`: `search_setting.model_copy(update={"max_results": max_results_override})` skips validation, because pydantic v2's `model_copy` does no validation by design.
-
-**The chain is genuinely unconstrained end to end.** `PipeSearchBlueprint.max_results` is `int | None = None` with no `ge`; `PipeSearchFactory.make` passes it through to `PipeSearch.max_results_override`, also unconstrained; only `SearchSetting.max_results` carries `Field(default=None, ge=1)`, and the `model_copy` is what bypasses it. So `max_results = 0` in a `.mthds` reaches a search provider.
-
-**Why it is not a regression.** Identical on the base branch, step 4 of `PipeSearch._live_run_operator_pipe`. Verified against `git show refactor/Kernel:pipelex/pipe_operators/search/pipe_search.py`.
-
-**Why it is deferred rather than fixed here, and why the obvious fix is the wrong one.** Revalidating the copy (the bot's suggestion) would raise a pydantic `ValidationError` deep inside the search run path, with no `.mthds` locator to tell the author which step is wrong — trading an unvalidated value for a bad diagnostic. The constraint belongs on `PipeSearchBlueprint.max_results` as `Field(default=None, ge=1)`, where it is caught at validation time with a proper error. That changes the MTHDS JSON Schema and drags the committed downstream copies (`mthds/`, `vscode-pipelex/`, `mthds-ui/`) with it, which is unambiguously outside a zero-behavior-change refactor. Do it as a standalone language-surface change with the schema regeneration and the cross-repo sweep in the same PR.
-
-**Phase-3 verdict (shared with KF-12): the conclusion holds, and 3.1 did not turn out to be its home.** Both items were scheduled onto task 3.1 as "the task that decides what a kernel entry point does with a malformed argument". 3.1 answered that for what it actually governs — the *memory* boundary — and the answer is: reject at the boundary with a typed error that names the variable and renders the expected shape, which is what `InputShaper` already does and what `shape_inputs` now hands both callers. Neither `max_results` nor `nb_images` passes through that boundary: they are operator arguments, not memory inputs, so 3.1 has no reach over them. The conclusion both items had already reached is unchanged, and nothing in this plan blocks it any longer — the constraint belongs upstream on the blueprint, caught at validation time with a locator, in one standalone language-surface PR that carries the schema regeneration and the cross-repo sweep.
-
-## KF-11 — `PipeImgGen`'s `seed` is documented language surface that no image-generation provider reads
-
-**Surfaced by** verifying cubic's P2 against `build_img_gen_job_params`, which reported that `seed or img_gen_param_defaults.seed` discarded an explicit `0`. That part was true and is **fixed in PR #1082** — the line now reads `seed if seed is not None else …`, matching the `is_raw` line below it. The larger fact came out of checking the claimed impact.
-
-**The seed is inert.** `seed` is a declared `PipeImgGen` blueprint field (therefore in the published MTHDS JSON Schema), it is validated (`ImgGenJobParams.seed`, `ge=0`), and it is composed into `ImgGenJobParams` on every image-generation run — and no img-gen worker reads it. Grepping `job_params.seed` across every worker under `pipelex/providers/*/` finds exactly one image-generation reference, and it is commented out: `pipelex/providers/google/google_img_gen_worker.py`. (The live hits are all `LLMJobParams.seed`, a different field on a different job type.) Which is why the `0` fix is observationally a no-op and does not dent the PR's zero-behavior-change claim.
-
-**The failure a user hits.** They write `seed = 12345` in a `PipeImgGen` step to reproduce an image, run it twice, and get two different images — no error, no warning, nothing indicating the parameter was discarded.
-
-**Why it is deferred rather than fixed here.** It is pre-existing, entirely outside the kernel extraction, and the fix is per-provider plumbing (each SDK spells the seed differently, and not all of them accept one) plus a decision about what to do for backends that cannot honor it — reject at validation, or document the field as best-effort. Both are product calls. Recorded here because this is where it was found; it belongs in the img-gen backlog rather than the kernel one.
-
-## KF-12 — `run_img_gen` treats a non-positive `nb_images` as one image, and what it *should* do is a Phase-3 question
-
-**Surfaced by** Codex on PR #1082 (P2): `nb_images=0` or a negative count falls through the `if nb_images > 1:` fork to `make_single_image`, so an invalid request generates one billable image instead of being rejected.
-
-**Why it is not a regression.** The fork is byte-identical to the base branch — `git show refactor/Kernel:pipelex/pipe_operators/img_gen/pipe_img_gen.py` has the same `if nb_images > 1:` at line 268, with the same `make_image_list` / `make_single_image` arms. The multiplicity derivation above it also moved unchanged: `nb_images = applied_output_multiplicity` whenever that is an `int`, with no lower bound anywhere on the way in.
-
-**Why it is deferred rather than fixed here, and this one is genuine doubt rather than scope.** There is no zero-behavior-change fix available. Unlike the `run_search` signature narrowing in this PR — where the ignorable fields could simply be removed from the signature — `nb_images` is an `int` and plain Python cannot express `int >= 1` at the boundary, so any fix *adds an error path* to a PR whose contract is that it adds none. And the fix's shape is not obvious: `nb_images=0` could defensibly mean "reject this request" or "produce an empty `ListContent`", and picking between them from a bot comment rather than from the caller experience is exactly the mistake KF-2 records. Phase 3's task 3.1 (`shape_inputs`) is the task that decides what a kernel entry point does with a malformed argument; settle it there, for all the ops at once, rather than one `int` at a time.
-
-**Worth noting on the way.** The interpreter path can reach it too — nothing between a `.mthds` `nb_output` and `nb_images` constrains the value — so if the answer turns out to be "reject", the constraint most likely belongs upstream on the blueprint, the same conclusion KF-10 reaches about `max_results`. The two should be settled together.
-
-**Phase-3 verdict: see KF-10.** 3.1 settled the malformed-argument question for the memory boundary only, which `nb_images` does not cross. Both items stay together, and their shared home is the standalone blueprint-constraint PR described there.
-
-## KF-13 — a DRY run's usage records carry no `pipe_code`, so a `--mock-usage` cost report has no pipe attribution
-
-**Surfaced by** writing task 3.3's parity test, which expected `pipe_code` to be the one field an interpreter run fills and a kernel run cannot. It is not filled on either side, and the reason is on the interpreter's side.
-
-**The gap.** `pipe_code` reaches a usage record through `JobMetadata`, and the only place it is stamped is `PipeAbstract.live_run_pipe`, which mints the child metadata with `pipe_code=self.code`. A `run_mode=DRY` run never reaches it — `_run_pipe_traced` matches on the run mode and routes to `dry_run_pipe`, which passes the metadata down untouched. So every usage record a dry run produces has `pipe_code=None`, and a `--dry-run --mock-usage` cost report attributes nothing to a pipe.
-
-**Why it is not urgent.** It bites only the mock-usage cost report, which exists to validate cross-worker cost-report *rendering* cheaply — the numbers are synthetic either way. A LIVE run, where attribution matters and money is real, stamps it correctly. Nothing silently misattributes; the field is simply absent.
-
-**Why it is deferred rather than fixed here.** It is pre-existing, entirely interpreter-side, and untouched by the kernel extraction — verified on the base branch, where `dry_run_pipe` has the same shape. Fixing it means moving (or duplicating) the child-metadata mint above the LIVE/DRY fork in `_run_pipe_traced`, which changes what every dry run's metadata carries: a behavior change inside a zero-behavior-change PR, on a path the graph tracer also reads. It belongs with whoever next works on the dry-run observability surface. The parity test pins the current reality on both sides so the fix will show up there as a diff rather than as a silent divergence.
-
-## KF-14 — `UsageReportEvent.node_id` has no readers, which is why a kernel run's flat node state is not a bug yet
-
-**Surfaced by** cubic on PR #1083 (P2), which argued that `PipelexKernel.make_step_metadata` inherits the run-level `TraceContext` unchanged, so every step of a multi-call kernel run carries `node_sequence=0` and `parent_node_id=None` — and concluded that a multi-step run's usage records would collide onto one node. The cold `/code-review` raised the same point independently.
-
-**Rejected as a code change, on measurement.** Two kernel LLM calls under one `TraceContext` produce two events and two records with the correct token total, on both emit paths (the registered-context fast path and the runner fallback). Nothing collides, because nothing on that path keys on the node: the event log's dedup key is `(workflow_id, writer_id, event type, sequence)` with `sequence` coming from a lock-guarded per-log counter, `UsageAggregator.aggregate` is a flat filter-and-map with no grouping, and `TokensUsageRecord` has no `node_id` field at all — so it never reaches `/execute`'s `tokens_usages` or `tokens_usages.json`.
-
-**The fact worth recording, because it is what makes the whole class of finding moot.** `UsageReportEvent.node_id` has no *production* reader. The only other consumer of `UsageReportEvent` in the tree is `GraphSpecAssembler`, which matches it and does nothing (`pass # Handled by UsageAggregator`); across the sibling repos, the sole non-test hits declare the type or list it in an ignore tuple. Two tests do read it — `tests/unit/pipelex/reporting/test_reporting_event_emission.py` asserts both the `"unknown"` fallback and a supplied `graph:node_42` — which strengthens rather than weakens the point: the first of those is the existing pin on exactly the behavior this item defends. A kernel run also emits no graph events — the graph tracer is interpreter-side and a leaf call does not pass through it — so the field's value is unobservable from a kernel call by any route available today.
-
-**Why advancing the sequence would be worse than leaving it.** A kernel run has no graph. `"unknown"` states that honestly; minting `graph_id:node_0`, `graph_id:node_1` would manufacture references to nodes that exist in no `GraphSpec`, and put them into a field nothing reads. Two of cubic's supporting mechanisms were also wrong on inspection: `copy_with_update` applies its update values by reference *after* the deep copy rather than deep-copying them, and `make_node_id()` is never called on the usage path at all.
-
-**What would reopen it.** Node identity becomes load-bearing the moment something reads it — graph-shaped tracing extended to kernel runs, or a consumer that groups usage events by node. At that point the answer is not a per-step sequence invented by the kernel but a decision about what a node *means* for a caller that has no graph, and it should be settled alongside whoever introduces the reader.
-
-## KF-15 — `Stuff.as_list_of_fixed_content_type` documents an exception it does not raise
-
-**Surfaced by** wiring the kernel's list-extraction helpers onto it, which meant reading what it actually raises in order to write their own `Raises:` sections honestly.
-
-**The gap.** Its docstring documents `Raises: TypeError` (`pipelex/core/stuffs/stuff.py`). It raises `StuffContentTypeError`, via `content_as` and `verify_content_type`, like every other typed accessor on `Stuff`. A caller who writes `except TypeError` around it catches nothing — `StuffContentTypeError` descends from `StuffError`, not from `TypeError`.
-
-**Why it is deferred rather than fixed here.** Pre-existing, one line, and in `pipelex/core/stuffs/` rather than on the kernel surface this PR is scoped to. Worth folding into whatever next touches those accessors; the same pass should check the sibling docstrings in that module for the same error, since this one was found by reading a single function rather than by sweeping.
-
-## KF-16 — The model-derived prompting style is obsolete and should become an explicit choice
-
-**Numbered 16, not 7, deliberately.** This item lands on the *first* PR of a three-PR stack, but the stacked Phase 2 and Phase 3 PRs already add KF-7 through KF-15. Taking the next free number instead of the next sequential one keeps every one of those entries — and the cross-references to them in the plan — exactly as written, so folding this in churns neither of the PRs above it. The gap below is theirs to fill.
-
-**Surfaced by** folding the parity-gaps track's Phase 2 into this stack. That plan listed a gap 2.2 — *"`PipelexKernel.llm_object` renders under the wrong model's prompting style"* — and called it a wrong value. **Re-verified against this branch: that was overstated, and nothing here is broken.**
-
-The façade takes one explicit `model`, which wins `resolve_llm_setting_for_object`'s first rung, so the style is derived from that same setting. That is what an interpreted run derives for a pipe naming only a text model. The two agree for every call this form can express; the divergence needs a pipe naming *both* models, which the façade has no way to say. So 2.2 is the same **narrowness** as the `llm_text` widening that did land here — not a defect.
-
-**Why it is deferred rather than widened.** Giving `llm_object` a second model choice means building the two-setting derivation that the whole mechanism is slated to lose. The owner's call (2026-08-03): deriving the prompting style from the model dates from when models were genuinely sensitive to prompt shape, which no longer holds. The target is an **explicit caller/author-chosen style defaulting to XML**, with the model-derived path removed — which deletes the derivation outright rather than teaching another caller to reproduce it.
-
-**Where the work is written up.** `wip/prompting-style/README.md` — current mechanism, why it goes, target design, open questions (where the choice lives, what happens to `prompting_target`, whether it needs an MTHDS surface and therefore an `mthds/` spec change), and the measured three-case table behind the "not a defect" verdict.
-
-**Recorded in code** as a docstring block on `PipelexKernel.llm_object`, carrying the trap: do *not* "fix" this by deriving the style from an object-only resolution — that would introduce the divergence rather than close it.
-
-## KF-17 — An empty-string model choice falls through to the deck default instead of failing
-
-**Surfaced by** cubic on PR #1081, against `resolve_llm_setting_for_text` / `resolve_llm_setting_for_object` in `pipelex/kernel/llm_ops.py`.
-
-**The gap.** Both resolvers pick the first choice by truthiness — `llm_choice or model_deck.llm_choice_overrides.for_text or model_deck.llm_choice_defaults.for_text`. The parameter is typed `LLMModelChoice | None`, so `is not None` is the check the type describes. The two differ for exactly one value: `""` is falsy, so `llm_text(model="")` runs against the deck default rather than raising.
-
-**Why it is deferred rather than fixed here.** Three reasons, and the first is decisive.
-
-- **It is not this PR's code.** The chain is verbatim what `pipe_llm.py` has on `dev` (`llm_for_text_choice or model_deck.llm_choice_overrides.for_text or …`). The extraction moved it; it did not write it.
-- **There is no divergence.** The interpreter now calls these very functions, so both readers resolve identically by construction. Changing the rung would change both together — this is not a parity gap, which is the bar the surrounding track set.
-- **Every authored path already rejects it.** `""` reaches a resolver only from a direct Python call. Through pydantic — which is how a `.mthds` model choice, a deck default, and a deck override all arrive — the `parse_model_reference` validator raises `ModelReferenceParseError: Model reference cannot be empty`. The remaining hole is `PipelexKernel.llm_text(model="")` in hand-written code.
-
-**What settling it would take.** Not a one-line swap: the object resolver has three rungs, and a faithful `is not None` version of a mixed None/falsy chain reads considerably worse than the `or` it replaces. Worth doing as part of a deliberate pass over model-choice validation — where the real question is whether `LLMModelChoice` should reject `""` at the type boundary once, instead of every consumer re-checking — rather than as a spot fix in a resolver that is only passing the value along.
-
-## KF-18 — A kernel-layer module reaches a named interpreter package through a function-local import, and no gate sees it
-
-**Surfaced by** the B0 footprint measurement (see [`kernel-distribution-footprint.md`](kernel-distribution-footprint.md)), which walked the static import graph of the whole tree rather than the closures the existing tests pin.
-
-`pipelex/core/memory/working_memory_factory.py` — kernel-layer, and one of the entry points listed in `KERNEL_LAYER_ENTRY_POINTS` — imports `pipelex.builder.pipe.pipe_spec` and `pipelex.builder.pipe.pipe_batch_spec` inside `_get_concrete_class_for_mocking`, under a `# Import here to avoid circular imports` comment. `builder` is a named interpreter package. Importing `pipelex.builder.pipe.pipe_spec` in a fresh interpreter pulls 6 interpreter modules.
-
-**Why both gates stay green, and why that is not a bug in either.** `test_kernel_layer_import_closure.py` imports the entry point and sweeps `sys.modules`, so it sees module-level imports only — a function-local one is invisible to it by construction. `pipelex-dev check-hub-layering` asks a different question (does this reach `interpreter_hub`?) and the answer here is genuinely no: the pulled modules are Pipe-*spec* models, and none of them reaches the hub. So each gate is answering its own question correctly. This is the exact blind spot `test_kernel_layer_import_closure.py`'s own docstring names — "a function-local import inside a kernel module is invisible to it *and* to the static graph at once" — and the boot-contract test's post-call sweep is the mechanism that exists to close it. It does not close *this* one, because the sweep only covers the ops it calls and this mocking helper is on none of them.
-
-**Why it is deferred rather than fixed.** B0 is a read-only measurement, and the fix is a design decision rather than a measurement: the import exists to break a circular import in dry-run mock generation, so removing it means deciding where the "pick a concrete subclass to mock" knowledge belongs — plausibly not in a kernel-layer memory factory at all. Doing that inside a measurement task would be exactly the reflex the standing constraint warns against.
-
-**What settling it would take.** Two independent halves, and the second is worth more than the first.
-
-- *The instance:* move the concrete-subclass choice out of `working_memory_factory`, or invert it so the builder registers its own mocking preference rather than the kernel naming builder types.
-- *The class of bug:* Part B's D-B5 ban closes it structurally — `nothing under pipelex_kernel/ may import pipelex` is stated over a package boundary, so it catches function-local imports and unnamed-bucket destinations alike, which is what neither current gate can do. Until then, the cheap partial is to extend the closure test's detector to AST-scan each entry point's *own* module set for function-local interpreter imports, which would have caught this one.
diff --git a/wip/kernel/kernel-distribution-footprint.md b/wip/kernel/kernel-distribution-footprint.md
deleted file mode 100644
index 1c6220479..000000000
--- a/wip/kernel/kernel-distribution-footprint.md
+++ /dev/null
@@ -1,225 +0,0 @@
-# Kernel distribution footprint — B0 measurement
-
-**Status:** measured 2026-08-11 on `refactor/Kernel-4`, at the Part A end-state (the entry-point group split, merged into this branch). Read-only: nothing in `pipelex/` was changed to produce it.
-
-This is B0 of [`kernel-plugin-groups-and-distribution-plan.md`](kernel-plugin-groups-and-distribution-plan.md). It answers three questions with numbers instead of intuition — **what would the kernel package contain, what would it require, and how big would it be** — and it exists to drive B1's content line (D-B2) now, and to inform a Part C greenlight and its extras design (OQ-2) later.
-
-**On the counts in this document.** The workspace rule against hardcoding counts targets prose that goes stale silently. Here the counts *are* the deliverable, and the plan explicitly asks Checkpoint B to point at this doc rather than inline its numbers. They are therefore dated, attributed to a commit, and reproducible — see [Reproducing](#reproducing-this-measurement). Treat any number here as a snapshot, not as a contract.
-
-## Headline
-
-| | |
-| --- | --- |
-| Declared kernel-layer modules | **560 of 981** in `pipelex/` — 57% of modules, 52% of source bytes (2.65 MiB of 5.07 MiB) |
-| Non-kernel modules a kernel-only boot actually loads | **11** — the concrete addendum to the content line |
-| Third-party top-levels the kernel layer imports at module level | **35**, of which **24** outside the provider extras |
-| Kernel core install (deps only, no extras) | **57 distributions, 61.1 MiB** |
-| Full `pipelex` core install today | **89 distributions, 93.5 MiB** |
-| Shed by dropping interpreter-only deps | **32 distributions, 32.4 MiB** (~35%) |
-| Booted process, kernel-only vs full | 1511 vs 1884 modules; 91.7 vs 108.7 MiB max RSS |
-
-The headline for a hypothetical Part C is therefore **not** "look how little you need". A kernel install is roughly two-thirds of a full one, and the ~61 MiB floor is dominated by four dependencies that have nothing to do with the interpreter: `pillow`, `faker` (via `polyfactory`), `pypdfium2` and `portkey-ai`. If a small headline is wanted, it has to be bought by extras design, not by the layer split — see [What this means for extras](#what-this-means-for-extras-oq-2).
-
-## 1. The module set
-
-### Declared kernel layer, by package
-
-Source of truth is `KERNEL_LAYER_PACKAGES` in `pipelex/cli/dev_cli/commands/hub_layering_guard.py` — the declaration the hub-layering guard polices.
-
-| Package | Modules | Source | Lines |
-| --- | ---: | ---: | ---: |
-| `pipelex.cogt` | 135 | 634 KiB | 14 770 |
-| `pipelex.tools` | 96 | 421 KiB | 11 361 |
-| `pipelex.core` | 76 | 450 KiB | 10 374 |
-| `pipelex.providers` | 111 | 425 KiB | 9 615 |
-| `pipelex.system` | 48 | 223 KiB | 5 478 |
-| `pipelex.graph` | 27 | 157 KiB | 4 124 |
-| `pipelex.kernel` | 19 | 105 KiB | 2 181 |
-| `pipelex.plugins` | 17 | 76 KiB | 1 632 |
-| `pipelex.tracing` | 12 | 62 KiB | 1 560 |
-| `pipelex.runtime_boot` | 1 | 60 KiB | 963 |
-| `pipelex.errors` | 3 | 31 KiB | 687 |
-| `pipelex.runtime_hub` | 1 | 26 KiB | 605 |
-| `pipelex.reporting` | 6 | 27 KiB | 603 |
-| `pipelex.test_extras` | 4 | 16 KiB | 383 |
-| `pipelex.observer` | 4 | 4 KiB | 124 |
-
-Plus `pipelex/kit/` data files (0.30 MiB) — not modules, but shipped, and reached by the kernel layer (see the `kit.paths` leak below).
-
-### What must move with it
-
-A kernel-only boot (`RuntimeBoot.make(needs_inference=False)`, measured in a fresh interpreter) loads exactly **11 modules that are not in the declared kernel layer**:
-
-```
-pipelex (__init__: `log`, `pretty_print` — re-exported from pipelex.tools)
-pipelex.base_exceptions
-pipelex.config
-pipelex.urls
-pipelex.suggested_fix
-pipelex.kit / pipelex.kit.paths
-pipelex.language / pipelex.language.mthds_config
-pipelex.runtime_bridge / pipelex.runtime_bridge.orchestration_mode
-```
-
-The static import graph agrees and adds one the boot does not reach (the `*_list` modules are lazy): **`pipelex.cli.exceptions`**, imported at module level by `cogt.model_backends.model_lists`, `providers.anthropic.anthropic_list` and `providers.bedrock.bedrock_list`.
-
-D-B2 already anticipated the top-level modules ("config/system, base exceptions, urls"). The measurement confirms them and adds four the plan did not name. Full static leak census — kernel-layer module importing a non-kernel-layer `pipelex` module:
-
-| Destination | Kernel importers | Kind | Reading |
-| --- | ---: | --- | --- |
-| `pipelex` (`log`, `pretty_print`) | 79 | module-level | **The single biggest B2 edit.** `pipelex/__init__.py` is itself pure kernel content — it re-exports from `pipelex.tools.log` and `pipelex.tools.misc.pretty`. So the symbol moves to `pipelex_kernel/__init__.py` and 79 modules change one import line. |
-| `pipelex.config` | 33 | module-level | Imports only kernel-layer modules. Moves whole. |
-| `pipelex.base_exceptions` | 32 | module-level | Moves whole (already anticipated). |
-| `pipelex.urls` | 6 | module-level | Moves whole (already anticipated). |
-| `pipelex.cli.exceptions` | 3 | module-level | **A genuine layering smell, not a move.** Kernel-layer model-listing code raises `PipelexCLIError`. Either the error gets a kernel home or these raise a kernel error the CLI maps. D-B4 says the kernel package ships no CLI — this is the only thing standing in the way. |
-| `pipelex.runtime_bridge.orchestration_mode` | 3 | module-level | 34 lines, imported by the plugin registrar and two registries. Moves, or the value type it defines does. |
-| `pipelex.kit.paths` | 2 (+1 deferred) | module-level | The kit *data* is arguably interpreter-side; `paths` is reached from `cogt.models.deck_manifest` and the service agreement. Decide whether the kernel owns a kit path accessor. |
-| `pipelex.language.mthds_config` | 1 | module-level | **The structural one.** `MthdsConfig` is a *field* of `PipelexConfig` in `system.configuration.configs` — the kernel-layer main config model embeds an interpreter-layer submodel. Not fixable by moving a file; it is a config-composition decision. |
-| `pipelex.builder.pipe.pipe_spec`, `…pipe_batch_spec` | 1 | **deferred** | See the finding below. |
-| `pipe_run.delivery_assignment`, `pipe_run.pipe_job`, `runtime_bridge.payloads`, `pipe_operators.func.pipe_func_executor_protocol` | 1 each | `TYPE_CHECKING` | Runtime-harmless; matters only for how D-B5's ban is written (below). |
-
-Everything on that list except the `TYPE_CHECKING` block is work B2 must do. None of it is large; the `pipelex` → `log` edit is broad but mechanical.
-
-## 2. Findings that change the plan's assumptions
-
-### The tools subset is not a subset
-
-D-B2 says the content line includes "the tools subset the closure actually reaches". Measured: of 96 `pipelex.tools` modules, **88 have at least one kernel-layer importer**. The 8 that do not are:
-
-```
-tools.jinja2.jinja2_optional_guards <- pipe_machinery.template_guard_lint
-tools.misc.async_utils <- pipe_controllers.batch.pipe_batch
-tools.misc.diff <- cli.dev_cli.commands.check_config_sync_cmd
-tools.misc.semver <- libraries.library_manager
-tools.misc.toml_sync <- cli.dev_cli.commands.sync_main_config_cmd
-tools.network.ssrf_guard <- pipe_run.delivery_executor
-tools.typing.annotation_utils <- pipe_operators.compose.structured_content_composer
-tools.typing.class_utils <- libraries.concept.concept_library
-```
-
-**Recommendation: move `pipelex.tools` whole.** Splitting 8 modules out of 96 buys ~1 MiB of source and one `semantic_version` dependency, and costs a permanent per-module judgement call on every future tools addition. The "subset" framing in D-B2 should be retired.
-
-### The tree has three buckets, not two — and that is why every gate is green
-
-The kernel layer is *declared* (`KERNEL_LAYER_PACKAGES`); the interpreter layer is *named* by the closure test's `INTERPRETER_PACKAGES`. Those two sets do not partition `pipelex/`. The remainder — `pipelex.cli`, `pipelex.language`, `pipelex.kit`, `pipelex.runtime_bridge`, and the top-level modules `config`, `base_exceptions`, `urls`, `suggested_fix`, `exceptions` — is in neither.
-
-**Every module-level leak in the table above lands in that third bucket.** That is not a coincidence, it is the mechanism: the hub-layering guard asks "does this reach `interpreter_hub`?" and the closure test asks "is this in a named interpreter package?", and each of those nine destinations answers no to both. The gates are working exactly as specified; the specification has a gap the size of the third bucket.
-
-This is the same shape as the already-recorded lesson that an undeclared package is unpoliced rather than neutral — see the `KERNEL_LAYER_PACKAGES` note about `graph`, `tracing`, `observer` and `errors`. D-B5's ban (`nothing under pipelex_kernel/ may import pipelex`) is the first rule that closes it, because it is stated over the *package boundary* rather than over a curated set of names. That is the strongest argument for Part B that the measurement produced, and it is stronger than the legibility argument the plan currently leads with.
-
-### One live layer breach, invisible to both gates
-
-`pipelex/core/memory/working_memory_factory.py` — kernel-layer, and a listed `KERNEL_LAYER_ENTRY_POINTS` entry — has a function-local import of `pipelex.builder.pipe.pipe_spec` and `pipelex.builder.pipe.pipe_batch_spec` inside `_get_concrete_class_for_mocking`, under a `# Import here to avoid circular imports` comment.
-
-`builder` **is** a named interpreter package. Importing `pipelex.builder.pipe.pipe_spec` in a fresh interpreter pulls 6 interpreter modules. It escapes both gates for two independent reasons: the closure test only sees module-level imports, and the hub-layering guard is satisfied because that path does not reach `interpreter_hub`.
-
-The boot-contract test's post-call sweep is the mechanism that exists to catch exactly this — but it only covers the ops it calls, and this mocking helper is not on any of them. Deferred rather than fixed here, per the standing "when in doubt, defer" constraint: B0 is a read-only measurement, and the fix (a circular-import workaround in dry-run mock generation) is a design decision, not a measurement. Recorded as **KF-18** in [`deferred-follow-ups.md`](deferred-follow-ups.md).
-
-### D-B5's ban needs to be written against runtime imports, not text
-
-Four `TYPE_CHECKING`-only imports cross the boundary (`pipe_run.delivery_assignment`, `pipe_run.pipe_job`, `runtime_bridge.payloads`, `pipe_operators.func.pipe_func_executor_protocol` — all from `pipelex.plugins`, which types against interpreter-layer objects it never constructs). A textual "reject any `import pipelex`" AST scan flags all four; they are runtime-harmless and are the plugin mechanism doing its job. Either the ban exempts `TYPE_CHECKING` blocks (the guard already has this exemption — reuse it) or those four type-only references become strings. The cold-import closure half of D-B5 is unaffected either way.
-
-### Two direct dependencies are undeclared
-
-The kernel layer imports **`tenacity`** (5 modules, including `tools.misc.tenacity_utils`) and **`httpcore`** (`tools.network.ssrf_guard`) at module level. Neither is in `pyproject.toml`'s `dependencies` — both arrive transitively today (`tenacity` via `instructor`, `httpcore` via `httpx`). This is a latent break in `pipelex` *now*, independent of Part B: dropping `instructor` from the core deps would break `tools.misc.tenacity_utils` with no dependency change to point at. A kernel distribution would have to declare both explicitly.
-
-### `pipelex.test_extras` is the only reason `pytest` is a kernel import
-
-`test_extras.shared_pytest_plugins` imports `pytest` at module level, and `pipelex.pipelex` imports `test_extras` at boot. It is declared kernel-layer for good reasons (it ships, it measures clean). Whether it belongs in a kernel *distribution* is a separate question that Part C would have to answer; it is excluded from the dependency numbers below.
-
-## 3. Third-party dependency closure
-
-Split by which layer imports each top-level, module-level imports only (`TYPE_CHECKING` excluded):
-
-- **Kernel-only (28):** `PIL`, `aioboto3`, `aiofiles`, `anthropic`, `boto3`, `botocore`, `datamodel_code_generator`, `docling`, `docling_core`, `dotenv`, `fal_client`, `filetype`, `google`, `httpcore`, `huggingface_hub`, `instructor`, `jinja2`, `json2html`, `linkup`, `mistralai`, `openai`, `portkey_ai`, `pypdfium2`, `pytest`, `semantic_version`, `tenacity`, `tomli`, `types_aiobotocore_bedrock_runtime`
-- **Shared (12):** `httpx`, `kajson`, `mthds`, `opentelemetry`, `polyfactory`, `posthog`, `pydantic`, `pydantic_core`, `rich`, `shortuuid`, `tomlkit`, `typing_extensions`
-- **Interpreter-only (3):** `click`, `typer`, `yaml`
-
-Of `pipelex`'s 37 declared core dependencies, **9 are never imported anywhere in the kernel layer**: `idna`, `markdown`, `networkx`, `pipelex-tools-py`, `pyyaml`, `reportlab`, `requests`, `typer`, `urllib3`.
-
-Four of the kernel-side imports are **deferred-only** — imported inside functions, never at module scope — which is the shape of an optional dependency: `instructor` (14 sites), `datamodel_code_generator` (2), `docling` (1), `docling_core` (1).
-
-## 4. Install size
-
-Measured as installed bytes in this venv (Python 3.13.9, macOS, arm64), transitively closed over each distribution's non-extra requirements.
-
-| | Distributions | Size |
-| --- | ---: | ---: |
-| Full `pipelex` core dependency closure | 89 | 93.5 MiB |
-| Kernel core closure (extras and `test_extras` excluded) | 57 | 61.1 MiB |
-| Shed | 32 | 32.4 MiB |
-
-Shed: `aiohappyeyeballs`, `aiohttp`, `aiosignal`, `annotated-doc`, `argcomplete`, `attrs`, `black`, `click`, `datamodel-code-generator`, `docstring-parser`, `frozenlist`, `genson`, `inflect`, `instructor`, `isort`, `markdown`, `more-itertools`, `multidict`, `mypy-extensions`, `networkx`, `packaging`, `pathspec`, `pipelex-tools-py`, `platformdirs`, `propcache`, `pytokens`, `pyyaml`, `reportlab`, `shellingham`, `typeguard`, `typer`, `yarl`.
-
-Note what dominates that list: `instructor` and `datamodel-code-generator` (with `black`, `isort`, `genson`, `inflect`) are shed not because they are interpreter-side but because they are **deferred-only** imports — they would come back the moment the kernel declared them. The genuinely interpreter-side shed is `typer`/`click`/`shellingham`/`argcomplete` (the CLI), `pyyaml`, `networkx`, `markdown`, `reportlab`, `pipelex-tools-py` — roughly 10 MiB.
-
-Heaviest in the kernel core closure:
-
-| Distribution | Size | Pulled by |
-| --- | ---: | --- |
-| `pillow` | 12.57 MiB | direct (`tools.misc.image_utils`, 2 img-gen workers) |
-| `faker` | 8.47 MiB | `polyfactory` |
-| `pypdfium2` | 5.77 MiB | direct (`tools.pdf.pypdfium2_renderer`) |
-| `portkey-ai` | 4.97 MiB | direct (the gateway + portkey providers) |
-| `openai` | 4.76 MiB | direct |
-| `pygments` | 4.31 MiB | `rich` |
-| `pydantic-core` | 4.30 MiB | `pydantic` |
-
-Provider extras, measured as what each adds *on top of* the kernel core:
-
-| Extra | Added | New dists |
-| --- | ---: | ---: |
-| `docling` | 62.89 MiB | 22 |
-| `aioboto3` (s3, bedrock) | 21.60 MiB | 16 |
-| `google` | 21.21 MiB | 14 |
-| `boto3` (dynamodb, bedrock) | 19.33 MiB | 6 |
-| `huggingface_hub` | 12.71 MiB | 10 |
-| `mistralai` | 3.59 MiB | 6 |
-| `anthropic` | 2.28 MiB | 2 |
-| `fal_client` | 1.17 MiB | 5 |
-| `linkup` | 0.04 MiB | 1 |
-
-Runtime cost of a booted process, same venv, fresh interpreter each time:
-
-| Scenario | `sys.modules` | `pipelex.*` modules | max RSS |
-| --- | ---: | ---: | ---: |
-| bare interpreter | 63 | 0 | 15.4 MiB |
-| `import pipelex.kernel.pipelex_kernel` | 927 | 280 | 67.7 MiB |
-| `RuntimeBoot.make()` (kernel-only) | 1511 | 365 | 91.7 MiB |
-| `Pipelex.make()` (full interpreter) | 1884 | 642 | 108.7 MiB |
-
-A kernel-only boot loads 353 of the 560 declared kernel-layer modules — the remainder is provider adapters and tools reached lazily or not at all.
-
-## 5. What this means
-
-### For B1/B2 (the content line, D-B2)
-
-The content line is **the declared `KERNEL_LAYER_PACKAGES` set, whole, plus five top-level modules** (`__init__`, `base_exceptions`, `config`, `urls`, `suggested_fix`), with four boundary decisions to take deliberately:
-
-1. `pipelex.cli.exceptions` — give `PipelexCLIError` a kernel home, or stop raising it from kernel-layer model listing. Blocks D-B4's "no CLI in the kernel package".
-2. `pipelex.language.mthds_config` — `PipelexConfig` embeds `MthdsConfig`. A config-composition decision, not a file move.
-3. `pipelex.runtime_bridge.orchestration_mode` — 34 lines the plugin registrar needs.
-4. `pipelex.kit.paths` — does the kernel own a kit-path accessor, or does the kit data move with it?
-
-`pipelex.tools` moves whole (the "subset" is 92% of the package). `pipelex.test_extras` is the one package whose membership is genuinely open.
-
-### For extras (OQ-2)
-
-If Part C is ever greenlighted, the extras question is **not** about the provider backends — those are already extras and already behave correctly (each adds its weight only when installed, from 0.04 to 63 MiB). It is about the ~61 MiB kernel core, where four dependencies carry 32 MiB between them:
-
-- **`polyfactory` → `faker` (8.5 MiB)** is reached from three modules, all dry-run mock generation. The best extras candidate in the set: a kernel that cannot mock is still a kernel.
-- **`pypdfium2` (5.8 MiB)** is one module, `tools.pdf.pypdfium2_renderer`.
-- **`pillow` (12.6 MiB)** is three modules, but one of them is `tools.misc.image_utils` — likely load-bearing.
-- **`portkey-ai` (5.0 MiB)** is the Pipelex Gateway provider, arguably not core to a *kernel* at all.
-
-None of this needs deciding before Checkpoint B. It is recorded so the greenlight conversation starts from numbers.
-
-## Reproducing this measurement
-
-The scripts were throwaway and live in the session scratchpad, not in the repo — deliberately, since a measurement harness nobody runs is a maintenance liability, and the two properties worth *pinning* are already pinned by `test_kernel_layer_import_closure.py` and `test_kernel_boot_contract.py`. To redo it:
-
-1. **Module set / leak census:** AST-walk every `pipelex/**/*.py`, resolve each `pipelex.*` import target to an existing module (folding `from pkg.mod import Name` onto `pkg.mod`), classify source and destination against `KERNEL_LAYER_PACKAGES`, and report edges where the source is kernel and the destination is not — split by module-level / function-local / `TYPE_CHECKING`.
-2. **Runtime closure:** run each boot scenario in a **fresh subprocess** (both hubs are sticky class-attribute singletons; an in-process check answers from a stale boot and passes vacuously) and dump `sys.modules`.
-3. **Dependency closure and size:** `importlib.metadata.packages_distributions()` to map top-level import names to distributions, then close over each distribution's non-extra `Requires-Dist` and sum `dist.files` sizes on disk.
-
-Caveats: sizes are one venv on one platform (`pillow`, `pypdfium2` and the `google`/`boto3` families are wheel-size-sensitive to platform); `packages_distributions()` maps a top-level to *every* distribution that provides it, which is why `google` fans out to eight; and the static graph cannot see genuinely dynamic imports, which is the blind spot the runtime cross-check exists to cover — the two agreed everywhere they overlap.
diff --git a/wip/kernel/kernel-extraction-plan.md b/wip/kernel/kernel-extraction-plan.md
deleted file mode 100644
index 8bbdf4eac..000000000
--- a/wip/kernel/kernel-extraction-plan.md
+++ /dev/null
@@ -1,278 +0,0 @@
-# Pipelex kernel extraction — `pipelex/kernel/`
-
-## Status block (update at every checkpoint)
-
-- **Current phase:** **Phase 3 COMPLETE — CHECKPOINT C reached, and the plan is done. Three PRs are open against `dev` and NONE may be merged** (the series is stacked: 1/3 = PR #1081 on `refactor/Kernel`, 2/3 = PR #1082 on `refactor/Kernel-phase2`, 3/3 = PR #1083 on `refactor/Kernel-phase3` based on it). **Commits are named by subject here, not by SHA.** Each branch in this series is rebased every time the one below it moves, which rewrites every hash on it — so a SHA written into this block goes stale the next time that happens, and this block has already been caught carrying stale ones. Phase 1's record, on `refactor/Kernel`: the Phase 0 scaffolding, tasks 1.1–1.6, task 1.7, then three review-driven commits (the forced-DRY fix below among them). Phase 2, in order: the extract / img-gen / search / compose operator extraction (tasks 2.1–2.4); the function-call semantics plus the per-operator boot contract (task 2.5, with the extension the cold review forced); the bot-triage fixes; the doc levelling; then the parity-gaps fold — `pipelex/kernel/img_gen_prompt.py` for that track's gap 2.3, and the boot-contract arm it turned out to owe — and the doc corrections from the bot round after it.
-- **Gates at Phase 3 head:** `make agent-check` **green**, full `make agent-test` **green**, `make drift-check` **green**.
-- **Gates at Phase 2 head, kept for the record:** `make agent-check` **green**, full `make agent-test` **green**, `make drift-check` **green** (not reopened — Phase 2 touched no hub module and no guard file, because the executor seam stayed interpreter-side; see the 2.5 deviation). CI green on every check on PR #1082.
-- **Gates at Phase 1 head (`c0815cf7f`), kept for the record:** all three green, `hub-layering-convention` acked twice — the forced-DRY fix reopened it. CI green on every check. Two gate failures surfaced at Checkpoint A and both are fixed — see "What Phase 1 taught Phase 2" below. Note for the record: this doc once claimed `make agent-check` was green at `3a11d113a`. It was not; the keyword-only gate was red there.
-- **One real bug was found by review and fixed — the PR's only behavior change.** `PipelexKernel.make` minted a LIVE `CogtRunParams` on a keyless boot (`needs_inference=False`), bypassing the forced-DRY coercion `PipeRunParamsFactory` applies. Reachable, not hypothetical: `run_mode` alone gates mocking, so the call reached a real provider, and `needs_inference=False` means backends load *leniently* rather than credential-free. The hazard was the **default** — `PipelexKernel.make(user_id=…)` names no mode. Root cause is this branch's own doing: the factory's docstring called itself "the single writer" of `run_mode`, which stopped being true when the kernel became a second run-params factory. The rule now lives once in `runtime_hub.resolve_run_mode_for_boot`, called by both factories, pinned by a third arm on the D4 contract module. **Phase 2 lesson: any new kernel-side factory of run-scoped state owes the same audit — ask which process-wide invariants the pipe tier applies that the kernel tier now skips.**
-- **Review record — Phase 1 (PR #1081):** a cold `/code-review` (no inherited context) found no correctness bug, no layering violation and no stale reference, and confirmed the three past bug fixes in this code (templating-style mutation, the multi-image/document dict-key collision, LLM-error cause unwrapping) preserved verbatim. Bots: Greptile 5/5 on head; cubic found the forced-DRY bug above; Codex raised one item (polymorphic serialization of `LlmObjectResult.content`) four times, independently verified and rejected twice — see KF-5.
-- **Review record — Phase 2 (PR #1082):** the cold `/code-review` found the boot-contract gap (see "What the cold review changed" below), which was the one substantive finding. Bots across two rounds: Greptile pass 5/5 both times with no actionable defects; cubic found four items and came back "no issues" after the fixes; Codex found three. **Three were fixed**, in *honour an explicit seed of 0 and stop run_search taking fields it ignores* — named by subject rather than hash, because this branch is rebased whenever its parent moves and the hash this line used to carry now resolves from no branch at all: the img-gen seed read with `or`, swallowing an explicit `0` that `ImgGenJobParams` accepts under its own `ge=0`; `run_search` taking a `TemplateBlueprint` and using two of its four fields; and an architecture-overview sentence *this branch introduced* claiming kernel ops do "no hub lookups" (they read `runtime_hub` freely — what they never touch is the interpreter layer). **Four were deferred** as KF-9..KF-12, each verified pre-existing against `git show refactor/Kernel:<path>` first. **One was rejected**: a P1 asking for a single-consumer test fixture to move to a `conftest.py` that does not exist, against a rule whose own text says "for easy sharing". Two of the deferred four are worth carrying into Phase 3 as one item, not two — KF-10 (`max_results`) and KF-12 (`nb_images`) are the same defect, a value flowing from blueprint to provider with no bound anywhere on the path, and in both cases the constraint belongs upstream on the blueprint rather than where the bot pointed.
-- **Review record — Phase 3 (PR #1083):** CI green on every check. Greptile 5/5 with no comments, vouching specifically for trace identity and per-step metadata propagation; cubic found two; Codex found one, the same as cubic's second. **One was fixed**: the memory boundary could not read back a multiple-output result — `llm_object(is_multiple_output=True)` stores a `ListContent`, and the single-content reads cannot narrow it, so the boundary sent the caller back to `WorkingMemory`'s positional accessors via an error message it raised itself. Two bots and the cold `/code-review` converged on it independently, and the producing side ships in this very diff, which is what made it a hole rather than a want. Fixing it also caught a doc bug this branch introduced: all four `extract_*` docstrings named `WorkingMemoryTypeError` where the accessors raise `StuffContentTypeError`. **One was rejected on measurement** and recorded as KF-14 — see there for the two calls / two records / correct total probe, and for the fact that makes the class of finding moot (`UsageReportEvent.node_id` has no readers anywhere, and a kernel run emits no graph events).
-- **Next action: none in this plan — it is finished.** What remains is landing the stack (merge 1/3, then 2/3, then 3/3, in that order and only when each is approved) and the deferred items in [`deferred-follow-ups.md`](deferred-follow-ups.md) — none of which blocks landing this plan. (Named by file rather than by numeric range: the range went stale twice as later rounds appended entries, which is the same self-staling shape as naming commits by hash.) Some are *scheduled after* the series lands, which is a different thing from blocking it: KF-3 and KF-4 are worth doing together as a standalone tidy once it does, both mechanical and both cheaper once no PR is claiming a verbatim move; KF-10 and KF-12 share one home, a blueprint-constraint PR carrying the schema regeneration and the cross-repo sweep.
-- **What Phase 3 turned out to be, in one line:** 3.1 and 3.2 are small on purpose — the memory boundary was already single-sourced machinery, so what they add is a named, keyword-only, boot-contract-tested surface for it rather than new behavior; 3.3 is where the real work was, because "usage reporting reaches parity" turned out to be a question about *who owns a lifecycle the kernel structurally cannot own*.
-- **What Phase 2 turned out to be, in one line:** four operators were genuine extractions (2.1–2.4 moved deck resolution, job-params assembly, generation and write-back into `pipelex/kernel/`); the fifth (2.5) was not a move and did not become one — its seam is typed on interpreter models, so what moved was the *call*, not the pluggable indirection.
-- **Open decisions:** none blocking. The kernel construction shape (0.2), structure-prompt provenance and the deferred runtime-boot orchestrator question are settled under Decisions, alongside every deviation from the plan's letter taken in Phases 1, 2 and 3. Deferred items are in [`deferred-follow-ups.md`](deferred-follow-ups.md), which is the count of record.
-
-### What Phase 1 taught Phase 2
-
-Read this before starting 2.1. **Moving code has consequences no compiler reports**, and Phase 1 hit four classes of them. Two failed a gate loudly; two are silent and only one of those is caught by CI at all.
-
-**Caught by a gate (will fail your build):**
-
-1. **Dead subject grants.** `subject_grants.toml` still granted positional subjects for defs the move deleted (`pipe_operators/llm/helpers.py::get_output_structure_prompt`) or relocated (the `LLMPromptBlueprint._extract_direct_*` methods). The convention's staleness check is *symmetric* — a grant whose def moved or vanished hard-fails until the registry is cleaned. Remove rather than re-grant: kernel replacements are fully keyword-only, the package's stated zero-grants doctrine. **Sweep the grants for every operator you move.**
-2. **Dead paths in `.test_durations`.** Moved test modules leave the committed shard-balancing artifact pointing at their old home, and `tests/unit/repo/test_test_durations_paths.py` catches it. Rewrite the node ids' path prefix rather than regenerating: the tests moved verbatim, so their recorded durations are still accurate, and `make store-test-durations` would churn every timing in the file for no gain. New modules simply have no entry, which pytest-split treats as average duration.
-
-**Silent (nothing tells you):**
-
-3. **Under-the-hood docs naming moved files.** Phase 1 broke a file path in `docs/under-the-hood/image-handling-in-llm-prompts.md` and nothing noticed — no drift contract has a trigger glob over `pipelex/pipe_operators/**` or `pipelex/kernel/**`, and `mkdocs build --strict` does not validate inline code spans in a table. Grep `docs/` for every path you move. Already known for Phase 2: `docs/under-the-hood/dry-run-mock-generation.md` names `pipe_operators/compose/structured_content_composer.py`, a task-2.4 target, and `docs/under-the-hood/architecture-overview.md` still presents `pipe_operators/` as the sole home of operator behavior. Both settled in Phase 2: the composer did not move, so its reference is still accurate, and the architecture overview now states the split. The Phase-3 equivalent is task 3.4's kernel page, which should be written against these two rather than beside them.
-4. **`docs/errors/` pages carry the defining module path.** The generator emits ``| Defined in | `<module>` |`` onto each page, so moving a `PipelexError` subclass makes its committed page stale — and `make generate-error-pages` runs in neither `make check` nor CI. Phase 1 escaped this only by luck: `LLMPromptBlueprintValueError` and its replacement `PromptContentError` are bare `ValueError`s, so `tests/data/errors/error_identity.txt` never moved. Phase 2 was predicted to move error classes that *are* `PipelexError`s (search, img-gen, compose, extract). **It moved none** — each operator's error family stayed with the interpreter-side code that raises it, because the kernel ops raise the same cogt-level errors the moved code raised and the operators rewrap as they always did. So the two chores this item names went unexercised and are still owed by whoever first moves a `PipelexError` into `pipelex/kernel/`: regenerate the pages, and note that the generator's `_SUBSYSTEM_SECTIONS` has no `kernel` key, so a moved error falls through to the `platform-and-tooling` fallback under a humanized "Kernel" heading instead of "Execution & runtime".
-
-**Two traps that are not move-consequences:**
-
-5. **The execution-data coverage test cannot see module-level functions.** `tests/unit/pipelex/pipe_machinery/test_execution_data_coverage.py` walks only `self.<method>(...)` call chains to find each pipe's `_register_execution_data` call. A kernel function is invisible to it. Phase 1 survived because that call stayed inline in `pipe_llm.py`; **every Phase-2 operator must keep `_register_execution_data` on its own `self.*` chain**, or the test fails for that pipe.
-6. **Every operator has tracer intermediates, and Phase 2's task list does not mention result envelopes.** The typed result envelope (`LlmTextResult`/`LlmObjectResult`/`StructuringPath`) was Phase 1's real design work beyond the ops, and each remaining operator registers its own execution data with the same kind of intermediates. Decide per operator whether it gets an envelope or the interpreter keeps computing them — but decide deliberately, because "the tracer rides the same functions" is the property that stops the two callers drifting.
-
-### Cold-start: where the code is
-
-`pipelex/kernel/` now holds these modules:
-
-| module | what is in it |
-| --- | --- |
-| `__init__.py` | Doctrine only, no re-exports: layering, definition-site imports, top-level imports, concept-resolution routing, memory contract, keyword-only/zero-grants, boot contract. |
-| `pipelex_kernel.py` | `PipelexKernel` — `__init__`, `make()`, `make_step_metadata()`, and the `llm_text` / `llm_object` façade methods. Holds only the run-level `JobMetadata` and `CogtRunParams`. |
-| `prompt_references.py` | `ImageReference(Kind)` and `DocumentReference(Kind)`, **moved** out of `pipe_operators/` (they could not stay there: a runtime-layer prompt-content model may not import an interpreter-layer type). All importers re-pointed; the two unit-test modules moved to `tests/unit/pipelex/kernel/`. |
-| `llm_prompt_content.py` | `LlmPromptContent` (+ `make_from_text`) and `assemble_llm_prompt` — the whole former `LLMPromptBlueprint.make_llm_prompt` body, images/documents/registry/placeholders included. |
-| `llm_results.py` | `StructuringPath` StrEnum, `LlmTextResult`, `LlmObjectResult`. |
-| `llm_ops.py` | `resolve_llm_setting_for_text`, `resolve_llm_setting_for_object`, `derive_templating_style`, `derive_structure_prompt`, `generate_object_content`, `run_llm_text`, `run_llm_object`. |
-| `memory_ops.py` | The whole memory boundary: `shape_inputs` (in), `store_result` (write-back, which **Phase 2 moved out of `llm_ops.py`**), `extract_main_content` / `extract_named_content` (typed read) and their `_as_list` pair (the multiple-output shape). |
-| `extract_ops.py` / `extract_results.py` | `resolve_extract_setting`, `build_extract_job_params`, `run_extract`; `ExtractResult`. |
-| `img_gen_ops.py` / `img_gen_results.py` | `resolve_img_gen_setting`, `resolve_default_size`, `build_img_gen_job_params`, `run_img_gen`; `ImgGenResult`. |
-| `search_ops.py` / `search_results.py` | `resolve_search_setting`, `run_search`; `SearchResult`. |
-| `compose_ops.py` / `compose_results.py` | `build_compose_context`, `build_composed_content`, `run_compose_template`; `ComposeResult`. Construct mode stayed interpreter-side — see Deviations. |
-| `func_ops.py` / `func_results.py` | `call_registered_function`, `run_func`; `FuncCallResult`, `FuncResult`. The pluggable executor seam stayed interpreter-side — see Deviations. |
-| `exceptions.py` | `PromptContentError(ValueError)` — the former `LLMPromptBlueprintValueError`, moved with the code that raises it. |
-
-`PipelexKernel` is **LLM-only and stayed that way through Phase 2** — the five operator ops above are module-level functions with no façade method, and the interpreter calls them directly. See Decisions for why, and note the test consequence: `test_runtime_layer_import_closure.py`'s `pipelex.kernel.pipelex_kernel` entry point does not reach them, so `test_kernel_boot_contract.py` is their only gate.
-
-Interpreter side: `LLMPromptBlueprint` keeps its fields, `required_variables()` and its `make_llm_prompt` **signature** (its many test call sites depend on it) but now maps down through a new `to_prompt_content()` and delegates; `PipeLLM._live_run_operator_pipe` calls `run_llm_text` / `run_llm_object` and its `_llm_gen_object_stuff_content` is gone; `PipeStructure` calls `resolve_llm_setting_for_object`, `derive_structure_prompt`, `generate_object_content` and `store_result` (not `run_llm_object` — see Decisions); `pipe_operators/llm/helpers.py` (`get_output_structure_prompt`) is deleted.
-
-### Verified in Phase 0 (do not redo)
-
-All three negative controls were run and each failed as intended, then was reverted: deleting the `pipelex.kernel` entry fails `test_the_pipelex_kernel_stays_declared`; a `pipelex.exceptions` import in a kernel module fails the aggregate gate; an `interpreter_hub` import in a kernel module fails both the closure test and the static guard.
-
-### What task 1.7 landed
-
-Three test modules, and one of them turned out to close a gap the tree did not previously cover:
-
-| module | what it pins |
-| --- | --- |
-| `tests/unit/pipelex/kernel/test_llm_object_kernel.py` | The two kernel-only arms, through the façade in DRY. Structure-prompt provenance is three cases, not two: derived-by-default, supplied-text-overrides, and **empty-string-overrides-with-nothing** — the sentinel is `is not None`, so a rewrite to `structure_prompt or await derive_structure_prompt(...)` would silently turn the third back into a derivation and only that case would notice. Plus the memory contract, asserted as "the *returned* memory carries the result" and deliberately **not** as `result.memory is memory`: pinning today's aliasing would make the change the contract exists to permit look like a regression. |
-| `tests/unit/pipelex/kernel/test_kernel_boot_contract.py` | The boot contract, permanently. Subprocess, `RuntimeBoot.make(needs_inference=False)`, `PipelexKernel.make(run_mode=DRY)`, **both** façade calls (`llm_object` and `llm_text` — they share almost nothing below the façade, so covering one leaves the other's closure unproven), typed results asserted — then a `sys.modules` sweep **after** the call, with the usual negative control (`cogt` as an "interpreter package" must fail). |
-| (moved in 1.3) `test_image_reference.py` / `test_document_reference.py` | Followed the reference types into `tests/unit/pipelex/kernel/`. |
-
-**The post-call sweep is a new gate, not a restatement of an old one — verified, not assumed.** Injecting a function-local `from pipelex.pipe_operators.llm.pipe_llm import PipeLLM` into `run_llm_object` leaves `pipelex-dev check-hub-layering` at **exit 0** and the import-closure module at **15 passed**; only the boot-contract test goes red. That is the function-local blind spot both `hub-layering.md` and the kernel's own doctrine warn about, closed mechanically for the first time. `docs/contribute/hub-layering.md` now documents it beside the other three gates.
-
-**The `concept_resolver`-omitted arm was correctly not written** — see the deviation record under Decisions. It does not exist in Phase 1.
-
-## Goal
-
-Pull operator-execution semantics out of the interpreter's operator classes into shared, importable kernel functions under a new public `pipelex/kernel/` subpackage, and re-point the interpreter onto them — **zero behavior change**. Today, what a `PipeLLM` step actually *does* (deck resolution, templating-style derivation, prompt assembly, generation, memory write-back) is only reachable through a fully booted interpreter with a loaded library. After this refactor, operator semantics have **one implementation with multiple callers**: the interpreter's operators, and any programmatic caller — SDK-style embedding, hosts that boot only the runtime layer — invoking them directly on a `RuntimeBoot`-only process with zero `.mthds` loaded.
-
-This completes the runtime/interpreter layering arc: the hub split (#1062/#1064), layer placement (#1071), concept purity (#1072), the boot split that created `RuntimeBoot` (#1073), the templating-style threading fix (#1074), and the concrete-class object path (#1076). It is a pure refactor, valuable on its own: single-sourced operator semantics are what prevent two callers from drifting apart.
-
-## Doctrine
-
-- **Layering.** The caller-facing kernel API is hub-free: an explicit `PipelexKernel` object and explicit arguments, never an ambient lookup. Kernel *internals* may use `pipelex.runtime_hub` — never `pipelex.interpreter_hub`. This is a mechanically enforced rule (the hub-layering guard plus the runtime-layer import-closure test), but #1071's history shows the guard does not hold the line "for free" — see the four sub-tasks under 0.1, which exist because each one closes a hole that episode demonstrated: an *undeclared* package is unpoliced rather than neutral (both guard rules filter through the layer declaration, so omission makes the guard quieter); a declaration with no test pinning it is a comment; a **cross-layer re-export aggregate defeats the guard entirely** (vendor adapters once pulled the interpreter into a declared-clean runtime package by importing from `pipelex.exceptions` instead of the definition site — a module that re-exports across layers is a layer boundary with the sign filed off; that hole is the one now closed mechanically tree-wide, and the kernel inherits the coverage by being declared); and a function-local import is invisible to the static graph and the closure test at once.
-- **Calls are activity-shaped.** Explicit, serializable-leaning inputs and outputs; `WorkingMemory` threaded explicitly (taken and returned); no hidden shared state. This is a design constraint, not a deliverable: it keeps a future Temporal-activity wrapping a re-decoration rather than a rewrite. The memory contract, stated so both caller classes read the same thing: a kernel call may mutate the memory it is passed and returns it — callers must treat the returned memory as the result and must not rely on aliasing of the argument, because inline execution aliases the two today and a serialization boundary will not.
-- **Functions carry the semantics; the class is a façade.** Module-level kernel functions hold the shared implementation. The `PipelexKernel` class is a thin ergonomic façade over them, holding the per-run state a caller would otherwise thread through every call. The interpreter's operators call the functions directly.
-- **The kernel API is fully keyword-only — zero subject grants.** The governing bar, stricter than the general rubric in [`docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md): only the first parameter may be positional, and strictly only when it is obviously the subject — named in the function, or as unmistakable. Nothing in the kernel clears that bar: `llm_text` and `llm_object` name what they *produce*, and `memory` is threaded state (taken and returned), not the operand. So `pipelex/kernel/` records no entries in `subject_grants.toml`, every call site names every argument, and `make fix-keyword-only` mechanically produces exactly this form — there is no ordering trap. Any future kernel def that wants a positional subject must clear the stated bar in review first, not in the registry.
-- **Boot contract: `RuntimeBoot.make()`** ([`pipelex/runtime_boot.py`](../../pipelex/runtime_boot.py)). Every kernel call must be servable on the runtime-only composition root, with no interpreter constructed and no library loaded. The import-closure test guards this structurally; a live smoke run proves it dynamically.
-- **Zero behavior change.** The full `make agent-test` suite is the gate at every checkpoint — no *behavioral* test rewrites. Import repoints, module moves and `mocker.patch` target updates are expected and are not a red flag: Phase 1 repointed several test modules' imports, moved two, and rewrote patch targets in `test_cogt_run_params_carrier.py` when the code they patch moved.
-
-## Target caller experience
-
-The sketch below is the API shape to preserve while the internals get extracted for real out of `pipe_llm.py` (which is where the deck chain, style derivation, and prompt assembly currently live). Every parameter is keyword-only, including `memory`. Two contracts the sketch elides for brevity, stated here because they are load-bearing: `user` and `system` are prompt *templates* rendered against `memory` inside the kernel — template references are how images and documents enter the prompt (task 1.3's assembly functions do the rendering) — and the return value is a small typed result carrying the updated memory plus the rendered prompts, the resolved model setting, and the structuring path taken, because the interpreter's execution-graph tracer consumes those intermediates after generation and recomputing them outside the kernel would mean a second assembly path. Expect the signatures to grow explicit keyword parameters for setting overrides and output multiplicity as tasks 1.1–1.4 extract the real thing; the shape that must survive is fully-named arguments over explicit state. One limit the sketch does not show, now that Phase 1 has landed: **the façade methods carry no image or document references at all** — both hardcode `LlmPromptContent.make_from_text(...)`, and a caller needing references drops to `run_llm_text` / `run_llm_object` with an `LlmPromptContent` it builds itself. Phase 2 brings image-bearing operators (2.1 `PipeExtract`, 2.2 `PipeImgGen`), so decide there whether `PipelexKernel` grows reference-carrying parameters or stays a deliberately text-only convenience. **Decided in Phase 2 — it stays LLM-only; see Decisions.** The sketch above already reflects one growth the plan did not anticipate: folding the parity-gaps track in widened `llm_text` to take an optional `concept` and `output_class`, and made `model` optional too, so the façade can express what the op beneath it always could — see the 2.1 entry in that track and the `llm_text` docstring for why each of the three has to be reachable.
-
-```python
-class PipelexKernel:
- """Façade over the module-level kernel ops; holds per-run state."""
-
- def __init__(self, *, job_metadata: JobMetadata, cogt_run_params: CogtRunParams): ...
-
- @classmethod
- def make(cls, *, run_mode: PipeRunMode = PipeRunMode.LIVE, user_id: str) -> "PipelexKernel": ...
-
- async def llm_text(
- self,
- *,
- memory: WorkingMemory,
- model: LLMModelChoice | None = None,
- user: str,
- system: str | None = None,
- concept: Concept | None = None,
- output_class: type[StuffContent] | None = None,
- result: str,
- ) -> LlmTextResult:
- """The semantics of a PipeLLM step with a Text output.
-
- `user`/`system` are templates rendered against `memory`; the result
- carries the returned memory plus the rendered prompts and resolved
- setting for the caller's tracing needs.
- """
-
- async def llm_object(
- self,
- *,
- memory: WorkingMemory,
- output_class: type[StuffContentT],
- concept: Concept,
- model: LLMModelChoice,
- user: str,
- system: str | None = None,
- structure_prompt: str | None = None,
- result: str,
- is_multiple_output: bool = False,
- fixed_nb_output: int | None = None,
- ) -> LlmObjectResult:
- """The semantics of a PipeLLM step with a structured output.
-
- The concrete pydantic class is handed over directly — no registry lookup,
- and no runtime schema-to-class reconstruction, because the class exists.
- The structure prompt is derived from `output_class` by default (same
- config template as today); pass `structure_prompt` to override it.
- """
-```
-
-## Phase 0 — scaffolding
-
-- [x] 0.1 Create the `pipelex/kernel/` package skeleton: façade module (the `PipelexKernel` class, thin over module-level functions) plus per-domain ops modules (llm first; extract/img/search/compose/func come in Phase 2), with docstring doctrine stating the layering role. Then, in the **same commit**, the four guard declarations the doctrine section explains:
- - [x] 0.1a Declare `pipelex.kernel` in `RUNTIME_LAYER_PACKAGES` ([`pipelex/cli/dev_cli/commands/hub_layering_guard.py`](../../pipelex/cli/dev_cli/commands/hub_layering_guard.py)) — an undeclared package is unpoliced, not neutral. In the same commit, add `pipelex.kernel` to the runtime-layer enumeration in [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md): that doc is the boundary's specification, it claims every top-level package is accounted for, and the `hub-layering-convention` drift contract triggers on the guard file — so the doc review is mandatory either way, and same-commit is this task's own discipline applied to the doc half.
- - [x] 0.1b Pin that declaration with a test, mirroring `test_the_measured_clean_packages_stay_declared` ([`tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`](../../tests/unit/pipelex/cli/dev/test_hub_layering_guard.py)), and run the negative control: delete the entry, watch it fail, restore it.
- - [x] 0.1c Write the no-aggregate rule into the kernel's docstring doctrine: import from definition sites only, never from `pipelex.exceptions` or any other cross-layer re-export, and never let `pipelex/kernel/__init__.py` become one (consistent with the repo-wide no-re-exports rule, but stated here because for this package it is a layering property, not a style one). The mechanical half needs no work here: KF-1's tree-wide gate ([`tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py`](../../tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py)) walks every package in `RUNTIME_LAYER_PACKAGES` and fails on imports and bare strings alike, module-level or function-local, so 0.1a's declaration buys it — including, for this one hazard, the function-local blind spot 0.1d records. Keep the negative control, which now proves the *coupling* rather than the test: the gate silently covers zero modules when a declared path does not resolve, so add a banned import to a kernel module, watch that gate fail, remove it.
- - [x] 0.1d Add a kernel entry point to `RUNTIME_LAYER_ENTRY_POINTS` in the closure test ([`tests/unit/pipelex/test_runtime_layer_import_closure.py`](../../tests/unit/pipelex/test_runtime_layer_import_closure.py)), with a negative control. Remember its blind spot: it only covers module-level imports — a function-local import is invisible to it *and* to the static graph, so reviews must watch for those by hand.
- - [x] 0.1e **Concept-resolution routing rule.** Kernel run paths answer concept compatibility with the two *pure* tiers that #1072 created — `Concept.are_compatible_by_declaration` (no registry; a caller without a loaded library supplies its own `concept_resolver`, or omits it where no `refines` crosses a package boundary) and `are_structure_classes_compatible` (takes resolved types) — and never call `ConceptLibrary.is_compatible` or `ConceptProviderAbstract.get_structure_class`, which is where resolution and therefore the ambient registry read legitimately live. Passing the concrete class alongside the concept is the preferred shape, as in the target sketch above.
-- [x] 0.2 Kernel construction shape: `PipelexKernel.make()` mints `JobMetadata` + `CogtRunParams`; decide what the instance holds vs what stays per-call. Two constraints on that decision are settled now. First, the instance holds only identity and run-scoped state (the run-level `JobMetadata`, the `CogtRunParams`); anything derived from config or the model deck — resolved settings, prompting style — is computed per-call and never cached on the instance, exactly the deliberate per-run derivation `pipe_llm.py` documents today, because cached derived state is hidden shared state and breaks per-call `run_mode` variation. Second, the run-level metadata the instance holds is not what a step runs under: each call mints a per-step copy via `copy_with_update` (per-step `pipe_run_id`), matching the interpreter's pass-down-a-modified-copy pattern, so trace and usage attribution stay per-step.
-
-## Phase 1 — LLM vertical slice (the meat)
-
-Each item is a fragment of `PipeLLM` to extract into a kernel function for real:
-
-- [x] 1.1 **Deck-resolution chain**: pipe choice → deck `llm_choice_overrides` → `llm_choice_defaults`, for_text and for_object (including object-falls-back-to-text), → `LLMSetting`. Out of `pipe_llm.py`, into a kernel function.
-- [x] 1.2 **Templating-style derivation**: setting/model → `prompting_target` → configured style.
-- [x] 1.3 **Prompt assembly**: the full `make_llm_prompt` path (text, images and their `ImageRegistry`, documents as the `[Document N]` substitution dict) as kernel functions, so kernel coverage equals PipeLLM coverage — not just a text-only form. The input shapes need a home and it is not the blueprint: `LLMPromptBlueprint` and its reference types live in `pipe_operators/llm/` and are language-side (blueprints are what `.mthds` parses into), so the kernel cannot import them without breaking the closure. The kernel defines its own runtime-layer prompt-content model (template strings, image/document references over memory) and the blueprint's `make_llm_prompt` becomes a thin mapping onto the kernel functions — the same move `core/` made with `ConceptProviderAbstract`: the semantics migrate to the layer that owns them, the language artifact keeps its parse-and-validate role and maps down.
-- [x] 1.4 **`llm_text` / `llm_object` semantics**: structure prompt (settled — see the decision record below: derived in-kernel from `output_class` by default, optional `structure_prompt` argument overrides), output multiplicity (single / variable list / fixed count), result storage into memory, and the typed result envelope the sketch describes (updated memory + rendered prompts + resolved setting + structuring path), which is what lets the interpreter's tracer ride the same functions instead of keeping a parallel path.
-- [x] 1.5 **Concrete-class object path**: the kernel's object call passes its `output_class` through to `ContentGenerator.make_object` (whose parameter is named `object_class`), which threads it down since #1076 — so no schema-to-class rebuild happens inline when the class is in hand. The schema round-trip stays where it serves the distributed activity boundary; do not remove it.
-- [x] 1.6 **Re-point** `PipeLLM` (and `PipeStructure`, which shares the object semantics) onto the kernel functions. The cut line, stated so nobody has to find it by trial: the interpreter retains blueprint resolution, the library-backed text-vs-object dispatch (`is_compatible` against native Text, `pipe_llm.py`), and its error-context wrapping (`PipeRunError` with the pipe stack — the kernel raises the same cogt-level errors the moved code raises today, and the operator rewraps as it always has); it calls `llm_text` or `llm_object` with resolved values, and the kernel never re-asks the library. Dispatch is the caller's job by construction — the kernel's two entry points are the fork made explicit. One quiet arm belongs on the interpreter's side of that line, cheaper remembered than rediscovered: today `get_output_structure_prompt` returns `None` when the concept's structure class is not in the class registry, and generation proceeds without a structure prompt — the kernel's `llm_object` *requires* `output_class`, so the re-point must keep that no-class arm in the interpreter (it is part of blueprint resolution, not of the kernel's semantics) rather than assume class resolution always succeeds. The zero-behavior-change suite is the backstop; this is the arm it would catch.
-- [x] 1.7 Tests: kernel unit tests (dry mode), naming the kernel-only arms explicitly because the re-pointed interpreter suite structurally cannot reach them — the structure-prompt argument supplied vs derived-by-default, the `concept_resolver`-omitted arm (**planned, then correctly not written** — Phase 1's ops answer no concept-compatibility question at all, so the arm has nothing to assert; see the 0.1e vacuity deviation under Decisions, and do not invent it), and the memory mutate-and-return contract; full `make agent-test` green; and the boot contract proven **permanently**, not once: a committed dry-mode pytest boots `RuntimeBoot.make()` in a subprocess (the closure test's isolation pattern — a suite-level boot already holds the process singletons), loads zero `.mthds`, and asserts a kernel `llm_object` call returns a typed result, with a live smoke script kept as the manual Checkpoint C verification. Note for whoever writes that test: it is the first real caller of a runtime-only boot, and `runtime_boot.py`'s orchestrator-rejection comment explicitly defers the external-interpreter-orchestrator half-application question to that first caller (analysed in `wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`) — settle it or guard it there, don't inherit it silently.
-
-**CHECKPOINT A** — LLM slice extracted and re-pointed; gates green (`make agent-check` + full `make agent-test` + `make drift-check`); cold `/code-review` on the diff; update this doc's status block with decisions taken and cold-start state.
-
-## Phase 2 — remaining operators
-
-Same treatment, one operator at a time, interpreter re-pointed as each lands. Each task includes kernel unit tests for that operator's kernel-only arms — the paths the re-pointed interpreter suite never takes are exactly where the two callers could drift undetected.
-
-- [x] 2.1 `PipeExtract` → kernel extract ops over the `make_extract_pages` seam, including the page-view handling (`should_include_page_views`, `page_views_dpi`, `max_page_images`). Landed as `resolve_extract_setting` / `build_extract_job_params` / `run_extract` in `kernel/extract_ops.py`, with `ExtractResult` in `kernel/extract_results.py`.
-- [x] 2.2 `PipeImgGen` → kernel image ops (single / list). Landed as `resolve_img_gen_setting` / `resolve_default_size` / `build_img_gen_job_params` / `run_img_gen` in `kernel/img_gen_ops.py`, with `ImgGenResult` in `kernel/img_gen_results.py`. `resolve_default_size` **moved** out of `pipe_img_gen.py` (it resolves a *config* default, which is kernel business); its unit test followed it to `tests/unit/pipelex/kernel/test_img_gen_size_default.py` and `.test_durations` was path-rewritten accordingly.
-- [x] 2.3 `PipeSearch` → kernel search ops (sourced answer / structured). Landed as `resolve_search_setting` / `run_search` in `kernel/search_ops.py`, with `SearchResult` in `kernel/search_results.py`. The kernel renders the query template and hands the rendered text back for the tracer. It takes the template as `template: str` + `category: TemplateCategory` rather than as the `TemplateBlueprint` it first landed with: a search renders against memory alone, so a blueprint handed over `templating_style` and `extra_context` that `run_search` silently ignored — harmless on the language path (`PipeSearchFactory` hardcodes the blueprint) but a trap on a caller-facing surface. Narrowing the signature, rather than merging the two fields in, keeps the zero-behavior-change contract and makes the op symmetric with `run_compose_template`.
-- [x] 2.4 `PipeCompose` → kernel templating ops. Landed as `build_compose_context` / `build_composed_content` / `run_compose_template` in `kernel/compose_ops.py`, with `ComposeResult` in `kernel/compose_results.py`. **Construct mode stays interpreter-side — a deliberate deviation, see Decisions.** `StructuredContentComposer` now builds its TEMPLATE-field context through the kernel's `build_compose_context`, so the two paths' three-layer ordering is single-sourced, and its dead `pipe_run_params` field is gone (stored, threaded to nested composers, never read — its docstring's "used to check if we're in dry run mode" was stale). That removal is what leaves the composer importing nothing from `pipe_run`.
-- [x] 2.5 `PipeFunc` → kernel function-call op. Landed as `call_registered_function` / `run_func` in `kernel/func_ops.py`, with `FuncCallResult` / `FuncResult` in `kernel/func_results.py`. `call_registered_function` **moved** out of `DirectPipeFuncExecutor.run_pipe_func` — registry lookup, async-vs-sync dispatch and the str/list→`StuffContent` coercion are what running a function *means*, and they are now defined once for both the in-process executor and a programmatic caller. `PipeFunc` keeps its hub-resolved executor call and rides `store_result` for the write-back. **The pluggable executor seam stays interpreter-side — a deliberate deviation, see Decisions.** Kernel unit tests cover `run_func` (which no interpreter test reaches) and both dispatch arms.
-
- The original task text, kept because its analysis of the seam is what the deviation rests on: `PipeFunc` → kernel function-call op over the **`PipeFuncExecutorProtocol` seam**, not a bare registry lookup. The executor is pluggable — `run_pipe_func` (live objects) and `run_pipe_func_transported` (serialized request/response via `pipe_func_execution_dtos`) are its two arms — and the kernel op must carry **both arms**. But the kernel never reads `HubSlot.PIPE_FUNC_EXECUTOR`: that slot is applied in `Pipelex.setup`, so it does not exist on a runtime-only boot, and an ambient read would break the boot contract for this one op. Instead the executor enters as an explicit protocol-typed argument — the interpreter passes its hub-resolved one (selected by `pipe_func_config.execution_mode`, `direct` by default), a programmatic caller passes the direct executor or its own.
-
- ⚠ **This is the highest-risk task in Phase 2, and it is not a move.** An earlier draft of this plan said the protocol "needs a runtime-layer home, since it currently lives in `pipe_operators/func/`", framing it as placement. It is not: the protocol and its DTOs are *typed on interpreter-layer models*. `pipe_func_executor_protocol.py` imports `PipeRunParams`; `pipe_func_execution_dtos.py` imports `PipeRunParams` **and** `LibraryCrate`; `pipe_func_execution_transport.py` imports `get_current_library` / `get_library_manager` straight from `interpreter_hub`, which is a flat layering violation the instant it lands in `pipelex/kernel/`. Both `pipe_run` and `libraries` are interpreter packages. The kernel is clean today *because* it uses `CogtRunParams` and never `PipeRunParams`, and the kernel's own doctrine forbids the usual escape hatch ("if a function-local import seems necessary, the placement is wrong and the type should move instead"). So the real task is **re-typing the protocol off `PipeRunParams`/`LibraryCrate`, or keeping an interpreter-side adapter** — not relocating a file. Moving those two models is far outside Phase 2's scope.
-
- Three further hazards on this task, none of which any gate catches:
-
- - **`pipelex/config.py` imports the executor registry**, which defers the protocol under `TYPE_CHECKING` for exactly this reason. If you conclude the deferral is now unnecessary and un-defer it, `pipelex.config` starts loading `pipe_run` and `libraries` — failing every closure test at once, from a module almost everything imports.
- - **Two external plugin repos import these exact modules**: our Daytona sandbox plugin (executor, DTOs, transport) and our Temporal plugin (in-workflow executor and the PipeFunc activity). They are separate repos, so nothing in this tree's CI sees them.
- - **A module path is held as a bare string and run via `python -m`** in the Daytona plugin (`"pipelex.pipe_operators.func.pipe_func_transported_entrypoint"`, hardcoded in two clients and again in its Dockerfile). No import error, no type checker, no static gate catches a rename — it fails at runtime inside the sandbox. Grep sibling repos for string-held module paths before renaming anything under `pipe_operators/func/`.
-
- Also relevant: 2.5 must touch `pipelex/interpreter_hub.py`, which reopens the `hub-layering-convention` drift contract — and this time the review target is genuinely falsified, because `docs/contribute/hub-layering.md` states in several places that the pipe-func accessor is interpreter-layer *because* its protocol lives in `pipe_operators/func/`.
-
-### What the cold review changed — the boot contract was claimed for six operators and tested for one
-
-A cold `/code-review` of the whole Phase-2 diff returned one finding, and it was right: the boot contract was being *asserted* for every operator and *tested* for the LLM arms alone. Worth recording in full, because the gap was invisible from inside the phase and the same shape will recur in Phase 3.
-
-`test_kernel_boot_contract.py` is the only gate that catches a **function-local interpreter import** inside a kernel function — the static hub-layering guard and the import-closure test both see module-level imports only, which the kernel's own doctrine says out loud. Phase 1 built that gate for `llm_object`/`llm_text` and Phase 2 added five operator ops without extending it. The blind spot is per-function: a function-local import inside `run_search` is caught only by calling `run_search`.
-
-Worse, the *import-time* gate did not reach them either. `test_runtime_layer_import_closure.py` lists `pipelex.kernel.pipelex_kernel` as its kernel entry point on the strength of a comment claiming "the façade imports the ops modules … so one entry point covers the package". That was true in Phase 1 and Phase 2 silently falsified it: `PipelexKernel` is an LLM-era façade that imports `llm_ops` alone. So `extract_ops`, `img_gen_ops`, `search_ops`, `compose_ops` and `func_ops` were policed by **neither** test.
-
-Fixed by extending the boot-contract subprocess to call all seven entry points on the same keyless `RuntimeBoot` and sweep afterwards. All five were drivable in DRY exactly as the LLM arms are — every cogt leaf mocks before a worker is looked up — so the settings are built literally rather than through the `resolve_*_setting` helpers, which read the deck and would be asking a different question. The stale closure-test comment is corrected to say what actually covers those modules and when adding one there would still be worth it. **Verified by mutation, not by assertion:** a function-local `pipe_operators` import planted in `run_search` makes the extended test fail with 72 offending modules, and passes without it.
-
-Two things surfaced while writing it, both recorded where they belong rather than here:
-
-- `ExtractResult.content` is the one kernel envelope field annotated below `StuffContent` (`ListContent[PageContent]`), so pydantic revalidates the plain `ListContent` that `run_extract` builds into a fresh container — making `result.content` a different object from the one the returned memory holds, uniquely among the ops. Nothing is lost (the `PageContent` items pass through by identity) and the interpreter is unaffected, since `PipeExtract` reads only `.memory`. The narrowing is worth keeping — a caller gets `.items` typed without a cast — so it is documented in `extract_results.py` instead of being flattened for uniformity.
-- The per-op check in the boot-contract test is therefore by type, not by identity. Asserting identity would have been asserting a coincidence.
-
-**CHECKPOINT B — PASSED.** All operators riding the kernel; `make agent-check`, full `make agent-test` and `make drift-check` green; this doc updated. Scope honestly stated: "riding the kernel" means every operator's produced content now reaches memory through `store_result`, and every operator's *resolvable* semantics (deck chains, job params, generation, templating, function invocation) are kernel functions with the interpreter as one caller. Two arms deliberately did not follow — `PipeCompose`'s construct mode and `PipeFunc`'s executor indirection — both recorded under Decisions and in `deferred-follow-ups.md`. The boot contract is now pinned for every operator rather than claimed for them.
-
-## Phase 3 — memory boundary and run-scoped state parity
-
-**Standing rule, learned the hard way in Phase 2:** every new kernel entry point gets called in `test_kernel_boot_contract.py`'s subprocess — the standing exception being the `resolve_*_setting` helpers, which read the model deck, a question the boot contract deliberately does not ask. It is the only gate that sees a function-local interpreter import, it is per-function, and neither static guard will tell you when it has fallen behind — Phase 2 added five ops and both gates stayed green while covering none of them. Adding the call is a few lines; noticing it was never added took a cold review.
-
-- [x] 3.1 Boundary shaping: kernel `shape_inputs` over the existing `InputShaper` (per-signature specialization is out of scope). Landed in `pipelex/kernel/memory_ops.py`, beside `store_result` — the two ends of the same boundary. `pipeline/execution_seams.py` calls it instead of `WorkingMemoryFactory.make_from_pipeline_inputs`, so the interpreter is one caller. **Narrower than the factory it re-points, deliberately:** `input_specs` is required, so the kernel has no bottom-up no-signature arm — see Deviations.
-- [x] 3.2 Result extraction helpers (main-stuff and named-slot, typed). `extract_main_content` / `extract_named_content` in `memory_ops.py`. They earn their place on one fact: every result envelope annotates its content field with the base `StuffContent`, so a caller holding an `LlmObjectResult` has the object but not its type — the helper takes the class the op was asked for and hands it back narrowed. Review added `extract_main_content_as_list` / `extract_named_content_as_list`: a multiple-output call stores one `ListContent`, the single-content read cannot narrow it (the bare item class raises, `ListContent[item_type]` is rejected by design), and the bare-`ListContent` workaround loses the item type — so without them the kernel produced one shape its own read half could not read.
-- [x] 3.3 Per-step `JobMetadata` semantics (per-step `pipe_run_id` minted from the instance's run-level metadata via `copy_with_update`, per the 0.2 constraint) as a kernel duty; optional trace-context wiring so cost/usage reporting reaches parity when a caller provides one. This task must also answer the lifecycle-ownership question it implies: the interpreter's run machinery is what opens and closes usage reporting today, so state who owns that lifecycle for a kernel-driven run. **Parity bar, measured not asserted:** a test runs an equivalent step through the re-pointed interpreter and through direct kernel calls (mock usage) and asserts the two produced `TokensUsageRecord` lists ([`pipelex/reporting/usage_records.py`](../../pipelex/reporting/usage_records.py)) match in shape and count — the list `/execute` returns on `pipe_output.tokens_usages` and durable runs persist as `tokens_usages.json`.
-
- **Answered: the caller owns the lifecycle; the kernel owns the stamp.** `PipelexKernel.make` grew `trace_context` and `is_mock_usage`; the context rides the run-level `JobMetadata` and every `make_step_metadata()` copy inherits it, which is the whole of what the cogt leaf needs to emit a usage event. Opening the event log, registering it on the report delegate, reading the events back and clearing the registration stay outside — a kernel call has no run boundary to hang a `finally` on, because it is one step and a caller may make one or a thousand. `pipelex/tracing/` gives a caller both halves it needs (`make_event_log`, `UsageAggregator`) and is runtime-layer, so this costs the boot contract nothing. The parity bar is met by `tests/integration/pipelex/kernel/test_usage_parity.py`, and it is **non-vacuous by mutation**: dropping the trace-context stamp in `PipelexKernel.make` turns 1 record into 0 and the test red.
-
-- [x] 3.4 Docs: a `docs/` page for the kernel — public-API doctrine, the layering contract, what a programmatic caller may import and how it boots. `docs/under-the-hood/pipelex-kernel.md`, in both mkdocs navs and the section index, written *against* `architecture-overview.md` (which now links to it) and `tokens-usage-wire-records.md` rather than beside them, as trap #3 asked.
-
-**CHECKPOINT C — PASSED.** Interpreter operator semantics single-sourced in the kernel and its memory boundary named at both ends; `make agent-check`, full `make agent-test` and `make drift-check` green; the `docs/` page landed; this doc updated. Scope stated honestly: "fully single-sourced" carries the two Phase-2 exceptions unchanged (`PipeCompose`'s construct mode, `PipeFunc`'s executor seam — KF-7, KF-8), and the boot contract now covers twelve entry points rather than seven (ten at the first push, plus the two list-extraction helpers review added).
-
-## Decisions
-
-- **Structure-prompt provenance — SETTLED: derived in-kernel, optional override.** The registry was only ever needed for the concept→class hop, and the kernel's object call already holds the class — so the kernel derives the structure prompt from `output_class` itself (same config template, same `StructurePrinter`, same `is_structure_prompt_enabled` gate as today), and an optional `structure_prompt` argument overrides it for callers who want to supply their own. The interpreter drops `get_output_structure_prompt`'s registry hop and rides the kernel derivation, so both callers produce the same prompt by default — the alternative (prompt as argument only) would have left the derivation outside the kernel and forked the two callers' default behavior, which is the drift this extraction exists to kill.
-- **The deferred runtime-boot orchestrator question — SETTLED: recorded, not guarded.** `runtime_boot.py` deferred the external-interpreter-orchestrator half-application hole to "the first caller of a runtime-only boot", which is now the kernel's boot-contract test. That caller does not trigger it, and not by luck: the gate is only reached when `plugins.boot_orchestrator` is non-`None`, and the test names none — as no kernel caller will, since the kernel's doctrine forbids it from reading `HubSlot` at all and Phase 2's `PipeFunc` op takes its executor as an explicit argument for that reason. The remedy stays unbuilt: both candidates are real machinery (a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class attribute, or a widened `build_registrar` signature) bought for a path with still no production caller. Reassess when a runtime-only boot is offered to real callers — that is when naming an orchestrator becomes reachable. Written up in [`wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`](../boot-split/runtime-boot-external-interpreter-orchestrator.md), and `runtime_boot.py`'s comment now points at the settlement rather than at an open question.
-- **Kernel construction shape** (task 0.2) — **SETTLED as implemented.** `PipelexKernel` holds exactly `job_metadata` (run-level, fresh `uuid4` `pipeline_run_id`) and `cogt_run_params`. `make_step_metadata()` mints the per-step copy with a fresh `pipe_run_id` and an explicit `otel_context=None`. Nothing config- or deck-derived is cached.
-
-### Deviations from the plan's letter, taken during Phase 3
-
-- **`shape_inputs` requires `input_specs`; the bottom-up no-signature arm is not kernel business.** 3.1 said "over the existing `InputShaper`", and that is literally what landed — the kernel does not wrap `WorkingMemoryFactory.make_from_pipeline_inputs`, whose signature-driven arm *is* `InputShaper.shape` and whose other arm infers each value's concept from its own shape. Inference is exactly the ambient guess a kernel entry point must not make for a caller, so `input_specs` is required rather than optional. A caller with no declared specs builds its stuffs and hands over a `WorkingMemory` directly.
-- **`WorkingMemoryFactory.make_from_pipeline_inputs` was re-pointed at, not moved.** The instinct — move the body into the kernel and delete the factory method, as 2.2 did with `resolve_default_size` — is wrong here, and checking is what showed it: the method is on the sanctioned transport surface, pinned by `docs/specs/pipelex-transport-boundary.md` — which lives at the **workspace root**, not in this repo, alongside the `conformance/` suite that enforces it — and is called from `pipelex-transport/pipelex_transport/bridge.py`, `pipelex-mistralai-workflows` and both demo repos. Deleting it is a cross-repo breaking change, which is not what a zero-behavior-change refactor gets to do. So the interpreter's one call site moved to the kernel op and the factory kept its surface.
-- **`PipelexKernel.make` grew two parameters, and the ordering of one of them is load-bearing.** `trace_context` was the task's ask; `is_mock_usage` came with it, because the DRY-only sub-flag is what makes a measurable parity comparison possible at all (a plain dry run reports zero tokens on both sides, which would compare equal while proving nothing). It is validated against the **requested** mode, before `resolve_run_mode_for_boot`, mirroring `PipeRunParamsFactory` — otherwise the one illegal combination would raise on a keyed boot and pass silently on a keyless one, i.e. a contract violation whose visibility depended on whether the process held API keys. Pinned in `test_keyless_boot_forced_dry.py`.
-- **A supplied `TraceContext` sets the run id rather than sitting beside one.** `PipelexKernel.make(trace_context=…)` adopts its `graph_id` as `pipeline_run_id`. The alternative (a separate optional `pipeline_run_id` parameter) lets the two diverge, and divergence is not cosmetic: the registered-context emit path stamps the event log's id while the runner fallback stamps the metadata's, so a run whose two ids differ scatters its usage events across both and a read-back keyed on either silently misses half. One identity, one parameter.
-- **The parity test measures `pipe_code` as *absent on both sides*, not as the one honest difference.** The plan's expectation was that the interpreter fills it and a kernel call cannot. It does not: `pipe_code` is stamped in `live_run_pipe`, which a DRY run never reaches, so the measurement cannot observe the one field that would legitimately differ. Asserted as-is rather than excluded quietly, because that is the honest scope of what the comparison proves — and recorded as KF-13, since a `--dry-run --mock-usage` cost report having no pipe attribution is a real (pre-existing, interpreter-side) gap.
-- **KF-6 was settled, KF-2 and KF-5 were closed out as needing nothing, KF-10/KF-12 were re-homed.** Four deferred items named a Phase-3 task as their trigger. Three resolved without code (see `deferred-follow-ups.md`); KF-6 resolved with a docstring, narrowing `StructuringPath` to say it names the *LLM* paths and why `PipeStructure`'s sibling literal has no member. KF-10 and KF-12 had been scheduled onto 3.1 as "the task that decides what a kernel entry point does with a malformed argument" — 3.1 answered that for the memory boundary (reject with a typed, locator-bearing error, which is what `InputShaper` already does), but `max_results` and `nb_images` are operator arguments that never cross it, so their conclusion is unchanged and their home is a standalone blueprint-constraint PR.
-
-### Deviations from the plan's letter, taken during Phase 2
-
-- **`PipeFunc`'s pluggable executor seam stays interpreter-side (task 2.5).** The task asked the kernel op to take the executor as an explicit protocol-typed argument, carrying both arms. Neither arm's type survives the layer boundary: `PipeFuncExecutorProtocol.run_pipe_func` declares `pipe_run_params: PipeRunParams` and `run_pipe_func_transported` is typed on `LibraryCrate`, both interpreter models the task itself rules out moving. That leaves two ways to satisfy the letter, and both were rejected on cost. *Re-typing the protocol* breaks two out-of-tree implementers (our Daytona and Temporal plugins) which thread `pipe_run_params` onto the transported request — for a parameter nothing in either repo actually reads, which makes it a wire-format question, not a cleanup. *A kernel-side protocol plus an interpreter adapter* buys a second protocol for one seam, a wrapper class, and a model conversion at the boundary — to compose two calls. So the composition (`run_func`) is the kernel's in-process path, and what is genuinely shared — the call itself and the write-back — is single-sourced in `call_registered_function` and `store_result`, which is what the interpreter's default executor and operator now ride. Consequence to hold onto: a programmatic caller cannot dispatch a kernel `run_func` to a sandbox, and `run_func` has no in-tree caller, which is why it is unit-tested directly. Recorded in [`deferred-follow-ups.md`](deferred-follow-ups.md) as KF-8.
-- **`PipeCompose`'s construct mode stays interpreter-side (task 2.4).** Its semantics are `StructuredContentComposer` (840 lines) over a `ConstructBlueprint` (315 lines), and the kernel cannot import either: `pipe_operators` is an interpreter package by the closure test's own predicate. So covering construct mode means *relocating both into `pipelex/kernel/`* — an MTHDS field-composition blueprint, its composer, and the `PipeComposeError` family they raise (which drags the `docs/errors/` regeneration and the `error_identity.txt` snapshot). Phase 1's `LLMPromptBlueprint` precedent points the other way but does not apply: there the kernel needed a *small* input model (`LlmPromptContent`) and the blueprint mapped down; the equivalent here is a near-verbatim copy of a 315-line model. Weighed against that cost, the caller-side gain is close to nil — a programmatic caller holding real Python builds the object directly rather than describing it in a blueprint. The template path, which *is* pure rendering over memory, is fully extracted, and the one thing both paths share (the three-layer context ordering) is now single-sourced in `build_compose_context`. Recorded in [`deferred-follow-ups.md`](deferred-follow-ups.md) as KF-7.
-- **`PipelexKernel` stays an LLM-only façade — the reference-carrying question the plan assigned to Phase 2 is answered "no".** The task at "Target caller experience" was to decide, once image-bearing operators landed, whether the façade grows reference-carrying parameters. It did not grow at all: the five Phase-2 ops are module-level functions with no façade method. Two reasons. The façade's job is holding *per-run state* a caller would otherwise thread through every call (`job_metadata`, `cogt_run_params`), and that state is identical for every op — a façade method per operator would add a naming surface without adding a service. And the ops' remaining arguments are the operator-specific ones (`ExtractInput`, `ImgGenPrompt`, `output_class`, a template and its category), which a façade would have to enumerate verbatim; wrapping them buys nothing and forks the signature the moment an op grows a parameter. So a programmatic caller mints a `PipelexKernel` for the run state and calls the module-level functions with it, which is what the boot-contract test does. **Consequence worth carrying into Phase 3:** `test_runtime_layer_import_closure.py`'s only kernel entry point is `pipelex.kernel.pipelex_kernel`, so an LLM-only façade means that test's closure does not reach the other ten kernel modules — the standing rule at the head of Phase 3 exists for exactly this reason.
-- **The kernel ops modules gained a shared `memory_ops.store_result`.** Phase 1 put it in `llm_ops.py`; every Phase-2 operator ends the same way, and importing it *from `llm_ops`* would have implied an LLM dependency that does not exist. It moved to `pipelex/kernel/memory_ops.py`, which is also where Phase 3's boundary shaping (3.1) and result extraction (3.2) belong.
-- **Not every operator earned a rich result envelope, and that was decided per operator** (the plan's trap #6). Each envelope carries exactly the intermediates the kernel *produces* and the caller cannot recompute: `SearchResult` carries the rendered query and the post-resolution `SearchSetting` (which is not the one passed in); `ComposeResult` the rendered text; `ExtractResult` the resolved `ExtractSetting`. `ImgGenResult` carries only memory + content, because everything the img-gen tracer records is either a caller input or something the caller resolved through an ops function before calling. The memory contract is why even the thin one exists.
-- **The kernel gained an image-prompt constructor the plan never scheduled (`pipelex/kernel/img_gen_prompt.py`).** Folded in from the parity-gaps track (its gap 2.3), on the same reasoning as Phase 1's `llm_text` widening: it is a defect *this* PR would otherwise introduce. `run_img_gen` takes a *ready* `ImgGenPrompt` by deliberate analogy with `run_llm_text` taking a ready `LlmPromptContent`, but the kernel shipped the LLM prompt's constructor and no image counterpart — so a `RuntimeBoot`-only process could call every operator op except the image one, and `kernel/prompt_references.py` hosted `ImageReference` under a docstring asserting the kernel resolves them while the interpreter-layer blueprint did the resolving. A "callable without the interpreter" guarantee at less than 100% is worth nothing. `ImgGenPromptBlueprint` drops 296 → 82 lines and delegates, keeping parse-and-validate; `ImgGenPromptBlueprintValueError` becomes `PromptContentError`, the same swap Phase 1 made on the LLM side. **The predicted cost did not materialise:** the parity plan expected the move to drag `ImageRegistry`, `PromptImageFactory`, `substitute_nested_in_context` and `render_template` across a layer boundary and force a scoping decision — all four are already `cogt`/`tools` citizens, and the blueprint held exactly one interpreter-layer import. Nothing moved layers. `max_prompt_images` deliberately stayed with the blueprint: it is a property of the model the *pipe* chose, its breach is a pipe-level error, and it is a `len()` check rather than the subtlety the kernel module exists to centralise. Two now-dead subject grants were removed rather than re-granted, per this package's zero-grants rule — exactly the sweep this plan warns about for every operator moved.
-- **The new entry point took the boot-contract arm the standing rule owes it, and the arm replaced a hand-built prompt.** `assemble_llm_prompt` never needed one — `run_llm_text` and `run_llm_object` both call it, so the LLM arms carry its closure. `run_img_gen` takes a ready prompt and calls nothing, so the img-gen arm had been *constructing* its `ImgGenPrompt` in the test, for the plain reason that nothing in the kernel could build one. That made the arm's coverage incomplete in precisely the way the kernel surface was. It now assembles from a memory holding a referenced image and generates from the result, asserting on the `[Image N]` token *and* on `input_images` — the two readings of one registry, whose disagreement would mislabel which image the prompt describes with nothing downstream able to notice.
-
-### Deviations from the plan's letter, taken during Phase 1
-
-- **The deck chain is two functions, not one `resolve_llm_settings`.** `resolve_llm_setting_for_text` and `resolve_llm_setting_for_object` (the latter taking the optional `llm_choice_for_text` that makes its chain one rung longer). A single function returning both settings would have made `PipeStructure` — which resolves only the object setting today — newly resolve the text one too, which is a behavior change on the one gate that matters. Two functions keep each caller resolving exactly what it resolved before, and the chain is still single-sourced.
-- **`PipeStructure` rides the kernel's *pieces*, not `run_llm_object`.** It shares the object semantics — structure-prompt derivation, generation, memory write-back — and calls those four kernel functions. It does **not** share prompt assembly: it has no template of its own and no memory-borne references, it renders one configured `structuring_prompt` template over one input string, and forcing that through `assemble_llm_prompt` would have changed the render context from `{"text": …}` to the whole working memory. That is a real behavior change for a cosmetic gain.
-- **`templating_style` is an explicit argument to `run_llm_text` / `run_llm_object`, not derived inside them.** `PipeLLM` derives it from its **text** setting and uses it on both paths; a kernel that derived from its own setting would silently change the object path's rendering style. The derivation itself (`derive_templating_style`) is single-sourced in the kernel; *which* setting governs is the caller's decision, and it has to be, because a caller can hold two.
-- **One deliberate widening, worth watching in review:** `PipeLLM`'s text path used to wrap only `structure_class(text=…)` in `except ValidationError`. That construction is now inside the kernel call, so the handler wraps the whole call. A `ValidationError` raised elsewhere inside it (prompt assembly, result construction) would now surface as `PipeRunError("Error generating text content in PipeLLM …")` instead of propagating raw. Same error class, same wrap, slightly wider scope.
-- **`assemble_llm_prompt` does not log the assembled user text**; `LLMPromptBlueprint.make_llm_prompt` still does, keeping its `output_concept_ref` parameter (whose only job was that log) so its test call sites are untouched. Moving the log into the kernel would have meant either duplicating it or carrying a log-only parameter across the layer boundary.
-- **The no-class arm task 1.6 told the re-point to keep does not exist, and was correctly dropped.** 1.6's text says the interpreter must retain the arm where `get_output_structure_prompt` returns `None` because the concept's structure class is not in the registry, "rather than assume class resolution always succeeds". The re-point does assume it: both `pipe_llm.py` and `pipe_structure.py` now call `get_class_registry().get_required_subclass(...)` eagerly before dispatch, and the soft `get_class(...) -> None` path is gone with `helpers.py`. That is right, and the plan's premise was a half-reading of the old code: the pre-move object path called `get_required_subclass` unconditionally as the first statement of `_llm_gen_object_stuff_content`, so no run ever survived a missing class — the soft arm only ever suppressed the *structure prompt*, never the failure. The only real change is that the error now raises before prompt assembly instead of after. Recorded because a future reader of 1.6 would otherwise think a required arm was dropped silently.
-- **`PipelexKernel.llm_text` ships as wide as the op beneath it** — `concept`, `output_class` and `model` are optional, defaulting to what the method previously hardcoded (native `Text`, `TextContent`, the deck's own choice). Folded in from the parity-gaps track (its gap 2.1) rather than landed as a follow-up PR, because the narrowness is a defect *this* PR would otherwise introduce: `run_llm_text` takes all three and the interpreter passes all three, so a façade hardcoding them stores `native.Text`/`TextContent` where an interpreted run stores the declared concept and its generated class — a silent memory divergence surfacing only later as `StuffContentTypeError` in whoever reads the result back. `llm_object` had all three from the start; the asymmetry was between the façade's own two methods. Purely additive (the only callers are tests), gated by `tests/unit/pipelex/kernel/test_llm_text_kernel.py`, which asserts on what lands in the returned memory rather than on the signature. No changelog entry: the package is new and unreleased, so there is no shipped behavior to note.
-- **The prompting-style question that came with it is deferred, not fixed — see KF-16.** The same parity track listed a gap 2.2 claiming `llm_object` renders under the wrong model's style. Re-verified here as **overstated**: the single explicit `model` wins `resolve_llm_setting_for_object`'s first rung, so the style comes from that setting — which is what an interpreted run derives for a pipe naming only a text model. The two agree for every call the façade can express. What remains is narrowness (a pipe naming *both* models is inexpressible), and widening it would mean building the two-setting derivation the mechanism is slated to lose entirely — `wip/prompting-style/README.md`.
-- **The concept-resolution routing rule (0.1e) is satisfied vacuously in Phase 1.** The LLM kernel ops answer no concept-compatibility question at all — the text-vs-object dispatch stays interpreter-side by construction, which is stronger than routing through the pure tiers. The rule is written into the kernel doctrine and applies to whatever Phase 2 adds; there is no `concept_resolver`-omitted arm to test yet, so task 1.7's third named arm does not exist and should not be invented.
-
-## Non-goals (explicit)
-
-- **Controllers stay interpreter-side.** This effort covers operator semantics only; `pipelex/pipe_controllers/` is untouched.
-- **No standalone PyPI distribution yet.** A separately installable kernel dist is a later milestone, once the cogt hub/plugins coupling is unwound; for now the kernel is a subpackage of `pipelex`.
-- **No behavior changes and no new operator features.** Extraction is behavior-preserving; the full test suite must pass, with only the mechanical churn the Doctrine section describes (import repoints, moved modules, patch-target updates).
-- **No Temporal activity target.** Activity-shaped is a design constraint on call signatures, not a deliverable of this refactor.
-
-## Key runtime files for the extraction
-
-`pipelex/pipe_operators/llm/pipe_llm.py`, `pipelex/pipe_operators/llm/llm_prompt_blueprint.py`, `pipelex/cogt/content_generation/content_generator.py` (+ `assignment_models.py`, `content_generation/llm_generate.py`, `schema_to_model_factory.py`), `pipelex/cogt/models/model_deck.py`, `pipelex/core/memory/working_memory.py`.
-
-## Working setup and gates
-
-- **Branch:** `refactor/Kernel` in the `_kernel/` worktree (treat it as repo root), off `dev`; PR targets `dev` on `Pipelex/pipelex`. The branch's `remote` and `pushRemote` are pinned to `origin`.
-- **First-time setup:** `make install` (fresh worktree, fresh venv). `derived/mthds_schema.json` is gitignored — regenerate with `.venv/bin/pipelex-dev generate-mthds-schema` if plxt lint complains.
-- **Gates at every checkpoint:** `make agent-check`, full `make agent-test`, `make drift-check`. ⚠ **`make agent-check` does not run `drift-check`** — only `make check` and CI do, so an agent following `CLAUDE.md` will not see an open contract locally and will discover it as a red CI job. Run it explicitly. The contract this work trips is **`hub-layering-convention`** (triggers on the layering guard and on both hub modules), *not* `keyword-only-convention`, which an earlier draft of this section named: that one triggers only on `keyword_only_guard.py`, and editing `subject_grants.toml` trips nothing. Workflow: `make drift-plan` → review → `git add` the trigger files (the digest reads the **index**, so an unstaged tree reports a false green) → `make drift-ack CONTRACT=<id> RATIONALE="…"`.
-- **Checkpoint discipline:** at each checkpoint, update the status block at the top of this doc with completed phases, decisions taken, open questions, and the current state of the code, so the work hands off cleanly into a fresh session.
diff --git a/wip/kernel/kernel-plugin-groups-and-distribution-plan.md b/wip/kernel/kernel-plugin-groups-and-distribution-plan.md
deleted file mode 100644
index 33c454ba5..000000000
--- a/wip/kernel/kernel-plugin-groups-and-distribution-plan.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Kernel layer: named, layer-gated plugins, and its own distribution
-
-**Goal.** Two staged moves that turn the kernel/interpreter boundary from a convention into a mechanism and then into enforced structure — plus a third that is deliberately left hypothetical: **Part A** splits plugin discovery by layer under kernel-branded entry-point groups (`pipelex.plugins.kernel` / `pipelex.plugins.interpreter`), with a coherent rename of the layer vocabulary from "runtime layer" to "kernel layer". **Part B** moves the kernel layer into its own top-level package `pipelex_kernel/` at the repo root, beside `pipelex/` — same repo, same single distribution, **not** published separately — making the one-way dependency statically checkable in one line. **Part C is a hypothetical, not a commitment**: it *would* ship `pipelex_kernel` as its own PyPI distribution `pipelex-kernel`, so a kernel-only consumer's venue physically could not contain the interpreter — but it proceeds only on an explicit greenlight (C0), and this plan commits to nothing beyond Part B.
-
-**Why.** The kernel trust-base story ("this code imports only the kernel") is a per-venue claim: measurement showed that merely *installing* the Temporal plugin dragged the whole interpreter into every pipelex process in the venv, because plugin discovery imports every installed plugin's module. The plugin-side violation was fixed at pipelex-temporal HEAD ("Keep the interpreter out of an import-light register, and gate it", 2026-08-09) — but that fix protects only plugins we author. Part A makes a kernel-only boot never even `load()` interpreter-side entry points; Part B makes a kernel→interpreter import impossible to merge (a static ban over `pipelex_kernel/`); a greenlighted Part C would make the interpreter uninstallable in a kernel-only venue, closing the hole for plugins nobody vetted — and would make the story self-evidencing: `pip install pipelex-kernel`, drop in your kernel-consuming code, run.
-
-**Why B is the plan's end-state and C stays hypothetical.** The big mechanical churn (every kernel-layer import repoints) lands without touching the release surface — the `pipelex` wheel simply ships two top-level packages, and PyPI sees nothing new. The irreversible step (registering and committing to a public `pipelex-kernel` distribution) is deliberately **not decided by this plan** — it is a distinct future decision, to be taken with B's measured footprint in hand. And consumers churn once either way: imports move to `pipelex_kernel.*` at B, and a later C would change only install metadata. Precedent: the Temporal externalization deliberately separated the reversible local cut-over from the publish gate.
-
-## Status
-
-| Part | Phase | State |
-| --- | --- | --- |
-| A | A0 naming ruling + inventory | **done** — see [A0 as built](#a0--as-built) |
-| A | A1 group-split mechanism | **done** — see [A1 as built](#a1--as-built) |
-| A | A2 external-plugin migration | **done** — three planned repos + the cookbook example (D-A3-1), verified against the A1 core; local commits, none pushed. See [A2 as built](#a2--as-built) |
-| A | A3 gates + checkpoint | **done** — 🛑 [CHECKPOINT A](#a3--as-built) reached; Part A complete and green, nothing pushed |
-| B | B0 footprint measurement | **done** — measured 2026-08-11; deliverable [`kernel-distribution-footprint.md`](kernel-distribution-footprint.md). Read-only, no source changed. See [B0 as built](#b0--as-built) |
-| B | B1 decisions | not started |
-| B | B2 the move + gates | not started |
-| C | C0 the greenlight | hypothetical — no decision taken |
-| C | C1 the distribution split | hypothetical |
-| C | C2 physical gate + proof | hypothetical |
-
-## The naming ruling (Louis, 2026-08-10)
-
-The layer formerly called the "runtime layer" is the **kernel layer**. Rationale: "runtime" is overloaded three ways in this workspace — the whole `pipelex/` engine (the workspace-docs sense), the orchestration venue ("boot as a Temporal runtime", the `runtime_bridge`/`boot_orchestrator` sense), and the sub-interpreter layer — and once Part B exists, the layer boundary *is* the `pipelex_kernel` package boundary, so the layer should carry the package's name. The Linux precedent holds: drivers are "kernel modules" without extending the syscall façade, so "kernel plugin" reads naturally for an inference backend or storage provider. "Kernel" is correctly Pipelex-branded per the workspace brand-boundary rule (a runtime/implementation concept, not a language one).
-
-**Rename scope — three buckets.** The sweep must be coherent (one name for one boundary) but must not cross repo-boundary pins prematurely:
-
-| Bucket | Contents | When |
-| --- | --- | --- |
-| Rename in Part A | `RUNTIME_BUILTIN_PLUGINS` → `KERNEL_BUILTIN_PLUGINS`, `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES` → `KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES` (both in `pipelex/providers/builtins.py`, consumed by `runtime_boot.py` and `interpreter_plugins/builtins.py`); "runtime-layer" prose in `plugins/contract.py`, `plugins/discovery.py`, provider docstrings, and the under-the-hood SPI docs; `tests/unit/pipelex/test_runtime_layer_import_closure.py` → `test_kernel_layer_import_closure.py` (and the reference to it in pipelex-temporal's `test_plugin_interpreter_import_closure.py` docstring — that copy's canonical-list pointer must follow in the same window, it is the drift hazard its own docstring warns about) | A0 |
-| Rename in Part B | Module paths whose names are pinned across repo boundaries or that move anyway: `runtime_boot.py`/`RuntimeBoot` → `kernel_boot`/`KernelBoot`, `pipelex.runtime_hub` → the kernel package's hub. `pipelex.runtime_hub` is named in the pipelex-transport ALLOWED_SURFACE and spec, so renaming it means re-pinning `docs/specs/pipelex-transport-boundary.md` + `conformance/tests/pipelex_transport/test_data.py` + the pipelex-transport repo — fold that into B2, where every one of these module paths changes anyway (they move into `pipelex_kernel/`), so the transport boundary churns once, not twice | B2 |
-| Never rename | `runtime_bridge/` (the orchestration-venue sense of "runtime", and interpreter-layer anyway), `boot_orchestrator` semantics and its "boot as a Temporal runtime" prose, any runner-API "runtime" usage | — |
-
-## Part A — layer-gated plugin discovery
-
-### A0 — naming inventory + sweep
-
-Grep-driven inventory of every "runtime" occurrence in `pipelex/plugins/`, `pipelex/providers/`, `pipelex/interpreter_plugins/`, the closure tests, and the SPI docs; classify each hit into the three buckets above (the bucket table is the ruling; the inventory verifies it found everything and nothing extra). Apply the Part-A bucket as one mechanical commit. `make agent-check` + the renamed closure test green.
-
-#### A0 — as built
-
-Done. One commit, no behavior change — identifier and prose renames plus two test-module renames.
-
-**What the inventory found beyond the ruling's Part-A row**, and why each was folded in rather than deferred (the ruling's test is "one name for one boundary"; leaving any of these behind would have left the canonical statement of the boundary contradicting the code that enforces it):
-
-| Found | Bucket | Rename |
-| --- | --- | --- |
-| `hub_layering_guard.py`'s layer vocabulary | A — pure internal identifiers, pinned by no repo boundary | `RUNTIME_LAYER_PACKAGES` → `KERNEL_LAYER_PACKAGES`, `is_runtime_layer` → `is_kernel_layer` |
-| `docs/contribute/hub-layering.md` | A — the canonical human-readable definition of the layer | all layer prose; plus one new paragraph recording that `runtime_hub` / `runtime_boot` still carry the layer's former name and why they wait for Part B |
-| `tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py` | A — a closure test, same row as the import-closure one | file + `TestRuntimeLayerExceptionsAggregateGate` → `…Kernel…` |
-| `KERNEL_LAYER_ENTRY_POINTS`, `TestBootedRuntimeLayer`, and ~8 layer-named test functions | A — layer vocabulary in test names | mechanical |
-| layer-sense prose outside the five inventoried areas (`runtime_hub.py`, `runtime_boot.py`, `pipelex.py`, `core/`, `cogt/`, `kernel/`, `architecture-overview.md`, `pipelex-kernel.md`) | A — same vocabulary, same boundary | "runtime layer/-layer", "runtime half", "runtime closure", "runtime-only boot", "runtime adapters", "runtime-contributed" → kernel forms |
-| `.test_durations` — the CI shard-balancing snapshot keys on pytest node IDs, so a renamed file, class or test function makes it stale | A — data, but it names the renamed things | keys rewritten in place |
-
-**Left alone deliberately** (verified hit-by-hit, not by pattern): `runtime_bridge` and every "runtime" meaning the orchestration venue ("boot the process as its runtime", "a host runtime", "the Temporal worker runtime"); `RuntimeError` / `runtime_checkable` / `at runtime` / "an ordinary runtime condition"; `system/runtime.py` and `runtime_manager`; `setup_doctor_runtime`; `docs/under-the-hood/orchestrator-plugins.md`'s host-runtime prose; `CHANGELOG.md`'s released entries and everything under `wip/` (historical records — only the still-`[Unreleased]` kernel entries were re-worded, since they ship describing current reality).
-
-**Decisions taken**
-
-- **D-A0-1 — `runtime_hub` / `runtime_boot` keep their module names through Part A.** They are pinned across repo boundaries (`pipelex.runtime_hub` is in pipelex-transport's `ALLOWED_SURFACE` and its spec) and they move anyway in B2, so renaming them now would churn the transport boundary twice. `hub-layering.md` and `runtime_boot.py`'s header both say so out loud, so the mismatch reads as staged rather than as drift.
-- **D-A0-2 — the pipelex-temporal pointer rides A2's commit.** `pipelex-temporal/tests/unit/pipelex_temporal/test_plugin_interpreter_import_closure.py` names the canonical list's file twice (its `#:` comment and its failure message). That repo gets exactly one commit in Part A (A2), so the pointer fix lands there rather than as a stray commit — same window, per the ruling. ⚠ It is stale between A0 landing and A2 landing.
-
-**Verification** — `make check` green (ruff, plxt, pyright, mypy, pylint 10.00, keyword-only, hub-layering, drift). Full `make agent-test` green. Three drift contracts re-acked in the same commit — `cli-docs`, `hub-layering-convention`, `pipelex-kernel-docs`. The `/code-review` fan-out over A0 was skipped on Louis' instruction; CHECKPOINT A's review covers the whole of Part A.
-
-**Two traps the sweep hit, worth repeating in A1**
-
-- A bulk `runtime layer` → `kernel layer` rewrite also matches *inside* other words: it turned `doctor_cmd.py`'s "mirror runtime **layered** resolution" (the layered *config* resolution, nothing to do with the layer) into "kernel layered". Caught only because that file is a drift trigger and the plan forced a hit-by-hit read. Re-grep for `kernel layered|kernel-layered` after any further bulk pass.
-- **A rename is not done when the tree type-checks — `.test_durations` keys on node IDs.** `make check` and every targeted suite were green with the file still naming `test_runtime_layer_import_closure.py`; only the full `make agent-test` caught it, through `tests/unit/repo/test_test_durations_paths.py`, whose whole job is to notice that CI shards are being balanced against tests that cannot run. Fixed by rewriting the stale keys in place, each new key asserted present in a fresh collection first — regenerating would have rewritten the whole snapshot with fresh timings for a rename. Any A1–A3 rename of a test file, class or function owes the same pass.
-
-**Open** — none.
-
-### A1 — the group-split mechanism
-
-- Two entry-point groups replace the single `pipelex.plugins`: **`pipelex.plugins.kernel`** (inference backends, model listers, storage providers, secrets providers, HTTP-error mappers) and **`pipelex.plugins.interpreter`** (orchestrators, bundle validators, PipeFunc executors, interpreter-side hub-slot claims).
-- `build_registrar` gains an injected `entry_point_groups` parameter, symmetric with the existing `builtin_plugins` injection: the kernel-only boot passes the kernel group alone; the interpreter boot passes both. The discovery module itself keeps naming no layer-welding constant — the composed defaults live where the builtin lists live today.
-- **Menu-tier cross-check.** Classify each registrar menu method by tier (kernel-tier: `add_inference_backend`, `add_model_lister`, `add_storage_provider`, `add_secrets_provider`, `add_http_error_mapper`; interpreter-tier: `add_orchestrator`, `add_bundle_validator`, `add_pipe_func_executor`; slot claims classified per-slot). Discovery records which group a plugin arrived under, and the registrar fails loud when a kernel-group plugin calls an interpreter-tier menu method. This catches a plugin lying about its layer at register time — the import-contamination half is caught by the per-plugin guard tests (Part A world) and, in a greenlighted Part C world, by physics.
-- **Legacy-group probe, fail-loud.** Discovery also reads the retired `pipelex.plugins` group; any entry point found there raises with a migration message naming the plugin and the two new groups. Silent nondiscovery is the quiet failure mode this probe exists to prevent.
-- `PLUGIN_API_VERSION` bumps (breaking change to the plugin contract); `pipelex plugins list` gains the layer/group column.
-
-#### A1 — as built
-
-Done. One commit, tests first (the module was red on a missing `PluginGroup` before any mechanism existed), then the mechanism.
-
-`PluginGroup` is a `StrEnum` in its own module `pipelex/plugins/plugin_group.py` rather than in `contract.py`, because the registrar needs it at runtime (it is a `PluginDiscovery` field) while `contract.py` names the registrar back — pyright's `reportImportCycles` is an error here, and a third module is the honest break. `build_registrar` takes `entry_point_groups` as a required parameter, symmetric with `builtin_plugins`; the composed defaults are `KERNEL_ENTRY_POINT_GROUPS` in `providers/builtins.py` and `ENTRY_POINT_GROUPS` in `interpreter_plugins/builtins.py`, each beside the built-in manifest it belongs with.
-
-**Decisions taken**
-
-- **D-A1-1 — the cross-check is one-directional, and the Temporal plugin is what settles it.** A kernel-group plugin may not reach the interpreter tier; an interpreter-group plugin may contribute kernel-tier capabilities freely. A symmetric rule reads tidier but would reject our own Temporal plugin, which is interpreter-side (it contributes an orchestrator) *and* contributes an `add_http_error_mapper` — a kernel-tier capability by the plan's own classification. It would also be rejecting nothing dangerous: the risk is an interpreter-layer object being constructed in a kernel-only boot, and a kernel-only boot never loads the interpreter group at all. Pinned by a test that names the reason.
-- **D-A1-2 — hub-slot tiering is a property of the slot, not a flag at the call site.** `HubSlot.is_interpreter_layer` uses an exhaustive match, so a newly added slot cannot be merged without classifying it. The classification tracks where each claim is *applied* — `PIPE_ROUTER` / `PIPE_RUN` / `PIPE_FUNC_EXECUTOR` in `Pipelex.setup`, the rest in the kernel boot.
-- **D-A1-3 — built-ins carry no group and are exempt from the cross-check.** They are handed in as a list and filed by layer in-tree, where the hub-layering guard polices them statically; a kernel-only boot simply never passes the interpreter half. `PluginDiscovery.group` is `None` for them and `plugins list` shows `—`.
-- **D-A1-4 — `begin_plugin(group=...)` is required, not defaulted.** It costs a mechanical `group=None` at ~30 test call sites that construct a registrar directly, and it buys the guarantee that a future discovery path cannot silently mislabel an external plugin as a built-in and skip the cross-check.
-- **D-A1-5 — the retired-group probe runs on every build, whichever groups were asked for.** A plugin left under `pipelex.plugins` is broken in both boots, and the symptom without the probe — a capability simply absent, no error — is the expensive one to diagnose.
-
-**Verification** — `make agent-check` green end to end. The plugins/providers/cli unit suites, both closure tests and the plugin integration suites: all green. The three new gates were mutation-tested: neutering the tier cross-check killed all six violation cases, ignoring the requested groups killed both kernel-only-boot cases, and neutering the retired probe killed its own case — each restored green after.
-
-~~⚠ Owed at A3~~ — **discharged at A3**, see [A3 as built](#a3--as-built). Every doc telling a plugin author to publish under `[project.entry-points."pipelex.plugins"]` now names the right group.
-
-### A2 — migrate the external plugins
-
-Every currently-published external plugin is interpreter-layer, so all of them move to `pipelex.plugins.interpreter` and bump `targets_api`, each in one commit in its own repo: **pipelex-temporal** (orchestrator + bundle validator + slot claims), **pipelex-mistralai-workflows** (orchestrator), **pipelex-daytona-sandbox** (PipeFunc executor). The `pipelex.plugins.kernel` group starts with no external members — the future `pipelex-secrets-<backend>` / storage / inference-backend plugins are its intended population. Version pairing: each plugin repo's pipelex pin floor becomes the release that carries the new discovery; an older core will not see the new groups, which is acceptable under no-backward-compat but must be stated in each plugin's changelog.
-
-#### A2 — as built
-
-All three repos migrated, one commit each, all on a branch named `refactor/plugin-layer-groups`, **none pushed**:
-
-- **pipelex-mistralai-workflows** — `029b476`, off `dev`. Entry-point group in `pyproject.toml`, the plugin docstring, `docs/reference-activities.md`, and `tests/integration/test_plugin_discovery.py` (which asserts the declared group, so it is the migration's own gate). Changelog entry.
-- **pipelex-daytona-sandbox** — `a08d566`, off `dev`. Entry-point group in `pyproject.toml` and the plugin docstring. Changelog entry.
-- **pipelex-temporal** — `1ed047a`, off `refactor/Topology` per Louis' call (see D-A2-2). Entry-point group, the plugin docstring, `begin_plugin(group=…)` at both call sites in `test_temporal_plugin_http_error_mapper.py` (one of them inside the import-light subprocess script), the D-A0-2 pointer fix, the prose sweep (`README.md`, `AGENTS.md`, `CLAUDE.md`, `docs/index.md`, `docs/installation-and-activation.md`), and a changelog entry.
-
-`targets_api` needed no edit anywhere: all three plugins write `targets_api = PLUGIN_API_VERSION`, so the v4 bump follows the constant.
-
-**Verification** — each repo's suite was run against the A1 core, by installing this worktree editable into that repo's venv (`uv pip install --no-deps -e ../_kernel`) plus a `-e .` reinstall so the dist metadata picks up the new entry-point group, then restoring the pinned pipelex afterwards. pipelex-temporal: full unit suite green, including both subprocess arms (the import-light register and the cold-import closure) — the parts no linter can see. pipelex-mistralai-workflows: full suite green, including the entry-point assertion and the tests that boot pipelex, so the retired-group probe is satisfied by the new metadata. pipelex-daytona-sandbox: suite green, but it never exercises discovery, so its layer claim was checked directly instead (below).
-
-Each plugin's layer classification was also mutation-checked from the consumer side — registering under `PluginGroup.KERNEL` must fail: pipelex-temporal is refused on `orchestrator temporal`, pipelex-daytona-sandbox on `pipe_func executor daytona`. Both register cleanly under the interpreter group, and Temporal does so *while also* contributing its HTTP error mapper — the one-directional rule (D-A1-1) demonstrated end to end rather than argued.
-
-⚠ **Each plugin repo's venv is now red on its migration branch**, and correctly so: the working tree declares the new group while the pinned pipelex reads only the retired one. That is the release gate showing through, not breakage — `uv sync` in each repo once the release lands.
-
-**Decisions taken**
-
-- **D-A2-1 — the commits stay local until the pipelex release lands.** These plugins are now undiscoverable by *released* pipelex (0.42.0 reads only the retired group), so a pushed PR's CI would install 0.42.0 and go red for a reason no code change can fix. Same for the pipelex pin floor the plan asks for: the release that carries layer-split discovery does not exist yet, so `pipelex>=0.41.0` / `>=0.42.0` stay as they are and the floor bump is owed at release time, together with the push and the PRs.
-- **D-A2-2 — pipelex-temporal's commit is based on `refactor/Topology`** (Louis, 2026-08-10), resolving the question recorded in [`a2-pipelex-temporal-branch-question.md`](a2-pipelex-temporal-branch-question.md). It sits on its **own** `refactor/plugin-layer-groups` branch stacked on that base rather than being added to PR #18 itself: the base is what makes the D-A0-2 pointer fix possible at all (the file it corrects exists only there), while the separate branch keeps PR #18 untouched and preserves the one-Part-A-commit-per-repo property. Since the commit is release-gated anyway and cannot ship before #18, the entanglement costs nothing in practice. Once #18 merges to `dev`, this branch retargets to `dev` cleanly.
-- **D-A2-3 — no new entry-point-declaration test in pipelex-temporal or pipelex-daytona-sandbox.** Only pipelex-mistralai-workflows had one to update. Adding the other two would duplicate what A3's core-side fake-dist gate covers mechanically; the per-repo claim that matters (this plugin is interpreter-layer) is enforced by pipelex at register time, which the mutation check above confirms is live.
-
-### A3 — gates and checkpoint
-
-- **The mechanical gate:** a subprocess test with a fake interpreter-group plugin dist (entry-point fixture; its module raises or writes a sentinel on import) asserting a kernel-groups-only discovery never imports it, while a both-groups discovery does. Mutation-test it: point the kernel boot at both groups and watch it go red before trusting it.
-- Menu-tier cross-check tests (kernel-group plugin calling `add_orchestrator` → the structured error), legacy-probe test, and the existing suites: `make agent-check`, full `make agent-test`. *(The three plugin repos' own suites against an editable core were already run at A2 — see A2 as built.)*
-- Changelog entry for **core** — the three plugin repos already have theirs. Update the SPI docs and `plugins list` docs: `docs/under-the-hood/{inference-backend,orchestrator,storage-provider,secrets-provider}-plugins.md` and `docs/cookbook/using-inference-plugins.md` all still instruct authors to publish under the now-fatal `pipelex.plugins` group.
-
-#### A3 — as built
-
-- **The mechanical gate**: `tests/unit/pipelex/plugins/test_installed_plugin_group_isolation.py`. It writes a real `*.dist-info/` with an `entry_points.txt` declaring an interpreter-group plugin, puts it on `sys.path`, and runs discovery in a **cold subprocess**; the plugin module writes a sentinel file when its body executes. A kernel-only boot must leave the sentinel absent and discover nothing; a both-groups boot must produce the sentinel *and* register the plugin. Mutation-tested both ways: making `_external_entry_points` ignore its `groups` argument fails on the kernel-only arm (exit 2), and declaring the fixture under a group nobody queries fails on the vacuity arm (exit 4).
-- **Menu-tier cross-check tests, the legacy-probe test, and the group-filtering test already landed with A1** — the A3 checklist listed them, but building the mechanism without its tests was never on the table. A3 added only the gate A1 could not give: the one that uses real installed metadata instead of a patched `importlib.metadata`.
-- **Docs swept.** Each SPI page now names the group its capability belongs to — kernel for inference backends, storage and secrets; interpreter for orchestrators. `inference-backend-plugins.md` carries the full explanation (what each group means, what a wrong choice costs in each direction, that the retired group is a startup error) and the other pages link to it rather than repeat it. `orchestrator-plugins.md` additionally states the one-directional rule and why Temporal is the case that settles it. The three `pipelex plugins list` references now mention the Group column and that it is the first thing to read when a plugin is missing. The seam diagrams stopped naming the retired group.
-- **Changelog**: nothing owed. A1's entry already describes the split, the enforcement, its direction, the retired-group error and the Group column; A3 added a test and doc corrections, neither of which is release-facing on its own.
-
-**Decisions taken**
-
-- **D-A3-1 — the cookbook example plugin was migrated too, and it was not on the plan's list.** A workspace-wide sweep for `entry-points."pipelex.plugins"` (enumerating every sibling directory rather than trusting the plan's three-repo list) turned up a fourth consumer: `pipelex-cookbook`'s `hello-inference-plugin`. Migrated to `pipelex.plugins.kernel` — an inference backend is kernel-layer — as commit `87c6800` on a `refactor/plugin-layer-groups` branch off `dev`, **not pushed**, release-gated like the others (D-A2-1). Leaving it would also have made the `using-inference-plugins.md` page A3 just corrected describe an example that contradicts it.
-- **D-A3-2 — `pipelex.plugins` the *package* was deliberately left alone.** The retired entry-point group and the kernel-layer Python package share a spelling, and `docs/contribute/hub-layering.md` refers to the package repeatedly (the transitive-breach worked example). A blind sweep would have corrupted that page. Historical `CHANGELOG.md` entries were left alone for the same reason: they record what shipped at the time.
-- **D-A3-4 — pipelex-api was a fifth consumer, and the A2/A3 sweep predicate could not see it.** Both sweeps searched for `entry-points."pipelex.plugins"` *declarations*, which is what found the cookbook. pipelex-api declares no entry point — it **calls `build_registrar`**, and that function gained a required parameter. Its call site resolves at module scope (`HTTP_ERROR_MAPPERS = _resolve_http_error_mappers()`), so the omission is an import-time `TypeError` that takes the whole runner down, not a degraded feature. Verified red-green against the in-flight core: reverted, `import api.main` raises; restored, it imports and its full suite passes. A second instance of the same break lived in its test helper (`begin_plugin` also gained a required `group`), which only running that suite surfaced. **Lesson for any future entry-point or SPI-signature change: sweep for *callers of the changed function*, not only for declarations of the changed group — they are different populations and only one of them was covered.**
-- **D-A3-3 — no new `plugins list` reference page.** The command has never had one; the three SPI pages mention it in prose. Adding a CLI reference page is a real gap but a separate concern (it was already recorded against the `cli-docs` drift contract at A1), and inventing one here would have widened Part A past its subject.
-
-**Verification** — `make agent-check`, `make drift-check` (staged, since it reads the index) and the **full `make agent-test`** all green on the A3 tip.
-
-🛑 **CHECKPOINT A — reached 2026-08-10. Part A is complete and green; nothing is pushed.**
-
-**State.** Core: commits on `refactor/Kernel-4` in the `_kernel` worktree — A0 (`283abd7d2`), A1 (`529ca483f`), the A2 record (`47b21887e`, preceded by `b5da2c1fb`), A3 (`f6672b2d1`), plus the checkpoint-review fixes. **Five** downstream repos each hold one unpushed commit on a `refactor/plugin-layer-groups` branch: pipelex-mistralai-workflows `029b476`, pipelex-daytona-sandbox `a08d566`, pipelex-temporal `1ed047a` (based on `refactor/Topology`, D-A2-2), pipelex-cookbook `87c6800` (D-A3-1), pipelex-api `d5acdfb` (D-A3-4).
-
-**What ships together.** Part A is one core PR plus **five** downstream PRs, and they **cannot go first**: released pipelex reads only the retired group, so their CI would install it and go red for a reason no code change fixes (D-A2-1). Order: land the core PR, cut the pipelex release, then push the five branches, open their PRs, and bump each repo's pipelex pin in the same window. pipelex-temporal additionally waits on PR #18 (its base), which the release gate makes free.
-
-**Open at this checkpoint.**
-
-- The pipelex pin bumps in all five downstream repos — owed at release, deliberately not done now (D-A2-1). pipelex-api pins exactly (`==`), so it is a hard bump, not a floor.
-- Each downstream repo's venv is red on its migration branch until that release; `uv sync` after.
-- No `pipelex plugins list` CLI reference page exists (D-A3-3).
-- Review-deferred items and three open questions for Louis: [`plugin-group-split-deferred-items.md`](plugin-group-split-deferred-items.md).
-- Part B's open questions are unchanged and still Louis' — see [Open questions](#open-questions-louis). B is *not* started.
-
-## Part B — the in-repo `pipelex_kernel` package (unpublished)
-
-The kernel layer moves out of `pipelex/` into a top-level `pipelex_kernel/` package at the repo root, beside `pipelex/`. One repo, one distribution: the `pipelex` wheel ships both top-level packages, PyPI's surface is unchanged, and nothing new is published. What this buys on its own: the layer boundary becomes visible in the tree and in every import statement, and the one-way dependency becomes a one-line static rule — **nothing under `pipelex_kernel/` may import `pipelex`** — which is impossible to state that cleanly while the kernel lives inside the `pipelex` package.
-
-### B0 — footprint measurement (read-only, can start any time)
-
-Compute what the kernel package would actually contain and require: the kernel layer's module set (seeded by the kernel-layer import-closure test and the kernel boot contract's `sys.modules` sweep), its third-party dependency closure, and an install-size estimate. Deliverable: `wip/kernel/kernel-distribution-footprint.md`. This drives B1's content line now, and would inform a Part C greenlight and its extras design later: if the hard dependency set is small, the eventual headline ("look how little you need") is an asset; if provider plumbing drags heavy deps, extras (`pipelex-kernel[<backend>]`) would get designed before any publish, not after.
-
-#### B0 — as built
-
-Measured 2026-08-11 at the Part A end-state, three ways that agree where they overlap: a static import graph over every `pipelex/**/*.py`, a runtime `sys.modules` sweep of four boot scenarios in fresh subprocesses, and a dependency/size closure over installed distributions. Full numbers, method and caveats in [`kernel-distribution-footprint.md`](kernel-distribution-footprint.md) — not inlined here, per this plan's Checkpoint-B instruction.
-
-Four results change decisions this plan had already written down:
-
-- **The dependency headline is not "look how little you need."** A kernel core install is about two thirds of a full one, and its floor is dominated by four dependencies that owe nothing to the interpreter. A small headline for a hypothetical Part C has to be bought by extras design, not by the layer split — which reframes OQ-2 from "do we want extras" to "the core is where the weight is".
-- **D-B2's "the tools subset the closure actually reaches" should be retired.** Nearly all of `pipelex.tools` has a kernel-layer importer; the exceptions are a handful of modules. `pipelex.tools` moves whole.
-- **The content line gains four boundary decisions the plan did not name** — `pipelex.cli.exceptions` (which also blocks D-B4's "no CLI in the kernel package"), `pipelex.language.mthds_config` (a config-composition problem, not a file move), `pipelex.runtime_bridge.orchestration_mode`, and `pipelex.kit.paths` — alongside the top-level modules D-B2 did anticipate.
-- **The strongest argument for Part B turned out to be a gate argument, not a legibility one.** The declared kernel layer and the closure test's named interpreter packages do not partition the tree; every current cross-layer import lands in the unnamed remainder, which is precisely why every gate is green. D-B5's ban is the first rule stated over the package boundary rather than over a curated set of names, so it is the first one that closes that gap. One live breach found and deferred (KF-18 in [`deferred-follow-ups.md`](deferred-follow-ups.md)); two undeclared direct dependencies found, which are a latent break in `pipelex` today independent of Part B.
-
-B1 is unblocked: its content line is the declared kernel layer whole, plus five top-level modules, minus the four decisions above.
-
-### B1 — decisions
-
-- **D-B1 package layout:** top-level package `pipelex_kernel/` at the repo root, beside `pipelex/`. A `pipelex.kernel` namespace stitch is rejected — `pipelex` is a regular package, two wheels cannot co-own it (which would matter the moment a Part C split the dist), and the family convention (pipelex_temporal precedent, decision D8 of the plugin externalization) is top-level packages.
-- **D-B2 the content line:** which packages move (kernel façade, plugin mechanism + registries, providers, boot, config/system, base exceptions, urls, the tools subset the closure actually reaches, telemetry) — driven by B0's measurement, not by intuition. Anything the kernel-layer closure does not reach stays in `pipelex`.
-- **D-B3 kernel-consumer import surface:** code written against the kernel imports `pipelex_kernel.*` from B2 onward. Any tooling that generates such code, and any existing kernel-consuming code, re-targets its imports in one window after B2 (see Sequencing). A greenlighted Part C would change nothing about imports.
-- **D-B4 CLI:** the kernel package ships no user CLI (the kernel is a library surface; `pipelex` keeps the CLI). Revisit only if B0 surfaces a real need.
-- **D-B5 the layering ban's form:** a static AST scan over `pipelex_kernel/**` rejecting any `import pipelex` / `from pipelex` (deterministic and total), plus a cold-import closure check (importing any `pipelex_kernel` module in a fresh subprocess never brings a `pipelex.*` module into `sys.modules`). Both run in `make agent-check`-adjacent gates and CI.
-
-### B2 — the move + gates
-
-`git mv` the kernel-layer packages into `pipelex_kernel/` and repoint every import, folding in the Part-B rename bucket (`RuntimeBoot` → `KernelBoot`, the runtime hub under its kernel name). Known move-consequence classes to work through deliberately (the kernel-extraction plan's "What Phase 1 taught Phase 2" applies):
-
-- **Transport boundary:** any module named in `docs/specs/pipelex-transport-boundary.md` / the conformance `ALLOWED_SURFACE` that moves gets re-pinned in the same change — spec, conformance test data, the pipelex-transport repo, and the two commercial plugins that import it; run `make check-spec-links` in conformance.
-- **Path-scoped tooling must widen or it goes quiet:** every gate whose scope is a path list silently stops policing moved code unless extended to `pipelex_kernel/` — the keyword-only guard, the hub-layering guard, the error-class location/uniqueness tooling and doc generators, import-light tests, coverage config, ruff/pyright/mypy/isort package settings, Makefile targets. Enumerate them as part of the move, don't discover them by absence.
-- **Packaging config:** the `pipelex` wheel explicitly ships both top-level packages; `py.typed` in the new package; verify the built wheel installs and imports cleanly from a scratch venv.
-- **Subject grants:** `subject_grants.toml` keys on file paths — re-key every grant whose def moved (the kernel façade itself is zero-grants; the moved tools/config modules are not).
-- **Drift contracts:** `drift.toml` triggers referencing moved paths; stage before `drift-ack` (the digest reads the git index).
-- **Error identity:** regenerate error pages and the error-identity snapshot after the move; class names don't change, so the wire `error_type` is stable — verify the snapshot diff is paths-only.
-- **Test-tree reconciliation:** tests for moved modules move to a parallel `pipelex_kernel` test tree (Phase-5 temporal reconciliation is the precedent, including the shared-fixture split).
-- **Downstream import sweeps:** enumerate the workspace directory for consumers (do not work from a remembered list) — the three plugin repos repoint `pipelex.<kernel-layer>` imports to `pipelex_kernel.*` when they bump their pins past B2, and update their copied interpreter-package guard lists; sweep every other `pipelex` importer for moved-path imports.
-- The layering ban (D-B5) lands in the same change as the move and is mutation-tested (add a forbidden import, watch it go red).
-
-🛑 **CHECKPOINT B** — shippable as a normal `pipelex` release: breaking import paths (minor bump), wheel ships two top-level packages, PyPI surface unchanged. Record status, the as-built content line, and B0's measured numbers (by pointing at the footprint doc, not inlining them). **This is the plan's committed end-state** — anything beyond it is Part C, which needs its own greenlight.
-
-## Part C — the `pipelex-kernel` distribution (HYPOTHETICAL — needs an explicit greenlight)
-
-**Nothing in this part is decided.** It is written down so the option is concrete when the greenlight question is asked; no phase here starts without Louis' explicit go, and Part B stands complete without it. If greenlighted, it would be packaging-only: no code moves, no import statements change — `pipelex_kernel` would get its own pyproject and become the published distribution `pipelex-kernel`, with `pipelex` depending on it in lockstep.
-
-### C0 — the greenlight
-
-The decision this plan does not make: registering the public `pipelex-kernel` name is a commitment. A greenlight resolves OQ-1 (supported public surface vs documented internal substrate) and OQ-2 (extras at first publish, from B0's numbers), with Louis. Absent it, Part B remains the end-state indefinitely.
-
-### C1 — the distribution split
-
-- Two pyprojects under a uv workspace (exact member layout decided here; any directory shuffle is packaging-only — imports are already `pipelex_kernel.*`); lockstep version, `pipelex` depends on `pipelex-kernel==<same version>`; wheel-metadata check that no editable/path pin leaks into `Requires-Dist` (the pipelex-temporal Phase-5 verification is the template).
-- Release flow: one release cut publishes `pipelex-kernel` first, then `pipelex`; the release skill gains the two-dist ordering.
-
-### C2 — the physical gate + proof
-
-- **The physical gate:** a CI job that syncs a venv with *only* `pipelex-kernel` and its test deps — where `import pipelex` is a `ModuleNotFoundError` — and runs the kernel test suite plus the keyless boot contract there. This supersedes the static ban and closure tests as the primary boundary enforcement (they remain as fast in-repo guards).
-- **The proof, in a clean venue:** fresh venv, install `pipelex-kernel` (wheel or index), run a kernel-only consumer, sweep `sys.modules` — the interpreter count is structurally zero because the interpreter is not installed. Any trust-base measurement is re-run there; never quote a closure number taken in a venv that also has full `pipelex` (the lesson that started all this).
-- Docs: `docs/under-the-hood/pipelex-kernel.md` gains the distribution story; public docs get the install surface; changelogs across every touched repo. Downstream installs are otherwise unaffected — `pipelex` still pulls everything in; kernel-only consumers may now thin their install.
-
-🛑 **CHECKPOINT C** — record the published versions, the clean-venue proof, and any support-surface decisions.
-
-## Sequencing and gates
-
-- **Part A is unblocked now** and lands on `dev` independently. The kernel stack is merged; nothing in A waits on anything.
-- **B0 can run any time** (read-only measurement); **B1/B2 start after Checkpoint A** so the group split and naming are settled before module paths churn.
-- **Part B is a normal release and the plan's committed end-state** — a legitimate place to stop indefinitely. Only the clean-venue story and the install headline would wait on a greenlighted C; nothing else downstream blocks on it.
-- **Part C is hypothetical until explicitly greenlighted (C0)** — it is the irreversible step, which is exactly why B exists as its own stage and why this plan commits to nothing beyond B.
-- **The kernel-consumer churn window:** anything written against the kernel API re-targets its imports to `pipelex_kernel.*` when it bumps its pipelex pin past B2. Consumers with their own pending sweeps should schedule the pin bump so all their kernel-facing churn lands in one window; a consumer that must move sooner sweeps twice — acceptable, but say so out loud when it happens.
-- **`refactor/Topology` (PR #1008)** is the one branch in flight on top of dev. Overlap checked (2026-08-10): none of Part A's code footprint is touched by it; the only shared file is `docs/under-the-hood/orchestrator-plugins.md` (its prose is in A0's sweep). Land #1008 before starting A0 and the overlap disappears entirely; if A0 goes first, expect one trivial doc conflict there.
-- Version semantics: Part A is breaking on the plugin contract → minor bump (pre-1.0 convention). Part B is breaking on import paths everywhere → minor bump, and the release that carries it should carry nothing else surprising. A greenlighted Part C would publish a new dist and re-shape `pipelex`'s dependency metadata → minor bump.
-
-## Enforcement model across the parts
-
-| Threat | Before | After A | After B | After C (if greenlighted) |
-| --- | --- | --- | --- | --- |
-| Our plugin imports the interpreter at module scope | per-plugin guard test (subprocess cold-import) | same, plus never loaded by a kernel boot | same | import fails in a kernel-only venv |
-| Third-party plugin drags the interpreter | nothing (discovery loads every installed plugin) | not loaded by a kernel boot (wrong group); fail-loud if it lies via menu calls | same (a venv with full `pipelex` still carries the interpreter) | uninstallable in a kernel-only venv (its dep on `pipelex` cannot resolve) |
-| Plugin declares the wrong layer | n/a (no layer axis for externals) | menu-tier cross-check fails loud at register | same | same, plus physics |
-| Kernel code quietly imports the interpreter | closure tests + boot-contract sweep (per-function, has missed an entry point before) | same, under the kernel-layer name | statically impossible to merge (the one-line ban over `pipelex_kernel/`) + cold-import closure | the kernel-only CI venv makes it a hard ImportError |
-
-## Risks and traps
-
-- **Silent nondiscovery** is the failure mode of retiring an entry-point group — the legacy probe exists to convert it to a loud error; don't drop the probe as "cleanup" later without a deliberate decision.
-- **Path-scoped gates go quieter on omission** — a guard whose path list doesn't include `pipelex_kernel/` reports nothing about it, which reads as clean. B2's tooling-widening bullet is the antidote; verify each widened gate by mutation, not by green.
-- **Copied guard lists drift quietly** (pipelex-temporal's interpreter-package list is a copy of the canonical one) — every rename in this plan that touches the canonical list or its filename must update the copies and their pointers in the same window.
-- **Stale `*.egg-info` shadows entry points** during editable development — if entry points are "not discovered" locally, remove stale root egg-info before debugging anything else.
-- **Any module move must grep pipelex-transport and its spec/conformance pair** (workspace rule) — B2's biggest cross-repo obligation.
-- **Sweeps enumerate the directory, not a remembered repo list**, and workspace-root recursive greps silently return nothing across sibling repos — loop over the repos explicitly.
-- **Closure numbers are per-venue** — Part B does not change what a full-`pipelex` venv contains; the only quotable measurement remains one taken in a kernel-only venv, which would exist only after a greenlighted C.
-
-## Open questions (Louis)
-
-1. **OQ-1 public commitment (this IS the Part C greenlight):** publishing `pipelex-kernel` to PyPI invites third parties to build on the kernel API directly. Is the kernel a supported public surface, or primarily an internal substrate (documented as such)? Part B proceeds without answering this, and Part C does not exist until it is answered with a yes.
-2. **OQ-2 extras design (only if Part C is greenlighted):** if B0 shows provider plumbing dragging heavy optional deps, do we want per-backend extras on `pipelex-kernel` at first publish, or a minimal core with extras added on demand?
-3. **OQ-3 timing vs kernel-consumer tracks:** for work in flight that consumes the kernel API, should B2 land first (so new consumers are born targeting `pipelex_kernel.*`), or should those tracks proceed on the current import surface and sweep later?
diff --git a/wip/kernel/plugin-group-split-deferred-items.md b/wip/kernel/plugin-group-split-deferred-items.md
deleted file mode 100644
index 82f73b4e9..000000000
--- a/wip/kernel/plugin-group-split-deferred-items.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# Plugin group split — deferred items
-
-Raised by the Checkpoint A review of the entry-point group split (Part A of the kernel track). Each item below was verified against the code and judged **not** worth fixing inside Part A — either because it is a design question that is Louis' to rule on, or because the remedy is machinery bought for a path nothing can reach yet. Items the review raised that *were* fixed in Part A are not listed here.
-
-One review finding was checked and **rejected**: the claim that `PluginGroup` could live in `contract.py` because `contract.py`'s import of `PluginRegistrar` is `TYPE_CHECKING`-only. pyright's `reportImportCycles` (an error in this repo) flags `TYPE_CHECKING` cycles too — verified empirically by adding a runtime `contract` import to `registrar.py` and running pyright, which reported `Cycle detected in import chain`. The separate `plugin_group.py` module and its stated rationale are correct as they stand.
-
----
-
-## D-1 — The retired-group probe pre-empts the `plugins.disabled` denylist
-
-**What.** `build_registrar` runs `_reject_retired_entry_point_group()` as its first statement, before it reads `config.plugins.disabled`. So the documented recovery path — "denylisted by their entry-point name *before* `load()`, so a broken installed plugin can still be disabled to recover startup" — does not cover this one failure class.
-
-**Why it matters.** An operator with some third-party plugin still published under `pipelex.plugins` gets `RetiredPluginEntryPointGroupError` on every pipelex process in that venv, and `plugins.disabled` cannot quiet it. `pipelex plugins list` — the tool the docs point at when a plugin is missing — also calls `build_registrar`, so the diagnostic is dead too. Recovery is uninstall or upgrade.
-
-**Why not fixed here.** It is a deliberate ordering, not an oversight: the probe exists precisely because silent nondiscovery is the expensive failure, and honouring the denylist would let an operator re-create that silence. But the asymmetry with a promise made in three SPI doc pages deserves an explicit ruling rather than an implicit one. The error message was widened in Part A to name the two actions actually available to an operator (upgrade, uninstall).
-
-**If revisited.** Filtering the probe's straggler list through `plugins.disabled` is a two-line change. The question is whether "I disabled it, let me boot" should beat "you have an unmigrated plugin and would otherwise not notice".
-
----
-
-## D-2 — The split governs registration, not imports
-
-**What.** The group split guarantees that a kernel-only boot does not *query* the interpreter group, plus a menu-tier check on what a kernel-group plugin may register. Nothing constrains what a **kernel-group** plugin's module *imports*.
-
-**Why it matters.** A third-party plugin published under `pipelex.plugins.kernel` that registers only an inference backend, but has `from pipelex.pipe_run import ...` at module scope, is loaded by a kernel-only boot and drags the interpreter in — the exact shape of the contamination that motivated this track. The plan is honest about this ("that fix protects only plugins we author"); Part A softened the CHANGELOG wording to match, so no shipped text now claims more than is enforced.
-
-**Why not fixed here.** Closing it means an import-closure rule over third-party code — a fundamentally different mechanism from a declaration, with real cost (importing the plugin to inspect its closure is itself the thing being prevented, so it needs a subprocess or a static walk). That is Part C territory and is explicitly gated on Louis' greenlight.
-
----
-
-## D-3 — The menu-tier cross-check is attribution-based
-
-**What.** `_require_interpreter_layer` reads `self._active.group`, and `_active` is whatever `begin_plugin` last set. A plugin that stashes the registrar during `register` and calls a menu method *later* — from a `make_worker` closure, or a factory thunk invoked at a boot apply-point — is checked against whichever plugin registered last.
-
-**Consequence.** The deferred call passes if the last-registered plugin was interpreter-group, and names the wrong plugin in the error if not.
-
-**Why not fixed here.** This requires the plugin to violate the documented "`register` is side-effect-free" invariant, which is stated in every SPI page. It is a hardening note, not a live bug. If revisited, binding the check to the discovery object handed to the plugin (rather than to registrar state) removes the ordering dependence entirely.
-
----
-
-## D-4 — A plugin published under both groups produces a self-referential duplicate error
-
-**What.** `_external_entry_points` iterates groups and yields an entry point once per group, so a distribution declaring itself in both is discovered twice. The second registration hits `_add` and raises e.g. `DuplicateInferenceBackendError(first_plugin="acme", second_plugin="acme")` — *"registered by both plugin 'acme' and plugin 'acme'"*.
-
-**Why not fixed here.** It is loud, so nothing silently misbehaves; only the message misleads. A dedupe by entry-point name, or a distinct `PluginPublishedUnderBothGroupsError`, would be clearer. Untested either way today.
-
----
-
-## D-5 — `PluginDiscovery.group is None` is an unenforced invariant
-
-**What.** `group: PluginGroup | None` encodes "built-in", which `origin` already encodes. Nothing asserts `group is None ⟺ origin is BUILTIN`, and `_require_interpreter_layer` silently skips when `group is None`.
-
-**Why it matters.** Not reachable through `build_registrar` today — every external path passes a group. But a future refactor that forgets to thread `group` degrades the cross-check to a no-op *silently* rather than loudly. Several tests construct `origin=EXTERNAL, group=None`, a state production cannot produce.
-
-**If revisited.** Either derive the group from origin at construction, or assert the pairing in `begin_plugin`. Both are small; the question is whether two fields should encode one fact at all.
-
----
-
-## D-6 — `INTERPRETER_TIER_CALLS` has no mechanical link to the menu
-
-**What.** The `claim_*` half of the cross-check is mechanical (the guard lives in `_claim`, so a new slot is covered automatically and the exhaustive match forces a classification). The `add_*` half is three hand-placed `_require_interpreter_layer` calls.
-
-**Consequence.** Adding a new interpreter-tier menu method without the guard call is caught by nothing — the test dict simply does not grow.
-
-**Why not fixed here.** The mechanical remedy (walking the registrar's public methods in a test) is more machinery than the exposure justifies for three call sites. A comment on the three `add_*` methods pointing at the dict would carry most of the value.
-
----
-
-## D-7 — The plugins unit tests are coupled to the developer's installed environment
-
-**What.** The retired-group probe reads the real venv and is not stubbable at the seam the tests patch (`_external_entry_points`). And `test_installed_plugin_group_isolation` asserts a both-groups discovery registers **exactly** the synthetic fixture.
-
-**Consequence, and it is live during this change window.** A developer with an unmigrated plugin editable-installed sees the whole plugins test tree fail with `RetiredPluginEntryPointGroupError`; one with a *migrated* plugin installed sees the isolation test fail on an exit code whose message does not say "you have a plugin installed". The paired-branch release ordering makes both states normal until the plugin repos land.
-
-**If revisited.** Asserting the fixture is *among* the discoveries rather than the sole one removes half of it; making the probe injectable removes the rest.
-
----
-
-## D-8 — `PluginLayerViolationError`'s "before anything it contributed is wired"
-
-The docstring claims the violation is caught before any contribution is wired. The test asserts the exception and its message fragments, not the ordering — moving `_require_interpreter_layer` after `_add` in all three methods would stay green. Low practical impact (the registrar is discarded when `build_registrar` raises), but the docstring makes a claim nothing holds up.
-
----
-
-## Open questions — Louis' to rule on
-
-### OQ-1 — Is `TASK_MANAGER` correctly classified as kernel-tier? — **RESOLVED: yes, and the docstring was what was wrong**
-
-`HubSlot.is_interpreter_layer` gave two criteria and presented them as coinciding: *"whether claiming this slot means handing back a `Pipe`-aware object"* and *"which is also where the claim is applied"*. For `TASK_MANAGER` they arguably did not. The claim is applied in the kernel boot, which says kernel-tier; but the only real claimant stands up a Temporal worker registering workflows over pipes, which reads Pipe-aware.
-
-The question was: whether any conceivable task-manager implementation can be built without naming an interpreter type. It can, and one already ships. Three findings:
-
-- **`TASK_MANAGER` is the only slot whose return core discards.** The kernel boot's apply-point invokes the thunk and drops the result; every other slot flows its value back into core (four through `_resolve_hub_slot`, `ISOLATED_EXECUTION_PROBE` through `set_isolated_execution_probe`). So the "hands back a `Pipe`-aware object" criterion is not False for this slot — it is *inapplicable*. There is no returned object to classify.
-- **Kernel-only worker scopes already exist.** Our Temporal plugin's per-backend runner scopes each disable all workflows, require no task pack, and name only leaf content-generation activities. That is a task manager standing up a worker serving purely kernel-tier work — the one-worker-pool-per-backend-class deployment.
-- **Those activities name only kernel-layer modules** — `pipelex.cogt.content_generation.*`, `pipelex.core.stuffs.image_content`, `pipelex.runtime_hub`. No `Pipe` type on that path.
-
-**Ruling:** `TASK_MANAGER` stays kernel-tier. No code change, no SPI change, nothing release-gated — a kernel-group plugin claiming it to stand up a specialized runner pool is coherent, and a kernel-only boot applying that claim serves real work.
-
-The remedy inverts what this entry proposed. The first criterion cannot govern, because for this slot there is nothing handed back; the apply-point is the only criterion every slot has. The `is_interpreter_layer` docstring now leads with the apply-point and names `TASK_MANAGER` as the reason the returned-type reading corroborates but cannot decide. What made the slot read Pipe-aware is that our plugin's *catalog* names pipe workflows at module import — that is the catalog handed to the task manager, not the slot's contract, and that plugin is interpreter-group anyway.
-
-### OQ-2 — Should the retired-group probe be permanent?
-
-The repo rule is "no backward compatibility — just change it". The probe is a permanent, un-disableable, per-boot metadata scan whose only job is to catch a migration that completes when the paired releases land. For: fail-loud beats silent nondiscovery, and the cost is one cached `entry_points()` call. Against: it is a compat artifact with no expiry, it adds a third metadata scan to every `build_registrar` (which the runner API executes at import), and it creates the unrecoverable state in D-1.
-
-**What would settle it:** whether any *published* distribution outside this workspace declares `pipelex.plugins`. If it is only ours — all migrated in the same window — the probe could carry a "remove after vX.Y" marker rather than living forever.
-
-### OQ-3 — Does `pipelex.plugins.plugin_group` belong in the documented SPI symbol list?
-
-Plugin authors declare their group in `pyproject.toml` and never import the enum. But a plugin that unit-tests its own `register` must construct a registrar, and `begin_plugin` now requires `group=` — so the enum is a de-facto *test-surface* dependency for any plugin with its own tests. Our own Temporal plugin imports it for exactly that reason. Whether a test-surface dependency belongs in the versioned SPI list is a policy call.
diff --git a/wip/layer-placement-completion.md b/wip/layer-placement-completion.md
deleted file mode 100644
index 3fd846cd6..000000000
--- a/wip/layer-placement-completion.md
+++ /dev/null
@@ -1,269 +0,0 @@
-# Complete the layer boundary — placement, so the predicate can say what it means
-
-**Status: DONE — this is the PR's guide, not an open plan.** Implemented on `refactor/Layer-boundary`, off `dev` at `123d81f3b`, in three commits (one per phase boundary). Every number below was measured on that tree, and every measurement was re-run after each phase; the recipes are inline so a reviewer can reproduce any claim in two minutes without external tooling. The one remaining open item is [Phase 4](#phase-4--cross-repo-release-gated), which is release-gated by construction and folded into a sweep that was already open.
-
-## For a reviewer, in one screen
-
-The hub split drew the runtime/interpreter boundary and made it enforceable. It shipped with a caveat repeated in **six** places: two interpreter packages could not be named in the closure test's predicate, so *"importing the runtime loads zero interpreter modules"* was really *"zero modules from the packages we can name"*. This PR removes the caveat by fixing what caused it, and the measurement turned up one thing the deferral did not know.
-
-**Two findings, two commits, one theme — placement, not indirection.**
-
-1. **`graph` was never an interpreter package, and being undeclared was hiding a live breach** (commit 1). `graph/graph_rendering.py` reached `interpreter_hub` through `pipeline.dry_run_pipeline` — 77 interpreter modules — with every gate green, because both the layer rule and the transitive rule filter candidates through `is_runtime_layer` and `pipelex.graph` was not declared. **An undeclared package is not neutral, it is unpoliced.** Fixed by splitting the module along the boundary's own question ("do I need a loaded method?") and declaring the four packages that measure clean.
-2. **Four leaf models were filed in the wrong package** (commit 2). They are what put `pipeline` and `pipe_run` in every runtime closure. Moved to runtime-layer homes, then the predicate widened — the same remedy `mthds_parsing` used, and the reason the fix is a move rather than an exclusion.
-
-**What to check hardest, if you only check three things:**
-
-- **The declaration additions are claims, and they are pinned.** `test_the_measured_clean_packages_stay_declared` fails if any of the four names is dropped; negative control run. Without it, deleting an entry left the whole suite green — the exact regression this PR exists to close.
-- **The property is now unqualified.** `INTERPRETER_PACKAGES` names every interpreter package with no exclusion; measurement command 1 returns zero `pipeline` / `pipe_run` modules for all nine runtime entry points. The negative control (`pipelex.interpreter_hub` as an entry point) still fails with an offender list, so the test is not passing vacuously.
-- **`PipeRunError` deliberately does not follow the other three leaves into `system/`.** That is a judgement call, argued in the [D-1 deviation](#deviation-from-d-1-recorded), and one earlier justification for it was **measured false and removed** — see that note.
-
-**Roughly 170 files, but almost all of it is mechanical.** The substantive diff is: `pipelex/graph/graph_rendering.py`, `pipelex/pipeline/bundle_graph_rendering.py` (new), `pipelex/cli/dev_cli/commands/hub_layering_guard.py`, `pipelex/system/pipe_run_mode.py` + `pipe_run_param_key.py` (new/moved), the `PipeRunError` hunk in `pipelex/core/pipes/exceptions.py`, `tests/unit/pipelex/test_runtime_layer_import_closure.py`, and `docs/contribute/hub-layering.md`. Everything else is a one-line import swap, and a missed one is an `ImportError`, never a silent wrong resolution.
-
-**No behavior changes.** Nothing in this PR changes what any code does — only where it lives and what the guard is allowed to see.
-
-**What this finishes.** The hub split drew the boundary and made it enforceable. It left one thing undone, and the track recorded it honestly rather than fixing it: three top-level packages could not be named in the closure test's `INTERPRETER_PACKAGES`, so the property the whole track exists to state — *importing the runtime loads zero interpreter modules* — still ships with a caveat. The caveat is not repeated in four places, as [`../refactoring/deferred-placement-follow-ups.md`](refactoring/deferred-placement-follow-ups.md) §3 estimated; it is repeated in **six**, and a caveat repeated six times is a caveat that will go stale in at least one. This plan removes it.
-
-The measurement also turned up something the deferral did not know: one of those three packages is not an interpreter package at all, and it is hiding a module that loads the entire interpreter.
-
-## Related documents
-
-- [`pr-1062-review-notes.md`](pr-1062-review-notes.md) §1 — where the leak was first recorded, from the Codex thread on the closure test. **Partly stale**: it names `core.bundles.exceptions` as the awkward case, and that module no longer exists — the modularity refactors moved it to `core.exceptions`, and it is no longer part of the problem.
-- [`../refactoring/deferred-placement-follow-ups.md`](refactoring/deferred-placement-follow-ups.md) §3 — the same leak, restated after M1, with the remedy named ("move the leaf models to a runtime-layer home, *then* widen the predicate"). This plan is that remedy, measured.
-- [`hub-split-tracker.md`](hub/hub-split-tracker.md) → [Cross-repo sweep](hub/hub-split-tracker.md#cross-repo-sweep) — **still open and release-gated.** This track's cross-repo work is the same shape and must merge into that sweep rather than open a second one. See [Cross-repo](#cross-repo--fold-into-the-pending-hub-sweep).
-- [`docs/contribute/hub-layering.md`](../docs/contribute/hub-layering.md) — the shipped specification. It is the thing this plan edits at the end, not the thing it works around.
-
-## The measurement — reproduce it in two minutes
-
-Everything below rests on three commands run from the `pipelex/` worktree.
-
-**1. What leaks into a runtime closure.** For any entry point, which modules of the three suspect packages get loaded:
-
-```bash
-.venv/bin/python -c "
-import sys, importlib
-importlib.import_module('pipelex.core.stuffs.stuff_factory')
-print(sorted(m for m in sys.modules if m.startswith(('pipelex.pipeline','pipelex.pipe_run','pipelex.graph'))))
-"
-```
-
-**2. Every module-level edge from the declared runtime layer into them** — the authoritative work list, because the closure is just this list plus transitive fallout:
-
-```bash
-grep -rn --include='*.py' -E '^from pipelex\.(pipeline|pipe_run|graph)[.a-z_]* import|^import pipelex\.(pipeline|pipe_run|graph)' \
- pipelex/cogt pipelex/core pipelex/plugins pipelex/providers pipelex/reporting \
- pipelex/system pipelex/tools pipelex/tracing pipelex/runtime_hub.py pipelex/config.py
-```
-
-**3. Whether an undeclared package is secretly clean (or secretly dirty)** — import each of its modules in a fresh subprocess and count interpreter modules loaded:
-
-```bash
-.venv/bin/python - <<'EOF'
-import subprocess, sys, pathlib
-INTERP = ('pipelex.libraries','pipelex.pipe_operators','pipelex.pipe_controllers','pipelex.codegen',
- 'pipelex.builder','pipelex.interpreter_plugins','pipelex.pipe_machinery','pipelex.pipe_signature',
- 'pipelex.mthds_parsing','pipelex.interpreter_hub')
-script = f"import sys, importlib; importlib.import_module(sys.argv[1]); print(len([m for m in sys.modules if m.startswith({INTERP!r})]))"
-for pkg in ("graph", "tracing", "observer", "errors"):
- for f in sorted(pathlib.Path("pipelex", pkg).rglob("*.py")):
- if f.name == "__init__.py":
- continue
- mod = str(f.with_suffix("")).replace("/", ".")
- n = subprocess.run([sys.executable, "-c", script, mod], capture_output=True, text=True).stdout.strip()
- if n not in ("0", ""):
- print(f"{n:>6} {mod}")
-EOF
-```
-
-Command 3 is the one that changed this plan's shape. Run it before trusting anything below.
-
-## What actually leaked
-
-Command 2 returns exactly nine edges, from eight files. This is the complete surface — there is no long tail:
-
-| # | Importer (declared runtime layer) | Imports | Resolution |
-| --- | --- | --- | --- |
-| 1 | `cogt/content_generation/cogt_run_params.py` | `pipe_run.pipe_run_mode.PipeRunMode` | **move the leaf** |
-| 2 | `core/pipes/inputs/exceptions.py` | `pipe_run.pipe_run_mode.PipeRunMode` | **move the leaf** |
-| 3 | `core/pipes/inputs/exceptions.py` | `pipe_run.exceptions.PipeRunError` | **move the leaf** |
-| 4 | `core/concepts/concept_structure_blueprint.py` | `pipe_run.pipe_run_params.PipeRunParamKey` | **move the leaf** |
-| 5 | `core/pipes/pipe_output.py` | `pipeline.pipeline_models.SpecialPipelineId` | **move the leaf** |
-| 6 | `core/pipes/pipe_output.py` | `graph.graphspec.GraphSpec` | **declare `graph`** |
-| 7 | `system/configuration/configs.py` | `graph.graph_config.GraphConfig` | **declare `graph`** |
-| 8 | `tracing/trace_events.py` | `graph.graphspec.{EdgeKind, ErrorSpec, IOSpec, NodeKind}` | **declare `graph`** |
-| 9 | `tracing/graphspec_assembler.py` | `graph.graphspec.*` | **declare `graph`** |
-
-Two different problems wearing one label. Four of the nine are not a placement wart at all — they are a **missing declaration**, and the fix costs nothing. The other five are the real leaves.
-
-Everything else in the closures is transitive fallout from these nine. In particular the longest chain — `pipeline.exceptions` → `pipeline.validation_errors` → `pipeline.fixes.planner` — is reached *only* through edge 4, via `pipe_run_params.py`'s import of `PipeStackOverflowError`. Cut edge 4 and the whole chain leaves every runtime closure without being touched.
-
-## Part 1 — `graph` and `tracing` are runtime-layer, and one module is lying about it
-
-**The finding.** Command 3, run over every module in `graph/`, `tracing/`, `observer/` and `errors/`, returns exactly one offender:
-
-```
- 77 pipelex.graph.graph_rendering
-```
-
-Every other module in all four packages loads **zero** interpreter modules. `graph/` imports no interpreter package anywhere except that one file; `tracing/`, `observer/` and `errors/` import none at all.
-
-So `graph` was never an interpreter package. It is the run-graph data model (`graphspec.py`), the tracer, the renderers and their config — all of it machinery present at execution time whatever is loaded, which is the runtime layer's own definition. It sat outside both declarations because nobody measured it, and the closure test could not name it because `graphspec` is in every runtime closure — which reads as a leak only if you have already assumed the package is interpreter-layer. It isn't. Edges 6–9 are correct imports that needed a declaration, not a refactor.
-
-**The hidden breach.** `graph/graph_rendering.py` imports `pipeline.dry_run_pipeline`, and importing it pulls in `interpreter_hub` and 76 more interpreter modules. It has passed every gate to date for a reason worth stating: the layer rule and the transitive rule both filter their candidates through `is_runtime_layer`, and `pipelex.graph` is not declared — so *omitting a package makes the guard quieter, not louder*. The guard's own note says exactly this. `graph_rendering` has been outside the rule's domain the whole time.
-
-This is the same shape as the `pipelex.plugins` breach the transitive rule was built to catch, and it is the argument for declaring these packages rather than leaving them undeclared: an undeclared package is not neutral, it is unpoliced.
-
-**The module splits cleanly.** Its two importers are both CLI (`cli/commands/graph_cmd.py`, `cli/agent_cli/commands/validate/bundle_cmd.py`), and its contents fall on either side of the line by themselves:
-
-- Runtime-layer, imports nothing but `graph/` + `config` + `tools`: `GraphFormat`, `_sanitize_graph_name`, `render_graph_from_spec` (takes a `GraphSpec`, renders it).
-- Interpreter-layer, needs `dry_run_pipeline`: `_dry_run_bundle`, `generate_graph_for_bundle`, `generate_view_for_bundle` (take a *bundle*, dry-run it, then render).
-
-The split is along "do I need a loaded method?", which is the layer boundary's own question.
-
-## Part 2 — the four leaves in `pipeline` and `pipe_run`
-
-Unlike `graph`, these two are genuinely interpreter-layer. Measured by counting module-level imports of interpreter packages:
-
-| package | modules importing the interpreter | verdict |
-| --- | --- | --- |
-| `pipeline` | 14 of 32 (`validate_bundle`, `resolve_bundle`, `controller_taint`, `fixes/fix_loop`, `execution_seams`, `bundle_validator`, `runner`, …) | solidly interpreter |
-| `pipe_run` | 3 of 15 (`pipe_job`, `pipe_job_factory`, `dry_run_in_process`) | straddles |
-| `graph` | 1 of 27 (`graph_rendering`) | runtime, with one tenant in the wrong house |
-
-The symbols the runtime layer actually needs out of the two interpreter packages:
-
-| symbol | today | size | who needs it from the runtime layer |
-| --- | --- | --- | --- |
-| `SpecialPipelineId` | `pipeline/pipeline_models.py` — the whole module | 6 lines, one `StrEnum` | `core/pipes/pipe_output.py` |
-| `PipeRunMode` | `pipe_run/pipe_run_mode.py` — the whole module | 34 lines, one `StrEnum` + three properties | `cogt/content_generation/cogt_run_params.py`, `core/pipes/inputs/exceptions.py` |
-| `PipeRunParamKey` | inside `pipe_run/pipe_run_params.py` (255 lines) | 2-member `StrEnum` + `value_list()` | `core/concepts/concept_structure_blueprint.py`, for its reserved-names list |
-| `PipeRunError` | inside `pipe_run/exceptions.py` (106 lines, 11 classes) | one `PipelexError` subclass | `core/pipes/inputs/exceptions.py`, as a base class |
-
-Two are whole tiny modules that move as-is. Two are single symbols inside larger modules and need extracting.
-
-**A note on `pipe_run/exceptions.py`.** `AsyncExecutionNotEnabledError`'s docstring, in that same file, says *"it lives in core precisely because it is the shared contract between the runner API … and any async-execution backend plugin"*. It does not live in core. That docstring is evidence the module's placement was already thought to be wrong once, and it is a free doc fix whichever way D-2 goes.
-
-## Decisions — settled, with the two that moved
-
-Recorded as drafted. Two were revised during implementation and both revisions are noted inline at the phase that made them: **D-3** (`_sanitize_graph_name` moved with its only caller rather than staying behind) and **D-1** (`PipeRunError` did not follow the other three leaves into `system/`). D-2, D-4 and D-5 landed exactly as recommended.
-
-
-- **D-1 — destination for the relocated leaves.** Recommended: **`pipelex/system/`**. This is not a new judgment call, it is the precedent the hub track already set — `JobMetadata` moved to `system/job_metadata.py`, `TraceContext` to `system/trace_context.py`, `DataInclusionConfig` to `system/data_inclusion_config.py`, all for exactly this reason. The alternative, `pipelex/core/`, reads worse: `core/` is documented as describing *what a method's values are*, and a run mode is not a value.
-- **D-2 — `pipe_run`: move the leaves, or split the package the way `core/` was split?** Recommended: **move the leaves.** The split is superficially attractive (only 3 of 15 modules touch the interpreter, and `core/` → `pipe_machinery` is the precedent), but the measurement kills it: declaring `pipe_run` runtime-layer would put `pipe_run_params.py` inside the declaration, and it imports `PipeStackOverflowError` from `pipeline.exceptions` — so the split *also* requires relocating the `pipeline.exceptions` → `validation_errors` → `fixes.planner` chain, which the leaf-move approach removes from the closure for free. The split is strictly more work and strictly more cross-repo churn (`pipe_job` is on the `pipelex-transport` `ALLOWED_SURFACE` and is imported by four sibling repos). Take the leaves.
-- **D-3 — where `graph_rendering.py`'s two halves go.** Recommended: **split it.** The pure half (`GraphFormat`, `render_graph_from_spec`, `_sanitize_graph_name`) stays in `graph/`; the bundle-driven half (`_dry_run_bundle`, `generate_graph_for_bundle`, `generate_view_for_bundle`) moves to `pipelex/pipeline/`, next to the `dry_run_pipeline` it exists to wrap. The alternative — move the whole file to `cli/` because both importers are CLI — is worse: it would strand `render_graph_from_spec`, which is a genuine runtime-layer renderer, behind a CLI import path.
-- **D-4 — how far to extend the declaration.** `graph` and `tracing` are required by this plan. `observer` and `errors` are measured equally clean and are cheap to add in the same commit; `kit` is data files and `language` has interpreter edges, so both stay out. Recommended: declare `graph`, `tracing`, `observer`, `errors` — a partial declaration is what let `graph_rendering` hide, and the fix is to stop leaving measured-clean packages unpoliced.
-- **D-5 — does the closure test name `graph` in `INTERPRETER_PACKAGES`?** No — that is the point of Part 1. `graph` moves into `RUNTIME_LAYER_PACKAGES`; only `pipeline` and `pipe_run` get added to `INTERPRETER_PACKAGES`. Recorded as a decision because [`pr-1062-review-notes.md`](pr-1062-review-notes.md) and the deferred-placement note both list `graph` alongside the other two, and a reader coming from those docs will expect it on the wrong side.
-
-## Phases
-
-### Phase 1 — declare the clean packages, and evict the one tenant that isn't
-
-- [x] 1.1 Split `graph/graph_rendering.py` per D-3: bundle-driven helpers to `pipelex/pipeline/bundle_graph_rendering.py`, pure renderer stays. Updated the one affected CLI import site (`bundle_cmd.py`; `graph_cmd.py` only wanted `render_graph_from_spec`, which stayed) and moved the four bundle-half test modules from `tests/unit/pipelex/graph/` to `tests/unit/pipelex/pipeline/`.
-- [x] 1.2 Add `pipelex.graph`, `pipelex.tracing`, `pipelex.observer`, `pipelex.errors` to `RUNTIME_LAYER_PACKAGES` in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`, and extend the tuple's note to say why each is there.
-- [x] 1.3 `make check-hub-layering` passes. **Negative control run and recorded**: re-adding the `pipeline.dry_run_pipeline` import to `graph/graph_rendering.py` makes the guard fail with `interpreter-hub-transitive` at `pipelex/graph/graph_rendering.py:14`, chain `pipelex.pipeline.dry_run_pipeline → pipelex.pipeline.runner → pipelex.interpreter_hub`. Before 1.2 that same file produced no finding at all.
-- [x] 1.4 Re-ran measurement command 3 over the four newly-declared packages: no output.
-
-**Deviation from D-3, recorded.** `_sanitize_graph_name` moved with the bundle half rather than staying in `graph/`. It is a private helper whose only caller is `generate_graph_for_bundle`; leaving it behind would have meant either dead code in `graph/` or promoting it to a public cross-module symbol to buy nothing. The layer argument for keeping it is untouched — it needs no loaded method — it just has no reason to live apart from its caller.
-
-**Added at review, beyond the plan.** Two findings from the checkpoint review, both accepted:
-
-- **The four new declarations are now pinned by a test.** `test_the_measured_clean_packages_stay_declared` asserts their membership in `RUNTIME_LAYER_PACKAGES`. Without it, deleting an entry left the whole suite green — which is precisely the failure this track exists to close, and the guard's own note already claimed the declaration "is asserted by a test". Mirrors the existing `test_the_plugin_split_left_both_halves_declared`; negative control run (dropping `pipelex.tracing` fails it).
-- **Test placement follow-through.** `tests/CLAUDE.md`'s `pipelex/pipeline/` row listed no unit path, so the four relocated modules landed outside the documented targeted-test route; the row now names `tests/unit/pipelex/pipeline/`. And `test_graph_rendering.py` — which tests `pipelex.graph.graph_rendering` — moved from `tests/unit/pipelex/cli/` to `tests/unit/pipelex/graph/`, where the mapping says it belongs and where the name is now free. It became load-bearing in this change: the bundle-side test stopped asserting the inclusion-flag mapping (that is the renderer's business, not the dispatcher's), so it is the only place that covers it.
-
-**🛑 CHECKPOINT 1** — the four packages are declared, policed, and clean; nothing in `pipeline`/`pipe_run` has moved yet. Gates: `make agent-check`, `make check-hub-layering`, full `make agent-test`. This is a coherent unit and a natural handoff: it is defensible on its own (it closes a live unpoliced breach), and it is the half with no cross-repo consequences at all — `graph_rendering`'s only importers are in this repo. Land it before opening Part 2.
-
-### Phase 2 — relocate the four leaves
-
-- [x] 2.1 `SpecialPipelineId` → `pipelex/system/job_metadata.py`; `pipeline/pipeline_models.py` deleted.
-- [x] 2.2 `pipe_run/pipe_run_mode.py` → `pipelex/system/pipe_run_mode.py`, whole module, every in-repo import site rewritten (the widest one).
-- [x] 2.3 `PipeRunParamKey` extracted to `pipelex/system/pipe_run_param_key.py`.
-- [x] 2.4 `PipeRunError` → `pipelex/core/pipes/exceptions.py`. **No sibling in `pipe_run/exceptions.py` subclasses it** — `PipeJobError`, `DeliveryError`, `PipeRouterError` and the rest all derive from `PipelexError` directly — so nothing travels with it and no import back up is needed. `AsyncExecutionNotEnabledError`'s stale "it lives in core" docstring corrected.
-- [x] 2.5 Measurement command 1 re-run for every entry point in `RUNTIME_LAYER_ENTRY_POINTS`: **zero `pipeline` and zero `pipe_run` modules in all nine.** The residue is `pipelex.graph.*`, which Phase 1 made runtime-layer — exactly what exit criterion 2 predicts. Measurement command 2 is down from nine edges to five, all into `graph`.
-
-<a id="deviation-from-d-1-recorded"></a>
-
-**Deviation from D-1, recorded.** D-1 recommended `pipelex/system/` for all four leaves; three went there, `PipeRunError` did not. Consistency of destination is not the criterion — what the symbol *is* decides. Three are run-scope directives and enums, which is the `JobMetadata` / `TraceContext` precedent D-1 cites. The fourth is the base class of two runtime-layer errors (`PipeRunInputsError`, `OptionalValueAbsentError` in `core.pipes.inputs.exceptions`), so it belongs with the pipe-error family in `core/pipes/exceptions.py` — and filing it there also lands it in the same error-reference section as those two subclasses, where `system/` would have put the base one section away from them. (A `system/exceptions.py` placement was first argued against on the grounds that the config bootstrap would then load `pipe_run_mode` → `graph.graphspec` for nothing. **That argument is false and was dropped**: measured, `import pipelex.config` already loads both, through `runtime_hub` → `content_generator_protocol` → `assignment_models` → `cogt_run_params`. The subclass relationship is the whole reason.) `SpecialPipelineId` likewise folded into `system/job_metadata.py` rather than getting a module of its own: it is the vocabulary of `pipeline_run_id`, which is `JobMetadata`'s field, and that module already hosts two sibling enums.
-
-### Phase 3 — widen the predicate and delete the caveat
-
-- [x] 3.1 `pipeline` and `pipe_run` added to `INTERPRETER_PACKAGES`, after 2.5 measured clean.
-- [x] 3.2 The closure test's module docstring now states the property unqualified, and records where each leaf went.
-- [x] 3.3 Caveat deleted at all **six** sites (the doc's machine-checked `INTERPRETER = {…}` snippet was a seventh edit, forced by `test_the_interpreter_package_set_matches_the_documented_one`). The deferred-placement note said four; it is six, and missing one leaves a doc claiming a wart that no longer exists:
- - `pipelex/runtime_hub.py` — module docstring ("Two interpreter-named packages are deliberately absent…").
- - `pipelex/cli/dev_cli/commands/hub_layering_guard.py` — the `RUNTIME_LAYER_PACKAGES` note ("`core.pipes.pipe_output` does still pull in `pipeline.pipeline_models`…").
- - `tests/unit/pipelex/test_runtime_layer_import_closure.py` — the `INTERPRETER_PACKAGES` note (3.2 above).
- - `docs/contribute/hub-layering.md` — "Two interpreter-named packages are deliberately **not** on the list".
- - `docs/contribute/hub-layering.md` — "Where core splits", the parenthetical on `core.pipes.pipe_output`.
- - `docs/contribute/hub-layering.md` — "The property — the import-closure test", "What the predicate still cannot name is `pipeline` and `pipe_run`".
-- [x] 3.4 `docs/contribute/hub-layering.md` gains the positive statements this track earned: `graph`/`tracing`/`observer`/`errors` are runtime-layer and why; the `graph_rendering` eviction goes in "Known inversions" as a *fixed* one, next to the `pipelex.plugins` worked example it rhymes with — including the lesson, which is the sharpest one this track produced: **an undeclared package is not neutral, it is unpoliced.**
-- [x] 3.5 CHANGELOG: breaking. Public import paths move for `SpecialPipelineId`, `PipeRunMode`, `PipeRunParamKey`, `PipeRunError`, and for `graph_rendering`'s bundle helpers. Give the old → new table.
-
-**🛑 CHECKPOINT 2** — the property is unqualified: every runtime entry point loads zero modules from any interpreter package, stated by a predicate that names them all. Gates: `make agent-check`, `make check-hub-layering`, full `make agent-test`, `make drift-check`.
-
-### Phase 4 — cross-repo, release-gated
-
-- [x] 4.1 Folded into the pending hub cross-repo sweep rather than opening a second one: [`hub/hub-split-tracker.md` → Third wave](hub/hub-split-tracker.md#third-wave--the-layer-placement-track-refactorlayer-boundary) carries the old→new table and the per-repo counts, re-measured 2026-07-29.
-- [ ] 4.2 **Open, and gated on a release** — execute that sweep. Nothing to do until a `pipelex` version carrying these moves is published; until then every consumer is correct on its pinned version.
-
-**🛑 CHECKPOINT 3 — not reached, by design.** The sweep is the hub track's, it was already open before this PR, and it closes when both waves ship together. This PR does not and cannot close it.
-
-## Cross-repo — fold into the pending hub sweep
-
-The hub track's own [cross-repo sweep](hub/hub-split-tracker.md#cross-repo-sweep) is **still open and release-gated**, and the evidence is easy to see: `conformance/tests/pipelex_transport/test_data.py`'s `ALLOWED_SURFACE` still pins `pipelex.pipeline.job_metadata` and `pipelex.graph.trace_context` — both of which moved to `pipelex/system/` when the hub split landed. Several sibling repos are on the same stale paths.
-
-So this track must not open a second sweep. Its moves get added to the existing one, and both go out on the same release.
-
-Consumers found by grepping the workspace (`grep -rn --include='*.py' -E 'from pipelex\.(pipeline|pipe_run|graph)' <repo>`) — re-run at sweep time, this is a 2026-07-29 snapshot:
-
-| repo | what it imports | affected by this track |
-| --- | --- | --- |
-| `cocode/` | `pipe_run.pipe_run_mode.PipeRunMode` in five CLI modules | **yes — the widest consumer of a moved symbol** |
-| `pipelex-cookbook/` | `pipe_run.pipe_run_mode.PipeRunMode` (two files), `pipe_run.pipe_run_params.FORCE_DRY_RUN_MODE_ENV_KEY` | **yes** |
-| `conformance/` | `ALLOWED_SURFACE` pins `pipe_run.*`, `pipeline.job_metadata`, `graph.trace_context` | **yes — plus the stale hub-track entries** |
-| `pipelex-api/` | `graph.graphspec.GraphSpec`, `pipe_run.exceptions.DryRunError`, `pipe_run.pipe_job`, `pipeline.runner` | check `DryRunError` under D-2's split |
-| `pipelex-transport/` | `pipe_run.pipe_job`, `pipe_run.pipe_run_params_factory`, `pipeline.job_metadata` | only if D-2 goes the other way |
-| `pipelex-daytona-sandbox/` | `pipe_run.pipe_run_params`, `pipeline.job_metadata` | only via the stale hub-track paths |
-| `pipelex-mistralai-workflows/` | `graph.trace_context`, `graph.graph_config`, `graph.graph_tracer_manager`, `pipe_run.*` | `graph.*` paths are **unchanged** by this track (Part 1 declares, it does not move) |
-| `pipelex-temporal/` (private) | `pipe_run.pipe_run_mode` (36 files), `pipeline.pipeline_models` | **yes — by far the largest consumer**, and the only importer of the deleted `pipeline_models` |
-
-⚠ **This table is the 2026-07-29 draft snapshot and is superseded.** It was assembled from a hand-written repo list and undercounts: the authoritative, re-measured work list is [`hub/hub-split-tracker.md` → Third wave](hub/hub-split-tracker.md#third-wave--the-layer-placement-track-refactorlayer-boundary), which adds `test-bed`, `pipelex-workshop`, `pipelex-demos` and the three `pipelex-demo-*` repos. Enumerate the workspace directory when re-measuring; do not hand-list it.
-
-Worth stating plainly, because it is the main reason D-2 recommends the leaf move: **Part 1 changes no public import path at all** apart from `graph_rendering`'s bundle helpers, whose only importers are in this repo. All the cross-repo cost lives in Part 2, and the leaf move is the variant that minimizes it.
-
-## Exit criteria — measured, not asserted
-
-All six re-measured on the final tree. A reviewer can re-run any of them from the repo root.
-
-1. ✅ Measurement command 1 returns zero `pipeline` / `pipe_run` modules for every entry point in `RUNTIME_LAYER_ENTRY_POINTS`. (The literal `[]` the draft asked for was the wrong bar: the command's prefix filter also matches `pipelex.graph`, which Part 1 made runtime-layer, so `graph.graphspec` legitimately remains in eight of the nine closures.)
-2. ✅ Measurement command 2 is down from nine edges to five, all into `graph`.
-3. ✅ Measurement command 3 returns no output over `graph/`, `tracing/`, `observer/`, `errors/`.
-4. ✅ `INTERPRETER_PACKAGES` names `pipeline` and `pipe_run`; the closure test is green; its negative control (`pipelex.interpreter_hub` as an entry point) still fails with an offender list.
-5. ✅ `make check-hub-layering` passes with the four new packages in `RUNTIME_LAYER_PACKAGES` — and, unlike before, *fails* when the evicted import is put back (negative control, recorded under 1.3).
-6. ✅ That grep returns one hit, and it is a *different*, still-live inversion (`get_pipe_func_executor_registry`, documented as unfixed). Nothing about the `pipeline` / `pipe_run` placement caveat survives anywhere.
-
-## What the review found, and what it changed
-
-Each phase was reviewed by an agent given only the diff — no plan, no rationale. Both rounds found real things, and both are worth a reviewer's attention because they are the kind of gap the plan itself could not have caught.
-
-**Round 1 (commit 1).** The four new declarations were pinned by nothing: dropping any of them left the entire suite green, while the guard's own note claimed "the declaration is asserted by a test". That is the same failure mode this PR exists to close, one level up — so it earned a test rather than a note. Second finding: the four relocated test modules landed in `tests/unit/pipelex/pipeline/`, which `tests/CLAUDE.md` did not list, so the documented targeted-test route stopped covering them.
-
-**Round 2 (commit 2).** Two published doc snippets still carried `from pipelex.pipe_run.pipe_run_mode import PipeRunMode` and would now raise `ImportError` for a reader copy-pasting them; the generated error-reference pages were stale after `PipeRunError` changed module (`make gep`); and — the one that mattered — **a justification stated in the CHANGELOG, in `hub-layering.md` and in a drift ack was measured false.** The claim was that filing `PipeRunError` in `system/exceptions.py` would make the config bootstrap load a run mode and `graph.graphspec` for nothing. Measured: `import pipelex.config` already loads both, via `runtime_hub → content_generator_protocol → assignment_models → cogt_run_params`. The alternative's stated cost was zero. The clause was removed from all three places and the drift ack re-recorded, because an ack arguing from a measurement nobody took is precisely what that system exists to prevent. The placement is unchanged and never needed the argument — the subclass relationship is the whole reason.
-
-**Round 3 (the whole PR, gstack `/review`).** Verdict was *ship, no blockers*, and the findings were all P2/P3 — but one of them is the most interesting thing this track produced, because it is a live counter-example to the claim the track exists to strengthen.
-
-- **Five built-in vendor adapters were pulling the entire interpreter into `pipelex.providers` — a package the declaration already claimed was clean.** `providers/{anthropic,bedrock,google,mistral}/*_list.py` imported `MissingDependencyError` from `pipelex.exceptions`, the *public all-errors aggregate*, instead of from its definition site `pipelex.system.exceptions`. That aggregate re-exports every interpreter package's exceptions, so each of the five loaded 15 interpreter modules. It survived because it needed two independent blind spots and had both: the guard's rules only chase `interpreter_hub`, which an aggregate of exception classes never reaches; and the closure test's `providers.builtins` entry point does not cover these modules, because the vendor plugins import them *inside a function* — a deferred import is invisible to the static graph and to the aggregator's runtime closure at once. Fixed at the import site (the repo's "direct full-path imports everywhere" rule already forbade it), plus `providers.anthropic.anthropic_list` as a tenth entry point, with a negative control. The generalization now recorded in "Known inversions": **a module that re-exports across layers is a layer boundary with the sign filed off.**
-- **`pipelex.test_extras` was measured clean, shipped, imported at boot — and undeclared**, while the guard's exclusion sentence named two packages and read as exhaustive. Declared, and the sentence now accounts for every top-level package. (`config`, `base_exceptions` and `urls` are also clean and undeclared; they were considered and left alone, because the transitive rule already covers them through their 30/32/5 declared runtime-layer importers. `test_extras` had no such cover.)
-- **The cross-repo sweep list was incomplete, and the way it was incomplete is the lesson.** The first pass iterated a *hardcoded* repo list and missed six repos with real breaking sites — `test-bed`, `pipelex-workshop`, `pipelex-demos` and three `pipelex-demo-*`. A repo absent from both the affected and the cleared column reads exactly like one that was checked and cleared. The tracker now says: enumerate the workspace directory, do not hand-list it.
-- Three bookkeeping fixes: a provenance comment in `pipelex/exceptions.py` that this PR itself made stale, the matched-set measurement snippet in `refactoring/modularity-refactors.md` (which a prescribed script check should have caught), and `refactoring/deferred-placement-follow-ups.md` §3, now marked resolved — its estimate of four caveat sites was also low, which is that section's own point about repeated caveats proving themselves.
-
-One question was deliberately **not** answered, and is deferred: [`inputs/error-reference-grouping-axis.md`](inputs/error-reference-grouping-axis.md). Moving `PipeRunError` to `core.pipes.exceptions` refiles it from "Execution & runtime" to "Authoring & language" in the public error reference, because the generator keys on the module's second dotted segment. That is *consistent* — its two subclasses were already filed there, so the base now sits beside them instead of a section away — but whether that section is right for any of the three is a pre-existing product question, and every fix for it is bigger than the problem.
-
-## Reproducing the whole thing
-
-```bash
-make agent-check # ruff, pyright, mypy, keyword-only, hub-layering
-make check-hub-layering # the guard on its own
-make agent-test # full suite
-make drift-check # the two review obligations this PR discharges
-```
-
-All green on the final tree. The two drift acks (`cli-docs`, `hub-layering-convention`) are committed alongside the change they cover, with their dogfood-log entries in [`drift-contracts/dogfood-log.md`](drift-contracts/dogfood-log.md).
diff --git a/wip/native-date-time/README.md b/wip/native-date-time/README.md
index 713c54b3b..ba1240d95 100644
--- a/wip/native-date-time/README.md
+++ b/wip/native-date-time/README.md
@@ -9,10 +9,10 @@ Tracks the work behind [PR #1089](https://github.com/Pipelex/pipelex/pull/1089)
| `what-we-built.html` | The write-up for co-developers — root cause, the fix, what the review uncovered, and what breaks for authors. Start here. |
| `bug-report.md` | The original report, filed from `mthds-ui` while adding native-concept fixture coverage. |
| `plan-and-review-log.md` | The working plan (was `TODOS.md` at the repo root) plus the decision record: every accept and decline across six bot rounds and the final independent review, with the reasoning. |
-| `doc-sweep-deferred.md` | Two cross-repo doc items deliberately left out of the PR, both release-gated. |
+| `doc-sweep-deferred.md` | The cross-repo doc item deliberately left out of the PR, release-gated. (A second item from the same review concerns another repo and is tracked at workspace level.) |
## Still open
- `mthds-ui` (`feature/Native-concepts_stories`): `make fixtures-live ONLY=pipeline_32` replaces the placeholder LIVE fixture with real data — the end-to-end regression check. Gated on a released pipelex carrying the fix.
- Optional pre-release sanity check: run a gateway `PipeLLM` with `output = "Time"` / `Date[]` against the production path.
-- The two items in `doc-sweep-deferred.md`.
+- The item in `doc-sweep-deferred.md`.
diff --git a/wip/native-date-time/doc-sweep-deferred.md b/wip/native-date-time/doc-sweep-deferred.md
index bb57007f9..189a38940 100644
--- a/wip/native-date-time/doc-sweep-deferred.md
+++ b/wip/native-date-time/doc-sweep-deferred.md
@@ -1,10 +1,10 @@
# Deferred: propagate the `Date` / `Time` ISO contract to the docs a model reads
-Deferred out of the `fix/Native-date-time` work (PR #1089). Both items are cross-repo and release-gated — neither is a code defect in `pipelex`, and neither blocks that PR.
+Deferred out of the `fix/Native-date-time` work (PR #1089). Cross-repo and release-gated — not a code defect in `pipelex`, and it does not block that PR. A second deferred item from the same review concerns another repo entirely and is tracked at workspace level.
-Background: the fix gave the `Date` and `Time` natives one ISO 8601 contract, owned by `pipelex/core/stuffs/iso_temporal.py` and shared by the content models and `StuffContentFactory`. The natives now accept the **extended** forms only, and refuse the end-of-day `24:00` spelling. See `TODOS.md` in this repo for the full plan and the round-by-round review decisions.
+Background: the fix gave the `Date` and `Time` natives one ISO 8601 contract, owned by `pipelex/core/stuffs/iso_temporal.py` and shared by the content models and `StuffContentFactory`. The natives now accept the **extended** forms only, and refuse the end-of-day `24:00` spelling. See [plan-and-review-log.md](plan-and-review-log.md) for the full plan and the round-by-round review decisions.
-## 1. The authoring guidance still says plain "ISO 8601"
+## The authoring guidance still says plain "ISO 8601"
`mthds-plugins/mthds/skills/shared/native-content-types.md` (and its sibling copies in the other plugin targets) describes `Date` and `Time` without mentioning the extended-only rule or the `24:00` refusal.
@@ -12,8 +12,3 @@ Why it matters: that file is part of what an LLM is prompted with when authoring
Do it when a released `pipelex` carries the fix, alongside the other release-gated plugin sweeps.
-## 2. `pipelex-app`'s date-format note documents a runtime model that is already false
-
-`pipelex-app/src/lib/run-form/date-format.ts` states in its header — explicitly as "measured, not assumed" — that pydantic accepts `"2026-07-06T00:00:00Z"` for `native.Date`'s `date` field. It does not: the datetime-shaped-string guard on `DateContent.date` rejects it, and rejected it before this PR too.
-
-No wire impact, and nothing to fix in behavior: `asCalendarDate` normalizes to a bare `YYYY-MM-DD` before sending, and the app emits no time-of-day values at all. This is a stale comment that predates the branch. Correct it the next time that file is touched.
diff --git a/wip/native-date-time/plan-and-review-log.md b/wip/native-date-time/plan-and-review-log.md
index e3e4d09ed..a5d14e9df 100644
--- a/wip/native-date-time/plan-and-review-log.md
+++ b/wip/native-date-time/plan-and-review-log.md
@@ -96,7 +96,7 @@ Verdict: ship with nits. No correctness hole; the parser's home and shape were j
- **`_make_time_content` swallowed the parser's specific message** where its `Date` sibling appended it, so a `Time` author got a generic shape hint instead of "24:00 names the next day's midnight". Now consistent.
- **The CHANGELOG entry did not carry `(Breaking)`** although authored inputs genuinely got stricter (`"15:40:00+0200"`, `"2026-07-07T154000"`, `"24:00:00"`, padding). Marked, with the refused forms named.
- **Pre-existing:** the datetime guard fires for both fields but its message named only `date`. Reworded to fit either field.
-- **Deferred to `doc-sweep-deferred.md` (this folder):** the plugin authoring guidance an LLM reads still says plain "ISO 8601" (cross-repo, release-gated, costs a re-ask not a failure), and a stale `pipelex-app` comment that has no wire impact.
+- **Deferred to `doc-sweep-deferred.md` (this folder):** the plugin authoring guidance an LLM reads still says plain "ISO 8601" (cross-repo, release-gated, costs a re-ask not a failure). A second deferred item belongs to another repo entirely and is tracked at workspace level.
## Follow-ups (out of this repo, after release)
diff --git a/wip/optionals/README.md b/wip/optionals/README.md
index a75b03024..3ed8835e6 100644
--- a/wip/optionals/README.md
+++ b/wip/optionals/README.md
@@ -2,23 +2,22 @@
## Where things stand
-**Phase 1 (the language core) is COMPLETE** — all steps A–F landed, final checkpoint cleared. The authoritative record is [optionals-phase1-tracker.md](optionals-phase1-tracker.md) (archived from the worktree-root `TODOS.md`; checkpoint log, decisions/deviations, hand-off notes). PR #1021 → dev is merge-ready; Louis merges.
+**Phase 1 (the language core) is COMPLETE** — all steps A–F landed, final checkpoint cleared. The authoritative record — checkpoint log, decisions/deviations, hand-off notes — is kept at workspace level, because most of what it logs is the cross-repo landing. PR #1021 → dev is merge-ready; Louis merges.
**Decided:** `??` coalescing is pulled forward from phase 3 into phase 2 — it is the ergonomic replacement for the `continue` pass-through that phase 1 broke (design doc §13 migration note, §17 phasing).
## What comes next — three streams
-1. **Release + conformance de-gate — DONE (pipelex 0.38.0 / pipelex-api 0.8.0).** The gate-removal checklist in [deferred-step-f-notes.md](deferred-step-f-notes.md) was run against the released runtimes: `OPTIONALS_PENDING_FEATURE` removed, six QA cases generated, probe-skips dropped, whole optionals conformance surface green on both arms. The same pin bump also required reconciling the (separate) PipeSignature-tag retirement in the conformance signature fixtures — see the deferred-step-f note for that + the follow-ups it surfaced (plxt schema propagation, the stale `pipelex#996` gate, the `-L`-path static-pass categorization bug).
-2. **Cross-repo optionals wave — plan to write.** Scope: mthds spec pages, mthds-python `absences` ledger on `DictWorkingMemoryAbstract` (un-gates the `_run_core_api.py` absent arm back here), mthds-js type mirrors, mthds-ui (skipped nodes, optional edges, `skip_reason`, the `conceptRefs.ts` parse-to-null bug), vscode-pipelex (grammar, semantic tokens, the Rust `strip_concept_qualifiers` bug), pipelex-api response models (`warnings` + contract `optional` flags), mthds-plugins skills. **Gated:** lands after the Required-main-stuff Phase 3 sweep (same mthds spec pages) and the release — except the two syntax-highlighting handoffs, which are ungated and already written up (workspace root `../wip/optionals/`).
+1. **Release + spec-suite de-gate — DONE (pipelex 0.38.0 / pipelex-api 0.8.0).** The gate-removal checklist (kept at workspace level; the outcome is recorded in [deferred-step-f-notes.md](deferred-step-f-notes.md)) was run against the released runtimes: the pending-feature marker removed, six QA cases generated, probe-skips dropped, the whole optionals surface of our cross-repo spec suite green on both arms. The same pin bump also required reconciling the (separate) PipeSignature-tag retirement in that suite's signature fixtures — see the deferred-step-f note for that + the follow-ups it surfaced (plxt schema propagation, the stale `pipelex#996` gate, the `-L`-path static-pass categorization bug).
+2. **Cross-repo optionals wave — plan to write.** Scope: mthds spec pages, mthds-python `absences` ledger on `DictWorkingMemoryAbstract` (un-gates the `_run_core_api.py` absent arm back here), mthds-js type mirrors, mthds-ui (skipped nodes, optional edges, `skip_reason`, the `conceptRefs.ts` parse-to-null bug), vscode-pipelex (grammar, semantic tokens, the Rust `strip_concept_qualifiers` bug), pipelex-api response models (`warnings` + contract `optional` flags), mthds-plugins skills. **Gated:** lands after the Required-main-stuff Phase 3 sweep (same mthds spec pages) and the release — except the two syntax-highlighting handoffs, which are ungated and already written up at workspace level.
3. **Phase 2 — plan to write, in-repo and ungated.** The PipeLLM/`Text?` maybe-wrapper with reasons + `??` coalescing (per the decision above). Candidate rider: the PipeBatch ledger-parity observability question from the Step F notes.
## Documents
- [optionals-design.md](optionals-design.md) — the design reference: decisions D1–D11, phasing (§17), decision summary. Still authoritative for future phases.
- [optionals-plan.md](optionals-plan.md) — the phase-1 narrative plan (steps A–F). CLOSED; kept as the record the tracker implements.
-- [optionals-phase1-tracker.md](optionals-phase1-tracker.md) — the phase-1 tracker (checkpoint log, decisions/deviations log, cold-start context). CLOSED; archived here from the worktree-root `TODOS.md` now that phase 1 is done.
-- [deferred-step-f-notes.md](deferred-step-f-notes.md) — **live follow-ups**: the conformance gate-removal checklist for the release, the hosted-wire absence-records pin, PipeBatch ledger-parity question, a pre-existing template-variable detection quirk.
+- [deferred-step-f-notes.md](deferred-step-f-notes.md) — **live follow-ups**: the hosted-wire absence-records pin, the PipeBatch ledger-parity question, a pre-existing template-variable detection quirk, plus the three the release surfaced (plxt schema propagation, the stale `pipelex#996` gate, the `-L`-path categorization bug). Also carries the **DONE** record of the spec-suite gate removal — the step-by-step checklist itself is at workspace level.
- [deferred-absence-handling-dedup.md](deferred-absence-handling-dedup.md), [deferred-step-d-review-tradeoffs.md](deferred-step-d-review-tradeoffs.md), [deferred-step-e-review-tradeoffs.md](deferred-step-e-review-tradeoffs.md) — design-tradeoff findings from the checkpoint cold reviews, deliberately not applied; triage on demand.
- [optionals-phase1-highlights.html](optionals-phase1-highlights.html) — presentation artifact summarizing phase 1.
-Cross-repo hand-off docs (vscode-pipelex + mthds-ui marker highlighting) live at the workspace root: `../wip/optionals/`.
+The phase-1 tracker and the cross-repo hand-off docs (vscode-pipelex + mthds-ui marker highlighting) are kept at workspace level.
diff --git a/wip/optionals/deferred-step-f-notes.md b/wip/optionals/deferred-step-f-notes.md
index 628c62c36..8bd9d1b85 100644
--- a/wip/optionals/deferred-step-f-notes.md
+++ b/wip/optionals/deferred-step-f-notes.md
@@ -1,36 +1,27 @@
# Step F deferred notes
-Deferred items surfaced while writing the Step F specs/conformance/docs. Same policy as the other deferred docs in this folder: none of these block phase 1; triage them with the cross-repo wave or on demand.
+Deferred items surfaced while writing the Step F specs, spec-suite coverage and docs. Same policy as the other deferred docs in this folder: none of these block phase 1; triage them with the cross-repo wave or on demand.
## Pre-existing: inline `$var` followed by ` (` escapes template variable detection
-Found while ground-truthing the `optional_input_unguarded` conformance fixture. A prompt like `"Greet $name (nickname: $nickname)."` reports `extraneous_input_variable` for `name` — the inline `$name` reference is not detected as a variable use when it is immediately followed by a space and an opening parenthesis. `"Greet $name today, nickname: $nickname."` detects both fine. Most likely the preprocessed Jinja2 parses `name (…)` as a call expression, and the variable walker misses the callee (or the detection regex swallows the call shape). Pre-existing behavior, unrelated to optionals — reproduced with plain (non-optional) inputs too. Worth a small fix in the variable-detection walk (`jinja2` dissection utilities); the workaround is any other punctuation/wording between the variable and the parenthesis.
+Found while ground-truthing the `optional_input_unguarded` spec-suite fixture. A prompt like `"Greet $name (nickname: $nickname)."` reports `extraneous_input_variable` for `name` — the inline `$name` reference is not detected as a variable use when it is immediately followed by a space and an opening parenthesis. `"Greet $name today, nickname: $nickname."` detects both fine. Most likely the preprocessed Jinja2 parses `name (…)` as a call expression, and the variable walker misses the callee (or the detection regex swallows the call shape). Pre-existing behavior, unrelated to optionals — reproduced with plain (non-optional) inputs too. Worth a small fix in the variable-detection walk (`jinja2` dissection utilities); the workaround is any other punctuation/wording between the variable and the parenthesis.
-## Conformance optionals coverage is pinned ahead of the runtime — remove the gates at release
+## Spec-suite optionals coverage was pinned ahead of the runtime — gates removed at release
-**DONE** (pipelex 0.38.0 + pipelex-api 0.8.0). The gate-removal checklist below was executed against the released runtimes. `OPTIONALS_PENDING_FEATURE` is gone; all six optionals QA cases + the categorized rows + the warnings tests are ungated and pass on both arms (agent-CLI and hosted HTTP), zero skips. The generic gate infrastructure (`pending_feature_skip_reason` / `runtime_supports_case` and the `pending_runtime_feature` field) was kept — it is independently harness-tested and still live for the `pipelex#996` QA gate, so it stays as dormant, reusable infra (no row/case sets it for optionals anymore).
+**DONE** (pipelex 0.38.0 + pipelex-api 0.8.0). Our cross-repo spec suite had written its optionals coverage against an unreleased runtime and gated all of it behind a pending-feature marker; the gate-removal checklist was executed against the released runtimes, and every optionals QA case, categorized row and warnings test now runs ungated on both arms (agent-CLI and hosted HTTP), zero skips. The generic gating infrastructure was kept as dormant, reusable machinery — it is independently tested and still live for another pending-feature gate. The step-by-step execution record lives at workspace level with the rest of that suite's notes.
-Two things came along for free with the same 0.35→0.38 pin bump and were reconciled in the same pass (they are NOT optionals):
-
-- **PipeSignature-tag retirement.** 0.38.0 rejects `type = "PipeSignature"` (`unknown_pipe_type`, "no longer a pipe type"); a signature is now a **type-less** pipe (no `type`, no implementation). The stale fixtures `pending_signature_bundle.mthds`, `valid-error-qa/cases/valid_pending_signature.mthds`, and the inline `_SIG_BUNDLE` in `tests/pipelex/test_validate_all.py` were modernized to type-less. The shipped verdict contract was confirmed and kept: a pending signature is `is_valid=true` in BOTH strict and `--allow-signatures` modes, gated only via exit code (strict→1, `--allow-signatures`→0) — `is_valid` ≠ `is_runnable`.
-- **Benign 0.38.0 corpus wording refreshes** in a few unrelated cases (`invalid_unresolved_concept*`, `valid_no_main_pipe`, `valid_runnable`) — verdict/category/error_type unchanged (the generator drift-check passes), only message wording.
+The same 0.35→0.38 pin bump also swept up the **PipeSignature-tag retirement** (0.38.0 rejects `type = "PipeSignature"` — `unknown_pipe_type`, "no longer a pipe type"; a signature is now a **type-less** pipe, no `type` and no implementation), plus benign wording refreshes in a few unrelated corpus cases (verdict/category/error_type unchanged). The shipped verdict contract was confirmed and kept: a pending signature is `is_valid=true` in BOTH strict and `--allow-signatures` modes, gated only via exit code (strict→1, `--allow-signatures`→0) — `is_valid` ≠ `is_runnable`.
Open follow-ups surfaced (NOT done here — flagged to route):
- **plxt/vscode-pipelex schema propagation.** pipelex 0.38.0's regenerated schema DOES carry `PipeSignatureBlueprint` (type-less, no required `type`), but the plxt-bundled schema is stale and rejects type-less bundles — an `mthds-schema-sync` propagation item (cross-repo wave).
-- **`pipelex#996` QA gate is now stale.** 0.38.0 emits `blueprint_validation / batch_item_name_collision` structured, so `invalid_batch_item_name_collision`'s `pending_runtime_feature="pipelex#996"` gate is dormant; per the marker-removal policy it should be dropped to close the invisible-regression window.
+- **The `pipelex#996` QA gate is now stale.** 0.38.0 emits `blueprint_validation / batch_item_name_collision` structured, so the batch-item-collision case's pending-feature gate is dormant; per the marker-removal policy it should be dropped to close the invisible-regression window.
- **`-L` directory-load path drops structured `error_type` for static-pass validators.** `library_manager.py:824` (`except ValidationError`) stringifies static-pass `PipeValidationError`s (e.g. `optional_output_required`, `optional_input_unguarded`) instead of categorizing them, so a `-L`-loaded bundle degrades to an uncategorized `blueprint_validation` residual — whereas single-file CLI and HTTP `mthds_contents` both categorize correctly. Latent pipelex bug (pre-existing, predates optionals), independent of this task.
-### The checklist as executed
-
-1. removed `pending_runtime_feature=OPTIONALS_PENDING_FEATURE` from the table rows and QA cases (the documented marker-removal policy),
-2. ran `make validate-error-qa` in `conformance/` to generate the committed artifacts for the six new cases,
-3. dropped the optionals-specific probe-skips (conftest `is_valid` probe → hard assert; agent `exit_code` probe → removed) so regressions become visible.
-
## PipeBatch compaction does not ledger the dropped branches (PipeParallel does)
Surfaced by the Step F cold review. When PipeBatch compacts an absent branch result out of the aggregated list (`pipe_batch.py`, the `AbsenceRecord` arm of the aggregation loop), it only emits a `log.verbose` line — unlike PipeParallel, which calls `working_memory.record_resolved_absence` for an omitted composite component. So a run's absence ledger does not show which batch items were dropped. Design question, not a bug: N dropped branches would add N records (noisy for large batches), and the compacted list itself is a present value at the boundary. If ledger parity is wanted (e.g. for the route-or-skip auditing story), record one absence per dropped branch (or one summarizing record) into the parent working memory during aggregation. Revisit with phase 2 observability work.
-## Absence records on the hosted wire — conformance pin awaits the mthds bump
+## Absence records on the hosted wire — the spec-suite pin awaits the mthds bump
-The spec section "Absence records on run artifacts" is `<!-- unverified -->` by design: the hosted `/v1/execute` cannot return the `absences` ledger until the mthds SDK wire models can carry it (cross-repo hand-off item 1 in the tracker). When that lands, add an HTTP-arm conformance test (a PipeFunc/PipeCondition-only bundle whose optional output resolves absent) and flip the spec section to `> Verified by:`.
+The spec section "Absence records on run artifacts" is `<!-- unverified -->` by design: the hosted `/v1/execute` cannot return the `absences` ledger until the mthds SDK wire models can carry it (cross-repo hand-off item 1 in the tracker). When that lands, add an HTTP-arm test to our cross-repo spec suite (a PipeFunc/PipeCondition-only bundle whose optional output resolves absent) and flip the spec section to `> Verified by:`.
diff --git a/wip/optionals/optionals-design.md b/wip/optionals/optionals-design.md
index a4d2dd860..562b25c7f 100644
--- a/wip/optionals/optionals-design.md
+++ b/wip/optionals/optionals-design.md
@@ -169,12 +169,12 @@ The validator gains an absence-propagation pass over each controller's dataflow,
- `?`/`!` grammar misuse (on plurals, on outputs for `!`, on `refines`...) → error at blueprint parse (`OPTIONAL_MARKER_INVALID`).
- Optional input referenced unguarded in a template → see D7.
-New error types flow automatically through the existing machinery (`build_validation_error_items` → agent CLI JSON/markdown, API 422, conformance) — the plumbing is already unified; we add enum values, fixtures, and conformance rows, not new channels.
+New error types flow automatically through the existing machinery (`build_validation_error_items` → agent CLI JSON/markdown, API 422, our cross-repo spec suite) — the plumbing is already unified; we add enum values, fixtures, and spec-suite rows, not new channels.
Two sub-decisions:
- **Dry-run modeling.** v1: keep the dry run all-present (mock every input, including optional ones) and rely on the static taint pass for the absent arm. Alternative: dual-arm dry run (a second pass with all optionals absent) — better coverage of skip paths and template guards, but doubles dry-run cost and requires the skip machinery to run under DRY. Decision: static-only in v1, dual-arm as a follow-up if the static pass proves insufficient.
-- **Advisory channel.** Some findings are lints, not errors: `!` on a guaranteed slot, `?` output on a pipe that can never produce absence. The validation report is binary today; the only advisory precedent is `pending_signatures`/`is_runnable`. Options: (a) mirror that pattern with a dedicated `optionality_notes` list; (b) add a general `warnings` array to the report (protocol change, conformance impact, but the right long-term shape); (c) stay silent on lints in v1. **Decision: option (b)** — a general `warnings` array (same item shape as errors, never flips `is_valid`), bundled into the same protocol bump that adds the `optional` flag to IO contracts, so one bump covers both. Note the split with the *factual* liftable-pipe inventory ("pipe X may be skipped when Y is absent"), which is dataflow information, not a lint — it ships as structured data on the valid report (beside `pipe_io_contracts`), per the D3 implicit-lifting commitment.
+- **Advisory channel.** Some findings are lints, not errors: `!` on a guaranteed slot, `?` output on a pipe that can never produce absence. The validation report is binary today; the only advisory precedent is `pending_signatures`/`is_runnable`. Options: (a) mirror that pattern with a dedicated `optionality_notes` list; (b) add a general `warnings` array to the report (protocol change, spec-suite impact, but the right long-term shape); (c) stay silent on lints in v1. **Decision: option (b)** — a general `warnings` array (same item shape as errors, never flips `is_valid`), bundled into the same protocol bump that adds the `optional` flag to IO contracts, so one bump covers both. Note the split with the *factual* liftable-pipe inventory ("pipe X may be skipped when Y is absent"), which is dataflow information, not a lint — it ships as structured data on the valid report (beside `pipe_io_contracts`), per the D3 implicit-lifting commitment.
## 11. D7 — Prompts and templates: what the author sees
@@ -252,16 +252,16 @@ Cross-repo (from the workspace survey):
| `vscode-pipelex/` | `strip_concept_qualifiers` in the LSP (strips `[...]` but not `?` — a trailing `?` breaks resolution today) + tests, TextMate grammar regexes, bundled schema sync, `plxt` format preservation | M |
| `mthds-ui/` | `StuffSpecInfo.optional`, Shiki grammar copy, skipped-node + optional-edge rendering, detail panels | M |
| `mthds-plugins/` | Skill templates that teach the ref syntax (`shared/mthds-reference.md.j2`, build/inputs/fix skills) + regeneration; teach the trichotomy and `@?` pairing | M |
-| `conformance/` + `docs/specs/` | `PipeIOContract.optional` in the protocol spec, new validation-error categories in the locked contract, valid/invalid fixtures (`optional_not_handled.mthds` etc.), error-QA corpus entries | M |
+| Protocol spec + cross-repo spec suite | `PipeIOContract.optional` in the protocol spec, new validation-error categories in the locked contract, valid/invalid fixtures (`optional_not_handled.mthds` etc.), error-QA corpus entries | M |
| `mthds-js` / `mthds-python` | Type mirrors (IO contracts, ValidationErrorItem); package-layer ref parsers untouched by design (D1) | S |
| `pipelex-api/` | Pass-through; new absence fields in run results, docs | S |
| JSON schemas | Regenerate only — `inputs`/`output` are unconstrained strings, already `?`-permissive | S |
-Sequencing note: per workspace rules, `docs/specs/` + `conformance/` move in the same change as the pipelex surface they verify; the mthds spec, tooling, and UI repos can follow the runtime release. The Required-main-stuff Phase 3 cross-repo sweep (release-gated: `combined_output` removal + `Composite` in the spec/schema/skills) touches the same mthds spec pages — land it before the optionals cross-repo wave to avoid colliding edits.
+Sequencing note: per workspace rules, the protocol spec and our cross-repo spec suite move in the same change as the pipelex surface they verify; the mthds spec, tooling, and UI repos can follow the runtime release. The Required-main-stuff Phase 3 cross-repo sweep (release-gated: `combined_output` removal + `Composite` in the spec/schema/skills) touches the same mthds spec pages — land it before the optionals cross-repo wave to avoid colliding edits.
## 17. Phasing
-- **Phase 1 — the language core (pipelex + spec/conformance).** D1 grammar, D2 ledger, D3 trichotomy + lifting, D4 plural rules, PipeCondition `continue` integration, optional method inputs, D6 taint validation + new error types, D7 template guard-lint + `@?` fix, D9 error classes + failure UX, IO-contract `optional` flag, run-result absence records, graph `skipped` state. This is a complete, useful feature on its own — even before LLM maybe-outputs, it legitimizes conditional flows and optional method inputs.
+- **Phase 1 — the language core (pipelex + the protocol spec and its verifying suite).** D1 grammar, D2 ledger, D3 trichotomy + lifting, D4 plural rules, PipeCondition `continue` integration, optional method inputs, D6 taint validation + new error types, D7 template guard-lint + `@?` fix, D9 error classes + failure UX, IO-contract `optional` flag, run-result absence records, graph `skipped` state. This is a complete, useful feature on its own — even before LLM maybe-outputs, it legitimizes conditional flows and optional method inputs.
- **Phase 2 — producing absence from models + coalescing.** PipeLLM/`Text?` maybe-wrapper with reasons, and `??` coalescing/defaults (pulled forward from phase 3: it is the ergonomic replacement for the `continue` pass-through that phase 1 broke — see the §13 migration note). Batch compaction shipped in phase 1 (Step C).
- **Phase 3 — ergonomics.** `on_error = "absent"`, presence sugar, dual-arm dry run if warranted.
- **Cross-repo wave** after the pipelex release: mthds spec pages, vscode/plxt, mthds-ui, skills.
diff --git a/wip/optionals/optionals-phase1-highlights.html b/wip/optionals/optionals-phase1-highlights.html
index e0aea2dec..738b9d649 100644
--- a/wip/optionals/optionals-phase1-highlights.html
+++ b/wip/optionals/optionals-phase1-highlights.html
@@ -142,7 +142,7 @@
<li><strong>Static safety theorem:</strong> validation proves at author time that <em>every possible absence reaches an explicit sink</em> — no more "my workflow silently produced nothing".</li>
<li><strong>Breaking, on purpose:</strong> <code>PipeCondition</code>'s <code>continue</code> no longer passes a value through — it resolves the declared output as absent, killing the language's last invisible optional.</li>
</ul>
- <p>Status: dev is merged in, CI is green, all review-bot findings are triaged (one real P1 caught &amp; fixed), and the PR awaits merge. Conformance coverage and protocol-spec sections are written but ride separate branches in the <code>conformance</code> and workspace-root repos (no PRs yet — they de-gate only once both conformance arms run an optionals-speaking pipelex).</p>
+ <p>Status: dev is merged in, CI is green, all review-bot findings are triaged (one real P1 caught &amp; fixed), and the PR awaits merge. Spec-suite coverage and protocol-spec sections are written but ride separate branches in the sibling repos that own them (no PRs yet — they de-gate only once both of the suite's arms run an optionals-speaking pipelex).</p>
</div>
<h2>Why we did this</h2>
@@ -429,7 +429,7 @@ inputs = { clause = "PenaltyClause!" } # ← asserts presence; absence = typed
<li><strong>One commit per checkpoint, six checkpoints (A–F).</strong> Each ran the full gate set (<code>make agent-check</code> + full <code>make agent-test</code>) plus a <em>context-free</em> cold code review of the step diff by a fresh reviewer with no access to the plan or rationale. Findings were triaged every time: correctness fixed in-step, design tradeoffs recorded as deferred docs, over-engineering simplified.</li>
<li><strong>TDD throughout:</strong> red tests first for every step — lift chains with provenance assertions, force-failure UX (the message must name the variable, both pipes, and the reason), plural normalization, hydration round-trips, end-to-end absent-main-output runs over every surface.</li>
<li><strong>Review round 1 on the PR:</strong> 13 bot findings (greptile, cubic, Codex), each adversarially verified before acting — 9 confirmed and fixed (headline: the parallel parent-memory clobber P1), 1 dead-code deletion, 1 refuted with evidence, 1 already-deliberate design decision. All threads answered with commit citations; CI fully green.</li>
- <li><strong>Ground-truth fixtures:</strong> every conformance fixture's expectations were generated by running it against the real build before being written down — no guessed error categories.</li>
+ <li><strong>Ground-truth fixtures:</strong> every spec-suite fixture's expectations were generated by running it against the real build before being written down — no guessed error categories.</li>
</ul>
<h2>What's deliberately NOT in phase 1</h2>
@@ -438,14 +438,14 @@ inputs = { clause = "PenaltyClause!" } # ← asserts presence; absence = typed
<li><strong>Coalescing <code>??</code></strong> — the ergonomic replacement for <code>continue</code> pass-through. Phase 2. (Non-required parallel fields absorbing as their <em>declared default</em> is a small preview of it.)</li>
<li><strong>The LLM maybe-wrapper</strong> — making <code>?</code> on operator outputs change the LLM contract ("return nothing rather than invent"). Phase 2; over-claiming <code>?</code> today is deliberately legal as evolution room, and deliberately not linted.</li>
<li><strong>Cross-repo wave</strong> — mthds wire models carrying the <code>absences</code> ledger (which unblocks the hosted-API absent arm), mthds-ui rendering skipped nodes/optional edges, pipelex-api surfacing <code>warnings</code> + <code>optional</code> contract flags. Gated behind other in-flight work; no PRs yet.</li>
- <li><strong>Conformance de-gating</strong> — the suite's optionals coverage is written and validated live against this branch, but stays probe-skipped (<code>OPTIONALS_PENDING_FEATURE</code>) until <em>both</em> conformance arms run an optionals-speaking pipelex (the HTTP arm pins the released <code>pipelex==0.37.0</code>).</li>
+ <li><strong>Spec-suite de-gating</strong> — the suite's optionals coverage is written and validated live against this branch, but stays probe-skipped until <em>both</em> of its arms run an optionals-speaking pipelex (the HTTP arm pins the released <code>pipelex==0.37.0</code>).</li>
</ul>
</div>
<h2>Links</h2>
<ul>
<li><a href="https://github.com/Pipelex/pipelex/pull/1021">Pipelex/pipelex#1021</a> — the phase-1 PR (feature/Optionals → dev). Everything above lands there.</li>
- <li>Conformance coverage and protocol-spec sections are committed on side branches of the <code>conformance</code> and workspace-root repos — PRs will follow once their merge vehicles are chosen.</li>
+ <li>Spec-suite coverage and protocol-spec sections are committed on side branches of the sibling repos that own them — PRs will follow once their merge vehicles are chosen.</li>
</ul>
<p class="footer">Optionals phase 1 · feature/Optionals · generated 2026-07-05 · lives in <code>wip/optionals/</code> (work-in-progress notes, not release docs)</p>
diff --git a/wip/optionals/optionals-phase1-tracker.md b/wip/optionals/optionals-phase1-tracker.md
deleted file mode 100644
index 9f5f78be7..000000000
--- a/wip/optionals/optionals-phase1-tracker.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# Optionals phase 1 — tracker (CLOSED — phase 1 complete)
-
-> Archived from `TODOS.md` at the worktree root into `wip/optionals/` now that phase 1 is done. See [README.md](README.md) for current track status and what comes next.
-
-**Phase 1 is COMPLETE** (all steps A–F done, FINAL CHECKPOINT cleared — see the checkpoint log). This tracker is kept as the feature's record; the only live follow-ups are the hand-off notes in "Cold-start context" and `wip/optionals/deferred-step-f-notes.md`.
-
-Branch `feature/Optionals` (worktree `_optionals`). This file is the single live tracker: progress checkboxes, checkpoint log, decisions/deviations. Reference docs: `wip/optionals/optionals-design.md` (decisions D1–D11, all decided) and `wip/optionals/optionals-plan.md` (the narrative plan this tracker implements — steps A–F map one-to-one).
-
-Working rules: TDD (red tests first per step), `make agent-check` after every code change, full `make agent-test` at each checkpoint, **one commit per checkpoint**, no backward compatibility (breaking changes go in the changelog under `[Unreleased]`).
-
-## Cold-start context (update at every checkpoint)
-
-- **Status: PHASE 1 COMPLETE — Step F DONE, FINAL CHECKPOINT cleared.** This tracker is CLOSED; nothing remains in-repo for phase 1. Step F landed across three repos: (1) `_optionals` `b66bd751a` — the "Understanding Optionality" docs guide (both mkdocs nav lists), PipeBatch compaction section, PipeLLM `@?` sigil docs, run-CLI absence-artifact docs, changelog Documentation entry, `wip/optionals/deferred-step-f-notes.md`; schema + error pages regenerated with zero diff (already current). (2) `conformance` `9acd10e` + triage `39c5b4e` (on `feature/config-dialect-fixture`) — invalid fixtures + `CATEGORIZED_VALIDATION_ITEMS` rows for all five optionals error types, `test_validate_optionals.py` on both arms (`optional` contract flags, `liftable_pipes`, `warnings`), six QA-corpus cases; ALL gated via `OPTIONALS_PENDING_FEATURE` / `pending_feature_skip_reason` because the sibling venvs run released pipelex without optionals — gate-removal checklist in the Step-F deferred notes. (3) workspace root `c28380d` + triage `caea84e` (on `feature/SDK-and-starter`) — protocol-spec sections (optional IO contracts + liftable pipes, advisory warnings, optionality validation errors, absence records on run artifacts) with bidirectional Verified-by links; `make check-spec-links` green. Nothing pushed in any repo.
-- **Previous status (Step E):** Step E DONE (Checkpoint E cleared — SHAs in the checkpoint log). An absent result is a first-class success everywhere in-repo. Protocol bump landed in one motion: `optional: bool` on `PipeInputContract`/`PipeOutputContract` (from `presence.is_optional`), `warnings: list[ValidationErrorItem]` on `PipelexValidationReport` (assembled in `build_validation_report`, populated by the new `pipeline/optionality_warnings.py::build_optionality_warnings` in `validate_in_process`, the agent-CLI whole-bundle validate cores, the bare CLI (`_echo_optionality_warnings`, bundle arm + `--all`), and the three bundle-context builder `validate_ops` twins — all through the single-walk collector `pipeline/controller_taint.py::collect_controller_taint_analyses`, which also feeds `build_liftable_pipes`; markdown gets a "Warnings" section in `validation_render.py`). The useless-`!` lint (`OPTIONAL_FORCE_REDUNDANT`, advisory-only enum value): the taint walks classify every `!` consumption (asserting = slot tainted, redundant = slot guaranteed) via `scan_taint_triggers` + new `ForceConsumptionInfo` carriers on both analyses; the builder aggregates per (pipe_ref, variable) ACROSS flows — one asserting flow silences redundant observations, and a `!` never observed in any flow is never flagged. Boundaries: `resolve_main_stuff_root_key` returns the declared slot name for a recorded main absence (message swept to the new invariant), `hydrate_working_memory` round-trips the `absences` ledger (malformed → loud `PipeJobError`), OTel captures absence documents on inputs and outputs, bare CLI prints/saves the absence artifact (no viewer), agent CLI returns the absence document as the compact result. Shared artifact renderers: `core/memory/absence_render.py::build_absence_payload/build_absence_json/build_absence_markdown/build_absence_html` (delivery executor + both CLI run cores render through them). Graph: `NodeSpec.skip_reason` + `skipped` status via the new `on_pipe_end_skipped` tracer hook (protocol + noop + manager + tracer + `pipe_end_skipped` event + assembler), skip reason from the shared `PipeAbstract._make_skip_reason`; a skipped pipe with a PLURAL output registers its real empty-list output spec (and plural companion slots) so downstream DATA edges resolve; `EdgeSpec.optional` on data edges whose producer registered `extra={"optional": True}` on its output IOSpec (set in the run epilogue from `output.presence.is_optional`; both builders share `graphspec.py::output_digest_is_optional`). **Bonus fix (load-bearing):** `StuffArtefact.__bool__` — Jinja2 truth tests (`{% if var %}`, `@?`) on a PRESENT singular value crashed via the list-only `__len__` fallback; now truthy, with empty lists falsy per D4. End-to-end pin: `test_absent_main_output_surfaces.py` (execute → response slot name, provenance chain to NOT_PROVIDED origin, graph skipped nodes + serialized).
-- **Next action:** none in-repo — hand off. (a) **Release**: cut the pipelex release carrying optionals, then run the conformance gate-removal checklist (`wip/optionals/deferred-step-f-notes.md`) and `make validate-error-qa`. (b) **Cross-repo wave** (after the Required-main-stuff Phase 3 sweep): the three hand-off notes below. (c) **Phase 2**: the LLM maybe-wrapper + `??` coalescing (design doc §phase 2).
-- **Cross-repo hand-off notes (accumulating for the wave):** (1) mthds-python `DictWorkingMemoryAbstract` must gain the `absences` ledger (extra=forbid blocks it today) — then `_run_core_api.py`'s gated absent arm can land (comment in code marks the spot); (2) mthds-ui renders `skipped` nodes + `optional` edges + `skip_reason` detail; (3) pipelex-api response models surface `warnings` + contract `optional` flags; (4) syntax highlighting of `?`/`!` markers is broken in both grammar copies — ungated, can land before the release; handoffs live at the workspace root: `../wip/optionals/handoff-vscode-pipelex-optional-markers.md` (TextMate grammar source + semantic tokens + Rust `strip_concept_qualifiers` goto/hover bug) and `../wip/optionals/handoff-mthds-ui-optional-markers.md` (shiki grammar + themes + FUNCTIONAL `conceptRefs.ts` parse-to-null bug that drops marked refs from static graphs).
-- **Open questions for Louis:** none blocking. Standing flagged compromise: `continue` pass-through breaks in phase 1 while its ergonomic replacement (`??` coalescing) is phase 2 — restructure only if Louis asks.
-
-## Checkpoint protocol — MANDATORY STOP at every CHECKPOINT
-
-At each checkpoint the agent MUST stop forward progress and run this sequence, in order. No rolling into the next step with the checkpoint half-done.
-
-1. **Verify:** full `make agent-check` + `make agent-test` green (`make tb` too if config files were touched). Fix failures before anything else.
-2. **Commit:** one commit for the step (changelog entry included when the step is user-visible/breaking).
-3. **Update this file:** tick the boxes, fill the checkpoint log row (SHA), and refresh "Cold-start context" — decisions taken, deviations from the plan, open questions, exact next action — so a brand-new session can resume efficiently from this file alone. If a design decision changed, update `wip/optionals/optionals-design.md`/`wip/optionals/optionals-plan.md` too.
-4. **Fan out a context-free code review:** spawn a **Sonnet-5 sub-agent with NO inherited context** (general-purpose agent, `model: sonnet` — never a fork) whose prompt is ONLY a pointer to the changes under review plus the instruction to run the `/code-review` skill. Example prompt: *"In /Users/lchoquel/repos/Pipelex/_optionals, run the /code-review skill on `git diff <previous-checkpoint-SHA>..HEAD`. Report findings."* Do **not** pass the plan, the design doc, the rationale, or your own conclusions — the reviewer judges the code cold. Review bar: clean solid software, not over-engineering.
-5. **Triage findings:** correctness bugs → fix now (amend or follow-up commit, re-run gates). Design-tradeoff findings → do not reflexively apply; record in a deferred-items doc under `wip/optionals/` and move on. Over-engineering findings → simplify now.
-6. Only then proceed to the next step.
-
-## Prep
-
-- [x] Commit this tracker (+ staged old-TODOS deletion). Record the SHA as the Step-A review base in the checkpoint log. *(Turned out already done: the tracker landed in `eace1d607`.)*
-
-## Step A — grammar and carriers (parse `?` / `!`, no behavior change)
-
-- [x] Red tests first: parser unit tests for every marker × multiplicity combination; blueprint + spec accept/reject fixtures.
-- [x] Extend the marker grammar (D1) in `pipelex/core/pipes/variable_multiplicity.py` (+ its inline twin), the looser regex in `input_stuff_specs_factory.py`, and the naive `[`-splitter in `concepts/helpers.py`. Fix the `MUTLIPLICITY_PATTERN` typo while there.
-- [x] `StuffSpec`/`NamedStuffSpec` gain the presence marker (a `PresenceMarker` StrEnum: plain / optional / force); `InputStuffSpecs.required_names` splits into required vs declared.
-- [x] Blueprint-parse-time grammar errors (`OPTIONAL_MARKER_INVALID`): `?` on plurals, `!` on outputs or plurals, markers on concept definitions / `refines` / structure-field refs / package refs (D1, D4).
-- [x] Builder specs mirror the blueprint rules (`to_blueprint()` passes markers through); `contract_match` canonicalization compares presence markers (D5).
-- [x] **CHECKPOINT A** — markers parse, validate, and round-trip; zero runtime behavior change; run the full checkpoint protocol above.
-
-## Step B — absence at runtime (ledger + trichotomy + lifting)
-
-- [x] Red tests first: lift-skip chain with provenance, absorb, force-failure UX (assert the message names variable, pipes, and reason), plural normalization, optional method inputs, run-report absence enumeration. All tests sink absence before the method boundary (a downstream `?` input) — end-to-end absent-main-output coverage is Step E's.
-- [x] WorkingMemory gains the absence ledger (D2): `AbsenceRecord` (`variable_name`, `producing_pipe`, `kind` = declared-absent | skipped | not-provided, `reason`, upstream chain). New tri-state resolved accessor (Stuff | AbsenceRecord) for post-run reads — do **not** resurrect `optional_main_stuff` (design §14).
-- [x] The three runtime miss-gates learn the trichotomy (D3): `PipeAbstract.validate_before_run` (fix the "Dry run of ..." message bug on the live path), `SubPipe`, PipeCondition's branch check. Plain input fed absence → **skip** (lift) + record skipped-absence for the pipe's output with provenance; `?` input → run; `!` input absent → `OptionalValueAbsentError` (D9: new error class in the relevant `exceptions.py`, provenance chain, RFC 7807 + error page via `pipelex-dev generate-error-pages`).
-- [x] The per-pipe graph-tracer epilogue in `pipe_abstract.py` (success path reads `working_memory.get_main_stuff()` directly) learns the resolved-as-absent arm **here, not in Step E** — it fires on every pipe run, so the first skipped pipe would crash it.
-- [x] Skipped plural output normalizes to empty `ListContent` + ledger note (D4); taint stops.
-- [x] Optional method inputs (D5): omitting a `?` input in `inputs.json` / the execute request → not-provided record instead of `PipeRunInputsError`; the required-input error message gains the "these optional inputs may be omitted" hint.
-- [x] Mock seeding / dry-run sweep learn optional slots (dry run stays all-present per D6): mock seeding already enumerates every declared input including `?` ones (all-present); pinned by test, and not-provided records are only written for slots the mock pass left empty.
-- [x] **CHECKPOINT B** — absence exists, propagates, and fails loudly only through `!`; run the full checkpoint protocol.
-
-## Step C — controllers: `continue` replacement + parallel combine (D11)
-
-- [x] Red tests first: continue-absent (live + dry), parallel with absorbed/omitted/required-absent branches, batch compaction if shipped.
-- [x] **PipeCondition `continue`** (design §14, breaking): replace pass-through-or-error with "declared output absent, memory otherwise unchanged" — record the absence (kind = declared-absent, reason = the evaluated expression/outcome), stamp no main stuff, return success. Same in dry run (the all-special-outcomes guard becomes: legal iff output declared `?`). Rewrite `test_pipe_condition_continue_delivery.py` to pin the new semantics (keep the run-id stamping assertions).
-- [x] These tests exercise the delivery boundary, so `delivery_executor.py` (typed + raw arms: absent main output delivers an explicit absence artifact, not an error) lands **here, not in Step E**.
-- [x] Document the migration idiom (previous value stays in memory under its own name; coalescing is the phase-2 answer) in docs + changelog (breaking).
-- [x] **PipeParallel combine under absence** (D11): absent branch result → structured output field with `required = false` absorbs as field-`None`; `Composite` output omits the component + ledger note. Runtime guard raises a typed error if a required field's branch is absent (statically unreachable after Step D, but the runtime must not feed `combine_stuffs` a hole). **Checkpoint-B review pinned the entry points:** `pipe_parallel.py` `_run_branches_and_combine` (`pipe_output.main_stuff` — the raising accessor) crashes today on a lifted branch (`WorkingMemoryStuffNotFoundError`, reproduced); `pipe_batch.py` has the identical shape at its branch-collect loop and in `_dry_run_controller_pipe`. Both must move to the tri-state `resolve_main_stuff()` with the D11 policy.
-- [x] PipeBatch compaction (D4 bonus): absent branch results dropped from the aggregated list — SHIPPED here (it fell out of the tri-state collect loop naturally; no `?`-output gating needed at runtime since a list cannot hold a hole).
-- [x] **CHECKPOINT C** — controllers speak absence; the #1014 `continue` tests replaced; run the full checkpoint protocol.
-
-## Step D — static validation: the taint pass + template lint
-
-- [x] Red tests first: taint fixtures (valid + each error type), guard-lint accept/reject, `@?` detection.
-- [x] Absence-propagation pass over controller dataflow (D6): per-slot presence computed (`guaranteed` / `maybe-absent`) by walk methods on the controllers (`PipeSequence.analyze_taint`, `PipeParallel.analyze_branch_taint`); shared carriers + presence-resolution helper in `pipe_controllers/absence_taint.py`.
-- [x] New `PipeValidationErrorType`s: `OPTIONAL_NOT_HANDLED` (taint reaches a non-optional boundary — message names source, path, three fixes), `OPTIONAL_OUTPUT_REQUIRED` (`continue`-reachable condition without `?` output), `OPTIONAL_BRANCH_REQUIRED_FIELD` (the D11 static error, extending `PipeParallel.validate_output_with_library`).
-- [x] Template guard-lint (D7): `OPTIONAL_INPUT_UNGUARDED` via the new guard walker (`tools/jinja2/jinja2_optional_guards.py`) + shared `lint_optional_input_guards` helper, wired into PipeLLM prompts/system prompts, PipeCompose templates, and PipeCondition expressions. `@?` fix: declared-optional inputs are no longer presence-required by the SubPipe / PipeCondition miss-gates.
-- [x] Liftable-pipe inventory as structured data on the valid report (`liftable_pipes` beside `pipe_io_contracts`), built by `pipeline/liftable_pipes.py` from the same taint analyses.
-- [x] **CHECKPOINT D** — validation proves the safety theorem ("every absence source reaches an explicit sink"); full checkpoint protocol run (see the checkpoint log).
-
-## Step E — wire, boundaries, and graph
-
-- [x] Red tests first: end-to-end absent-main-output run over each surface (execute response, CLI output cores, telemetry, hydration round-trip), graph skipped-state serialization, contracts/warnings, redundant-`!` lint.
-- [x] Protocol bump, one motion (D6 + D8): `optional: bool` on `PipeInputContract`/`PipeOutputContract`, the general `warnings` array on the validation report (same item shape as errors, never flips `is_valid`), absence records on run results. Neutral MTHDS naming, no `pipelex_` prefixes.
-- [x] Populate `warnings` with the useless-`!` lint (`optional_force_redundant`). The over-claimed-`?` lint is deliberately **not** emitted in phase 1 (D5 blesses over-claiming as evolution room; phase 2 makes `?` on operator outputs meaningful).
-- [x] The remaining post-run boundaries learn the resolved-as-absent arm: `resolve_main_stuff_root_key` (absent arm returns the declared slot name), `hydrate_working_memory` (absences ledger round-trips, malformed record fails loud), `otel_factory` (inputs AND outputs capture), bare CLI run core (pretty print + `--save-main-stuff` absence artifact + `--save-csv` message), agent CLI run core (absence document as result payload). Shared renderers in `core/memory/absence_render.py`; delivery executor refactored onto them. **Agent-API run core (`_run_core_api.py`) stays gated on the cross-repo mthds bump** — the SDK wire models (`DictWorkingMemoryAbstract`, extra=forbid, root+aliases only) cannot carry absences yet; noted in code, hand-off item for the cross-repo wave.
-- [x] Graph (D8): `NodeSpec` gains `skip_reason`, lifted pipes end their node `skipped` (new tracer hook `on_pipe_end_skipped` + `pipe_end_skipped` trace event + assembler handler), `EdgeSpec.optional` marks data edges fed by `?`-declared outputs (producer output IOSpec `extra["optional"]`). (mthds-ui rendering is the cross-repo wave.)
-- [x] Sweep the invariant prose to "a pipe run always resolves its declared output: a value or a recorded absence".
-- [x] **CHECKPOINT E** — an absent result is a first-class success everywhere in-repo; full checkpoint protocol run (see the checkpoint log).
-
-## Step F — specs, conformance, docs, release prep
-
-- [x] `docs/specs/` protocol spec: `optional` flag, `warnings` array, absence records, new validation-error categories; matching `conformance/` fixtures (`optional_not_handled.mthds` etc.) + error-QA corpus rows; `make check-spec-links` green (run in `conformance/`).
-- [x] Regenerate the MTHDS JSON schema (`pipelex-dev generate-mthds-schema`) and error pages; docs: an optionality guide beside `multiplicity.md`'s pipelex counterpart, pipe-page updates (PipeCondition, PipeParallel, PipeBatch), `@?` docs reconciled. *(Both regenerators produced zero diff — already current since Steps B/D; the schema carries no concept-ref patterns, so the marker grammar needs no schema change.)*
-- [x] Changelog under `[Unreleased]`: breaking — `continue` semantics, `?`/`!` grammar, protocol additions. *(Already complete from Steps A–E; Step F added the Documentation entry.)*
-- [x] Full `make agent-test` + `make tb`.
-- [x] **FINAL CHECKPOINT** — phase 1 complete; run the full checkpoint protocol. Hand off: cross-repo wave (after the Required-main-stuff Phase 3 sweep) and phase 2 (LLM maybe-wrapper). Fold or close this tracker and `wip/optionals/optionals-plan.md`. *(Closed — completion banners on this tracker and the plan doc; design doc stays as reference.)*
-
-## Checkpoint log
-
-| Checkpoint | Commit SHA | Review verdict | Notes |
-|---|---|---|---|
-| Prep | `eace1d607` | n/a | Tracker was committed alongside the plan update; serves as the Step-A review base. |
-| A | `ae4ace79e` | Clean — no findings at reporting confidence | Cold Sonnet review of `eace1d607..HEAD`. Two sub-threshold doc-in-code notes applied in the follow-up commit (PipeSpec authoring-surface descriptions teach `?`/`!`; enum comment covers all three trigger cases); third note (factory doesn't re-enforce mutual exclusion) = deliberate layering, see deviations log. |
-| B | `6c258e2ba` | 4 findings, all triaged | Cold Sonnet review of `80c4e56f6..HEAD`. (1)+(2) PipeParallel/PipeBatch crash (`get_main_stuff` raise) on a lifted branch — CONFIRMED reachable, but it is exactly the already-planned Step C work (D11 combine-under-absence + batch compaction); pinned explicitly in the Step C bullets. (3) delivery executor generic error on an unsunk lift chain — the plan's explicit Step C boundary (delivery arms land there). (4) duplicated miss-gate check → hoisted to `WorkingMemory.list_missing_names` in the checkpoint commit. |
-| C | `0df759bd6` | 10 findings: 1 bug fixed, rest triaged | Cold Sonnet review of `7d2ed6bf4..HEAD`. (1) **Stale-value masking — CONFIRMED bug, fixed in the checkpoint commit:** recording an absence under a name that already held a `Stuff` left the stale value winning `resolve_stuff`; fix = new `record_resolved_absence` (removes value + alias under the name — the mirror of `set_stuff`'s value-supersedes-record), used by `record_new_main_absence` and the parallel branch arm; `record_absence` stays the pure NOTE write (D4 plural note depends on it). Regression tests added. (2)–(4) OTel + three CLI run cores raise on absent main — already-planned Step E work, now pinned as REACHABLE in the Step E bullet (Checkpoint-B precedent). (5) `hydrate_working_memory` drops the absences ledger — added to the Step E bullet (was missing from the checklist). (6) non-`None` field default absorbs as the default — deliberate (proto-coalescing); changelog + docs wording corrected to say "field default". (7)–(9) dedup/nesting tradeoffs → `wip/optionals/deferred-absence-handling-dedup.md`. (10) informational. |
-| D | `f3d58d104` (+ triage follow-up commit) | 10 findings: 8 fixed, 2 deferred | Cold Sonnet review of `2d4211420..HEAD`. **Fixed in the triage commit:** (1) lifted `add_each_output` parallel left branch slots neither-value-nor-record at runtime while the static pass blessed the flow — new `PipeAbstract.lifted_companion_slots()` hook + `_make_lifted_output` resolves each companion (singular → SKIPPED record with provenance, plural → empty list per D4); the sequence walk's lifted-parallel arm now keys on the same hook (one source of truth); end-to-end static+runtime agreement test added. (2) walker skipped subtrees under unbuildable paths (`{{ x[0].f }}`) → now recurses inward. (3)+(7) `{% set %}` handling rebuilt as sequential body-walking: read-before-set is flagged, nested sets shadow correctly. (4) `Jinja2DetectVariablesError` leaked raw from construction → lint skips unparseable templates (parsing gates own syntax errors). (5) PipeSearch + PipeImgGen (prompt + negative_prompt) wired into the guard-lint. (6) `and` short-circuit recognized (`{% if var and var.attr %}` clean). (8) `variable_names` now carries `SlotTaint.origin_slot_name`, not prose. (10) duplicated taint bookkeeping factored into `scan_taint_triggers` + `is_plural_step_result` in `absence_taint.py`. **Deferred → `wip/optionals/deferred-step-d-review-tradeoffs.md`:** (9) cross-package liftable inventory scoping (decide at the Step E/F protocol bump), taint-analysis recompute/double-parse efficiency, `_build_full_path` duplication, inverted-guard shapes. |
-| E | `2f55da612` (+ checkpoint commit) | 10 findings: 1 bug + 5 consistency/cleanup fixed, 4 deferred | Cold Sonnet review of `26738d440..HEAD`. **Fixed in the checkpoint commit:** (1) **lifted-plural producer registration — CONFIRMED regression, fixed:** the skipped early-return never registered the lifted pipe's output IOSpec, but a lifted PLURAL output writes a real empty-list Stuff (D4) that downstream pipes consume — its digest never entered either graph builder's producer map, silently dropping the DATA edge. Fix: `on_pipe_end_skipped` (protocol/tracer/manager/event/assembler) now carries `output_spec` + `output_concept_data` and registers them like a success output; the epilogue computes the spec on both arms; plural companion slots register via `register_controller_output`. Unit tests on both builders. (3) useless-`!` lint was unreachable from the human `pipelex validate` → `_echo_optionality_warnings` on the bundle arm + `--all` sweep. (4) builder `validate_ops` twins drifted → `warnings` added to the three bundle-context ops. (7) taint walk ran twice per validate → shared `collect_controller_taint_analyses` pass feeds both projections (`pipelex/pipeline/controller_taint.py`); both builders now take analyses. (8) `_is_optional_output_digest` duplicated → shared `output_digest_is_optional` in `graphspec.py`. (10) absence-artifact serializer divergence → `build_absence_json`/`build_absence_html` in `absence_render.py`, all three call sites routed through them. (9) missing docs → graph-tracing page (SKIPPED + skip_reason + optional edges) and agent-cli page (validate `warnings` shape vs init/doctor warnings shape). **Deferred → `wip/optionals/deferred-step-e-review-tradeoffs.md`:** (2) API-runner absent arm (cross-repo gated, already in hand-off notes), (5) builder runner_code codegen crashes on absent optional output (pre-existing, builder-layer pass), (6) `\|length` on singular still raises (D4 keeps length a list concept; candidate guard-lint extension), + reviewer's below-cut latent facade gap and pre-existing no-span-on-lifted-leaf. |
-| F (final) | `b66bd751a` (+ triage commits: conformance `39c5b4e`, workspace root `caea84e`, `_optionals` checkpoint commit) | docs review: 5 findings, all doc-accuracy — fixed/deferred; conformance+spec review: 8 findings — 2 blockers fixed, rest fixed/mitigated | Two cold Sonnet reviews (docs diff `65e50f6a3..HEAD`; conformance `436d037..HEAD` + workspace-root spec diff). **Docs review:** run.md "Absent main output" over-claimed vs the Step-E code (no `main_stuff.html` on the absent arm; `--save-csv` exits 1 with an explicit error, consistent with its non-flat-list arm; console prints the reason only, provenance chain lives in `main_stuff.md`) → paragraph rewritten to match reality; PipeBatch.md claimed dropped branches ledger an absence record — they only log → doc corrected + ledger-parity question deferred (`deferred-step-f-notes.md`); EOF newline added; the new optionality guide verified fully clean. **Conformance review:** (1)+(2) CONFIRMED blockers — the `pending_feature_skip_reason` gate ran AFTER each arm's hard assertions, so `optional_output_required` (new semantics on OLD syntax → a pre-optionals runtime says VALID) hard-failed both arms → gate now decided first, with a lenient `_observed_validation_errors` probe on the CLI arm; (3) gating logic had zero unit coverage (it live-skips everywhere until release) → `runtime_supports_case` valid-probe + fallback tests and a new `test_validation_contract_gate.py` harness module; (4) spec hardcoded counts → count-free wording; (5) probe-skips greppability — already mitigated (both modules import + cite `OPTIONALS_PENDING_FEATURE`; removal checklist names them); (6) duplicated hand-rolled warning assertions → shared `REDUNDANT_FORCE_WARNING_ITEM` through `assert_categorized_validation_item` on both arms; (7) stale `pending_runtime_feature` field docstring → documents both probe paths; (8) two TestClasses in one module → HTTP-arm valid coverage split per spec section (`test_validate_warnings.py`), probe shared via conftest. **Bonus:** `CONFORMANCE_CLI_<NAME>` env override added (precedent `CONFORMANCE_PIPELEX_PYTHON`) and used to validate ALL gated CLI-arm coverage LIVE against this worktree — every row asserts and passes, zero skips. Also unblocked a local-env drift: the main checkout moved to `release/v0.37.0` mid-session (release cut) and stale untracked `conformance/.pipelex/pipelex.toml` carried `temporal_dynamodb`, breaking the pinned CLI's boot — section stripped (backup kept), mirroring the June ~/.pipelex strip. All gates re-run green after triage: conformance agent-check + FULL agent-test (exit 0, gates skip correctly) + check-spec-links; pipelex docs-check. |
-
-## Decisions & deviations log
-
-(fill at checkpoints — anything done differently from `wip/optionals/optionals-plan.md`, with why)
-
-- **Step A — parser is combo-permissive; validators own the mutual-exclusion rule.** `parse_concept_with_multiplicity` accepts `X[]?` (multiplicity + marker) and returns both; the D1 v1 rule (markers mutually exclusive with multiplicity) is enforced at the blueprint/spec layer where the input-vs-output context is known, raising the typed `OPTIONAL_MARKER_INVALID`. Rejecting in the parser would have degraded those cases to untyped syntax errors.
-- **Step A — `OPTIONAL_MARKER_INVALID` is a `PipeValidationErrorType` raised as `PipeValidationError` inside blueprint validators**, riding the existing pydantic-unwrap machinery (`extract_wrapped_pipe_validation_error`) exactly like `BATCH_ITEM_NAME_COLLISION`. No categorizer change needed.
-- **Step A — the naive `[`-splitter was renamed** `strip_multiplicity_from_concept_ref_or_code` → `strip_markers_from_concept_ref_or_code` (it now strips presence markers too; the old name would have lied). Internal helper, single caller (`pipe_factory`).
-- **Step A — runtime gates pinned to `declared_names`.** The three `pipe_abstract` enumeration sites + `pipe_extract.required_variables` now use `declared_names` (all inputs), so an input declared `?` is still enforced-present at run time in Step A — exact current behavior preserved; Step B flips the gates to the trichotomy.
-- **Step A — derived batch-list needs stay presence-plain.** In `pipe_parallel`/`pipe_sequence`, the computed list-input specs that override `multiplicity=True` (batch `input_list_name` derivation) do not carry the inner spec's presence (a plural + marker combo is exactly what D4 forbids); all pass-through `add_stuff_spec` sites carry `presence=stuff_spec.presence`.
-- **Step A — two stale fixtures updated**, since a trailing `!` is now legal grammar: `test_pipe_blueprint.py` invalid-syntax cases switched to genuinely malformed specs (`Invalid@Format`, `Invalid@Concept`).
-- **Step B — the lift gate reads the pipe's OWN declared presence, not the needed-aggregation.** A controller's `needed_inputs()` carries its children's markers (a sequence over a step needing `X` plain aggregates `X` plain even when the sequence declares `X?`). Lifting on the aggregated marker would skip the whole controller instead of letting its steps lift. `_scan_input_presence` therefore prefers `self.inputs.root[name].presence` (the boundary contract, D5 "boundaries explicit") and falls back to the needed spec's marker. Consequence: whole-controller lifting still happens when the author declares the input plain at the controller boundary — which is the intended semantics.
-- **Step B — the declared-vs-needed controller input check no longer compares presence markers.** With presence on `StuffSpec`, the old full-model `!=` would have rejected exactly the legal D3 shapes (controller `X?` over child-needed `X` plain) with an empty mismatch summary. The check now compares concept + multiplicity explicitly; presence relationships across the boundary are all legal per the trichotomy (Step D's taint pass reasons about them).
-- **Step B — `validate_before_run` returns the presence scan** (`InputPresenceScan`: missing / forced-absent / liftable) instead of `None`; it owns all three raise cases (force → `OptionalValueAbsentError`, missing-no-record → `PipeRunInputsError` with the run-mode-correct label + optional-inputs hint) and skips resource checks + per-pipe `_validate_before_run` when the pipe is about to be lifted (pipe-specific validation would inspect inputs the pipe never consumes — e.g. PipeCondition's expression render would crash on the absent var).
-- **Step B — value-supersedes-record invariant:** `set_stuff` pops the absence record under the written name; `set_new_main_stuff` also pops the positional `main_stuff` record. The D4 plural note is written AFTER the empty list so it survives as an observability note (stuff wins in `resolve_stuff`).
-- **Step B — lifting applies in dry mode too** (uniform gate): records never exist in today's dry sweeps (mock seeding is all-present per D6), so this is unreachable until Step C's continue-under-dry work, which will pin the dry semantics.
-- **Step B — sequence test builds pipes in code** (`get_pipe_library().add_new_pipe`) instead of an `.mthds` fixture: a bundle declaring `PipeFunc`s can't validate standalone (the functions aren't registered in the validation hook's process).
-- **Step C — dry-run `continue` parity keys on "no mapped pipes", not "no main stuff".** The dry sweep runs every mapped outcome, so when `pipe_dependencies()` is non-empty the mapped pipes' stamped outputs stand (the continue arm is Step D's static concern). Only an all-special-outcomes condition records the declared-absent output in dry — including over a pre-existing main stuff, mirroring the live supersede rule.
-- **Step C — batch compaction shipped (D4 bonus), ungated.** The tri-state collect loop drops any absent branch result — no check that the inner output is declared `?`. Rationale: a `ListContent` cannot hold a hole, so compaction is the only lossless runtime behavior; whether the author *may* rely on it is Step D's static story. The old xfail `test_pipe_condition_continue_output_type` ("identifies a bug") is un-xfailed and pins the fixed semantics: live = compacted list, dry = every mapped outcome modeled (one mock item per batch item).
-- **Step C — parallel ledger note is re-keyed to the branch result name.** `_make_lifted_output` records the branch absence under the sub-pipe's `output_name` already; the combine defensively re-keys via `model_copy(update={"variable_name": ...})` if a record ever arrives under another name, so the parent ledger always speaks in result names.
-- **Step C — delivery absence artifact shape:** `main_stuff.json` = `{"absent": true, ...AbsenceRecord dump...}` (explicit discriminator so consumers can tell an absence doc from a value dump), `main_stuff.md` = human-readable summary + provenance chain, `main_stuff.html` = escaped `<pre>` of the JSON. `main_stuff_viewer.html` is NOT produced for absences (nothing to view). Raw arm reads the serialized `absences` ledger; a malformed raw record degrades to the loud contract-violation error.
-- **Step C — PipeCondition docs page was stale** (`pipe_map` / `default_pipe_code` — fields that don't exist in the language; it's `outcomes` / `default_outcome`, and `default_outcome` is required). Fixed while documenting the new `continue` semantics + migration idiom on that page.
-- **Step C (checkpoint triage) — the ledger API now distinguishes NOTE from RESOLUTION.** `record_absence` = pure ledger note beside a possible value (D4 plural note); `record_resolved_absence` = the slot's resolution, removing any stale value/alias under the name (mirror of `set_stuff`'s value-supersedes-record). `record_new_main_absence` and the parallel branch arm go through the resolution form. Found by the Checkpoint C cold review (stale value outranked a fresh absence under a colliding name).
-- **Step C (checkpoint triage) — non-required structured fields absorb absence as their DEFAULT, not hardcoded `None`.** Deliberate: an author-declared default on an optional field is per-field coalescing avant la lettre (phase-2 `??` preview). Docs + changelog say "field default (`None` unless the author declared another default)".
-- **Step D — the taint pass is a separate walk, not a presence dimension inside `needed_inputs`.** The plan wording ("`needed_inputs`/`generated_outputs` gain the presence dimension") would have entangled taint state with the input-aggregation used by unrelated validation. Instead: `PipeSequence.analyze_taint()` / `PipeParallel.analyze_branch_taint()` re-use `needed_inputs()` per step and track presence in their own `slot_taints` map — same bookkeeping, isolated concern, and the liftable-pipe inventory reuses the identical analyses.
-- **Step D — `OPTIONAL_OUTPUT_REQUIRED` fires at pipe construction** (`validate_output_static`, inside the pydantic model validator, wrapped like `OPTIONAL_MARKER_INVALID`), not at library validation: outcome map and output declaration are both local to the pipe, so the earliest gate wins.
-- **Step D — guard-lint coverage extended beyond the plan's "prompts":** PipeLLM (prompt + system_prompt), PipeCompose (template mode), PipeCondition (expression), PipeSearch (prompt), PipeImgGen (prompt + negative_prompt) — every pipe rendering authored templates over its inputs. PipeCompose construct mode composes structured fields, not authored templates: not linted.
-- **Step E — the agent-API run core's absent arm is GATED on the cross-repo mthds bump.** The mthds SDK wire models (`DictWorkingMemoryAbstract`: root + aliases, `extra="forbid"`) cannot carry the absences ledger, so `_run_core_api.py` keeps its contract-violation raise (message swept to the new invariant wording) with a comment marking the gate. Everything else on the §14 checklist landed.
-- **Step E — `warnings` also ride the agent-CLI whole-bundle validate surfaces**, not just the protocol report: `validate_bundle_core` and `validate_pipe_in_bundle_core` attach `warnings` (dumped `exclude_none`, mirroring the error-items projection); `validate_pipe_core` (no bundle context) does not. Rationale: the lint's cross-flow aggregation needs the whole loaded bundle, which those surfaces have.
-- **Step E — redundant-`!` aggregation is deliberately conservative.** A warning fires only when the (pipe, variable) has ≥1 redundant observation and 0 asserting observations across ALL analyzed flows; a `!` input on a pipe referenced by no controller yields no observation and no warning (no flow context to judge it in). This guarantees the lint never tells an author to remove a `!` some flow relies on.
-- **Step E — otel INPUTS capture also learned the absence arm** (site not on the §14 checklist): `make_inputs_json` hard-read every needed input and crashed on a running controller whose `?` input was absent (found by the new end-to-end test). Value → as before; recorded absence → absence payload; neither → still the loud hard-miss raise.
-- **Step E — pre-existing truthiness bug fixed (load-bearing for D7):** `StuffArtefact` had no `__bool__`, so Jinja2's truth test (`{% if var %}` — exactly the guard idiom the Step D lint recommends) fell through to the list-only `__len__` and raised `TypeError` on a PRESENT singular value. Found when the new `@?hint` contract fixture failed its dry run. Fix: present non-list artefact is truthy; list artefacts follow emptiness (`[]` falsy, D4). Changelog entry under Fixed.
-- **Step E — the optional-edge marker is producer-side data:** the run epilogue stamps `extra={"optional": True}` on the output IOSpec when the pipe declares a `?` output; edge generation (tracer + assembler) reads the producer's registered output spec for the digest (shared `output_digest_is_optional` helper since the checkpoint triage). A skipped node with a SINGULAR output registers no output spec (a recorded absence has no payload), so no data edge leaves it; a skipped node with a PLURAL output registers its real empty-list output (see the triage entry below), so its data edges resolve like any produced value.
-- **Step E (checkpoint triage) — skipped nodes register real outputs.** `on_pipe_end_skipped` (protocol, NoOp, tracer, manager, `PipeEndSkippedEvent`, assembler) gained optional `output_spec`/`output_concept_data`, registered in the producer map exactly like a success output. The run epilogue now computes the output spec on BOTH arms (a lifted plural output is a real empty-list Stuff per D4) and, on the lifted arm, also registers plural companion slots via `register_controller_output` (the companion-slot registration is exercised only under an `add_each_output` lift with tracing on — covered by the code path, no dedicated test; the main-output arm is unit-tested on both builders).
-- **Step E (checkpoint triage) — one taint walk per validate pass.** `collect_controller_taint_analyses` (`pipelex/pipeline/controller_taint.py`) runs each controller's analysis once; `build_liftable_pipes` and `build_optionality_warnings` now take the analyses, not pipes. Every warnings call site (protocol report, agent-CLI cores, bare CLI, builder validate_ops) goes through the collector. Deeper memoization (recompute inside `validate_output_with_library` / enclosing walks) stays deferred (Step D item 2, carried into the Step E deferred doc).
-- **Step E (checkpoint triage) — the lint now reaches all four validate surfaces.** Bare `pipelex validate` prints warnings in yellow (bundle arm + `--all` sweep; advisory, never the exit code); the three bundle-context builder `validate_ops` twins carry the same `warnings` key as their agent-CLI cores. Single-pipe surfaces stay lint-less on every CLI (no flow context).
-- **Step E (checkpoint triage) — absence artifact renderers centralized.** `build_absence_json` (clean_json_dumps, indent=2) and `build_absence_html` (escaped `<pre>`) joined `absence_render.py`; the bare CLI (`--save-main-stuff`), the agent CLI envelope, and the delivery executor all render through them — no per-surface serializer drift.
-- **Step F — all conformance coverage is capability-gated, not green-against-HEAD.** The conformance suite never imports pipelex: its CLI arm resolves `pipelex/.venv/bin/pipelex-agent` and its HTTP arm boots `pipelex-api/.venv` — both running the released pipelex (main checkout on `release/v0.37.0`, pre-optionals). So the new table rows carry `pending_runtime_feature` (new field + `pending_feature_skip_reason` helper, the row analog of the QA corpus's `runtime_supports_case`), the new test modules probe-skip (POST/run the marker bundle; not-valid ⇒ runtime lacks optionals ⇒ skip), and the QA cases are gated — `runtime_supports_case` extended to probe a gated VALID case's `expected_is_valid` (a feature bundle an older grammar rejects must be preserved-not-clobbered too). Gate-removal checklist for the release: `wip/optionals/deferred-step-f-notes.md`.
-- **Step F — spec sections match what conformance can pin; absence records stay unverified-marked.** The four new spec sections carry Verified-by links to the gated modules (spec-links validates linkage, not execution). "Absence records on run artifacts" is `<!-- unverified -->` by design: the hosted execute wire cannot carry the ledger until the cross-repo mthds bump (hand-off item 1), and conformance has no execute arm yet — the section documents the canonical pipelex shapes and names the in-repo pins.
-- **Step F — fixture ground truth taken from this branch, not guessed.** Every new fixture was run against `_optionals/.venv/bin/pipelex-agent` (and the local protocol runner for the report artifacts) before its expectations were written down: categories confirmed (`optional_marker_invalid` → `blueprint_validation`; the four taint/lint errors → `pipe_validation`), locators recorded (e.g. `optional_output_required` carries no `variable_names`).
-- **Step F — flagged pre-existing quirk:** inline `$var` immediately followed by ` (` escapes template variable detection (`"Greet $name (nickname: ...)"` reports `name` as unused — likely Jinja2 parsing `name (…)` as a call). Unrelated to optionals; noted in `wip/optionals/deferred-step-f-notes.md`.
-- **Step F — cross-repo commits ride the repos' current working branches** (conformance `feature/config-dialect-fixture`, workspace root `feature/SDK-and-starter`) — the same branches the previous spec/conformance commits landed on; only the optionals files were staged. Flag for Louis: both carry unrelated in-flight work, so pick the merge vehicle at push time.
-- **Step D (checkpoint triage) — lifting learned companion slots.** `_make_lifted_output` (a Step B site) only resolved the pipe's own output slot; a lifted `add_each_output` parallel left its branch slots neither-value-nor-record — a hard miss downstream on flows the new static pass declares safe. New `PipeAbstract.lifted_companion_slots()` hook (overridden by PipeParallel) resolves each branch slot on lift (singular → SKIPPED record, plural → empty list), and the sequence taint walk keys its lifted-parallel arm on the same hook so static and runtime cannot diverge.
diff --git a/wip/optionals/optionals-plan.md b/wip/optionals/optionals-plan.md
index a76d247b5..e52a8538c 100644
--- a/wip/optionals/optionals-plan.md
+++ b/wip/optionals/optionals-plan.md
@@ -1,12 +1,12 @@
# Optionals — phase-1 implementation plan (CLOSED — phase 1 complete)
-> **Status: COMPLETE.** All steps A–F landed and the FINAL CHECKPOINT cleared — see [optionals-phase1-tracker.md](optionals-phase1-tracker.md) (checkpoint log + hand-off notes, archived from the worktree-root `TODOS.md`). Live follow-ups: the release-time conformance gate removal and cross-repo wave items in `wip/optionals/deferred-step-f-notes.md`. This document is kept as the narrative record; `wip/optionals/optionals-design.md` remains the design reference (incl. phases 2–3).
+> **Status: COMPLETE.** All steps A–F landed and the FINAL CHECKPOINT cleared — the tracker holding the checkpoint log + hand-off notes is kept at workspace level. Live follow-ups: the release-time spec-suite gate removal and cross-repo wave items in `wip/optionals/deferred-step-f-notes.md`. This document is kept as the narrative record; `wip/optionals/optionals-design.md` remains the design reference (incl. phases 2–3).
-Branch `feature/Optionals` (worktree `_optionals`). Design: `wip/optionals/optionals-design.md` — all decisions D1–D11 decided. This plan covers **phase 1 of §17**: the complete language core in pipelex, with `docs/specs/` + `conformance/` moving in the same change. The LLM maybe-wrapper (phase 2) and ergonomics (phase 3) are out of scope; the cross-repo wave (mthds spec, vscode/plxt, mthds-ui, skills) follows the pipelex release and must land **after** the Required-main-stuff Phase 3 sweep.
+Branch `feature/Optionals` (worktree `_optionals`). Design: `wip/optionals/optionals-design.md` — all decisions D1–D11 decided. This plan covers **phase 1 of §17**: the complete language core in pipelex, with the protocol spec and our cross-repo spec suite moving in the same change. The LLM maybe-wrapper (phase 2) and ergonomics (phase 3) are out of scope; the cross-repo wave (mthds spec, vscode/plxt, mthds-ui, skills) follows the pipelex release and must land **after** the Required-main-stuff Phase 3 sweep.
Working rules: TDD (red tests first per step), `make agent-check` after every code change, full `make agent-test` at each checkpoint, one commit per checkpoint, no backward compatibility (breaking changes go in the changelog under `[Unreleased]`).
-Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in `TODOS.md` at the worktree root, now archived as [optionals-phase1-tracker.md](optionals-phase1-tracker.md); this document stays the narrative plan.
+Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in `TODOS.md` at the worktree root, now archived as the phase-1 tracker at workspace level; this document stays the narrative plan.
## Step A — grammar and carriers (parse `?` / `!`, no behavior change)
@@ -16,7 +16,7 @@ Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in
- Builder specs mirror the blueprint rules (`to_blueprint()` passes markers through); `contract_match` canonicalization compares presence markers (D5).
- Tests: parser unit tests for every marker × multiplicity combination, blueprint + spec accept/reject fixtures.
-**CHECKPOINT A** — markers parse, validate, and round-trip; zero runtime behavior change; all gates green; run the checkpoint protocol in [optionals-phase1-tracker.md](optionals-phase1-tracker.md).
+**CHECKPOINT A** — markers parse, validate, and round-trip; zero runtime behavior change; all gates green; run the checkpoint protocol from the phase-1 tracker (kept at workspace level).
## Step B — absence at runtime (ledger + trichotomy + lifting)
@@ -28,7 +28,7 @@ Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in
- Mock seeding / dry-run sweep learn optional slots (dry run stays all-present per D6).
- Tests: lift-skip chain with provenance, absorb, force-failure UX (assert the message names variable, pipes, and reason), plural normalization, optional method inputs, run-report absence enumeration.
-**CHECKPOINT B** — absence exists, propagates, and fails loudly only through `!`; all gates green; run the checkpoint protocol in [optionals-phase1-tracker.md](optionals-phase1-tracker.md).
+**CHECKPOINT B** — absence exists, propagates, and fails loudly only through `!`; all gates green; run the checkpoint protocol from the phase-1 tracker (kept at workspace level).
## Step C — controllers: `continue` replacement + parallel combine (D11)
@@ -37,7 +37,7 @@ Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in
- PipeBatch compaction (D4 bonus): inner `?` output → absent branch results dropped from the aggregated list. Ship it here if it falls out of the lifting machinery naturally; otherwise defer to phase 2 with the semantics recorded.
- Tests: continue-absent (live + dry), parallel with absorbed/omitted/required-absent branches, batch compaction if shipped.
-**CHECKPOINT C** — controllers speak absence; the #1014 `continue` tests replaced; all gates green; run the checkpoint protocol in [optionals-phase1-tracker.md](optionals-phase1-tracker.md).
+**CHECKPOINT C** — controllers speak absence; the #1014 `continue` tests replaced; all gates green; run the checkpoint protocol from the phase-1 tracker (kept at workspace level).
## Step D — static validation: the taint pass + template lint
@@ -47,7 +47,7 @@ Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in
- Liftable-pipe inventory as structured data on the valid report (D3 phase-1 commitment), beside `pipe_io_contracts`.
- Tests: taint fixtures (valid + each error type), guard-lint accept/reject, `@?` detection.
-**CHECKPOINT D** — validation proves the safety theorem ("every absence source reaches an explicit sink"); all gates green; run the checkpoint protocol in [optionals-phase1-tracker.md](optionals-phase1-tracker.md).
+**CHECKPOINT D** — validation proves the safety theorem ("every absence source reaches an explicit sink"); all gates green; run the checkpoint protocol from the phase-1 tracker (kept at workspace level).
## Step E — wire, boundaries, and graph
@@ -58,11 +58,11 @@ Live progress tracking (checkboxes, checkpoint log, decisions/deviations) was in
- Sweep the invariant prose to "a pipe run always resolves its declared output: a value or a recorded absence".
- Tests: end-to-end absent-main-output run over each surface (delivery artifacts, execute response, CLI output, telemetry), graph skipped-state serialization.
-**CHECKPOINT E** — an absent result is a first-class success everywhere in-repo; all gates green; run the checkpoint protocol in [optionals-phase1-tracker.md](optionals-phase1-tracker.md).
+**CHECKPOINT E** — an absent result is a first-class success everywhere in-repo; all gates green; run the checkpoint protocol from the phase-1 tracker (kept at workspace level).
-## Step F — specs, conformance, docs, release prep
+## Step F — specs, spec suite, docs, release prep
-- `docs/specs/` protocol spec: `optional` flag, `warnings` array, absence records, new validation-error categories; matching `conformance/` fixtures (`optional_not_handled.mthds` etc.) + error-QA corpus rows; `make check-spec-links` green.
+- Protocol spec: `optional` flag, `warnings` array, absence records, new validation-error categories; matching fixtures (`optional_not_handled.mthds` etc.) + error-QA corpus rows in our cross-repo spec suite; the spec-link check green.
- Regenerate the MTHDS JSON schema and error pages; docs: an optionality guide beside `multiplicity.md`'s pipelex counterpart, pipe-page updates (PipeCondition, PipeParallel, PipeBatch), `@?` docs reconciled.
- Changelog under `[Unreleased]`: breaking — `continue` semantics, `?`/`!` grammar, protocol additions.
- Full `make agent-test` + `make tb`.
diff --git a/wip/parity/README.md b/wip/parity/README.md
index 04af4d530..3e0001547 100644
--- a/wip/parity/README.md
+++ b/wip/parity/README.md
@@ -24,7 +24,7 @@ This track fixes a family of defects that share one shape: a single authored fac
- **Phase 0 (planning): ✅ done 2026-08-03.** Plan written, targets verified on this tree, decisions D-1..D-3 posed with recommendations.
- **Phase 1: ✅ done 2026-08-03.** All three fixes landed with their gates, red-green verified; Checkpoint A recorded in the plan. D-1 settled as crate-wide resolution (not own-domain-first — see [`d1-domain-hint-deferred.md`](d1-domain-hint-deferred.md)); D-2 settled as recommended.
-- **Phase 2: ✅ done 2026-08-04, folded into the kernel stack.** 2.1 fixed in #1081; 2.3 fixed in #1082, with the boot-contract arm it turned out to owe in the same PR and the doc review on #1083 — commits named by subject in [`parity-gaps-plan.md`](parity-gaps-plan.md), because the stack is rebased and hashes do not survive it. 2.2 **withdrawn** on re-verification — the façade's single `model` wins the object resolution's first rung, so the style it derives already matches an interpreted run for every call the façade can express; the surviving narrowness is deferred as KF-16, because the whole model-derived-style mechanism is slated to become an explicit user choice (design in `wip/prompting-style/README.md`, which ships on the kernel stack — not on this branch). D-3 settled as recommended, (a), and its predicted layering cost did not materialise.
+- **Phase 2: ✅ done 2026-08-04, folded into the kernel stack.** 2.1 fixed in #1081; 2.3 fixed in #1082, with the boot-contract arm it turned out to owe in the same PR and the doc review on #1083 — commits named by subject in [`parity-gaps-plan.md`](parity-gaps-plan.md), because the stack is rebased and hashes do not survive it. 2.2 **withdrawn** on re-verification — the façade's single `model` wins the object resolution's first rung, so the style it derives already matches an interpreted run for every call the façade can express; the surviving narrowness is deferred as KF-16, because the whole model-derived-style mechanism is slated to become an explicit user choice (design in [`../prompting-style/README.md`](../prompting-style/README.md), which landed with the kernel stack). D-3 settled as recommended, (a), and its predicted layering cost did not materialise.
## Deferred, not dropped
diff --git a/wip/parity/SESSION-HANDOFF.md b/wip/parity/SESSION-HANDOFF.md
index f5a15a464..1656913ca 100644
--- a/wip/parity/SESSION-HANDOFF.md
+++ b/wip/parity/SESSION-HANDOFF.md
@@ -45,7 +45,7 @@ Backups to roll back to: `backup/parity-pre-round3` and `backup/kernel-{,phase2-
**Next actions, in order:**
1. Read the bot feedback on all four — **review bodies and inline comments, not check states** (see the cubic trap below). Greptile posts as *issue comments*; cubic posts *reviews* + issue comments; Codex posts reviews. If Greptile and Codex stay silent again, decide whether to chase them or proceed on cubic alone.
-2. Fan out an **Opus 5** sub-agent to dedupe, verify each item, and arbitrate — fixing **only clear wins**, no over-engineering, no guarding impossible scenarios. Anything doubtful becomes a `.md` in `wip/parity/` (or `wip/kernel/` for stack items). Tell the sub-agent it is **STRICTLY READ-ONLY**.
+2. Fan out an **Opus 5** sub-agent to dedupe, verify each item, and arbitrate — fixing **only clear wins**, no over-engineering, no guarding impossible scenarios. Anything doubtful becomes a `.md` in `wip/parity/`. Tell the sub-agent it is **STRICTLY READ-ONLY**.
3. Merge in order **#1081 → #1082 → #1083**. #1085 is independent of the stack and can merge whenever Louis chooses.
**A trap this round taught, now written into the kernel plan:** a doc that lives *on* a stacked branch must name commits **by subject, never by SHA**. Every rebase of the parent rewrites every hash on the child, so the SHAs are dead before anyone reads them — including the "corrected" ones a reviewer suggests. Cubic's proposed replacements were themselves already stale when the fix was written.
diff --git a/wip/parity/bare-pipe-ref-spec-divergence.md b/wip/parity/bare-pipe-ref-spec-divergence.md
index 0005511c4..633ced409 100644
--- a/wip/parity/bare-pipe-ref-spec-divergence.md
+++ b/wip/parity/bare-pipe-ref-spec-divergence.md
@@ -40,11 +40,11 @@ See [`d1-domain-hint-deferred.md`](d1-domain-hint-deferred.md) for the narrower
Three reasons, and the third is decisive.
1. **It is a behavior change to the language, not to a reader.** Every `.mthds` in the wild that leans on cross-domain bare resolution stops loading. That is the opposite of a zero-behavior-change parity fix.
-2. **It is cross-repo.** The rule lives in `mthds/` (the standard) and is implemented in `pipelex/`; `conformance/` would need the case, and any bundle in `pipelex-cookbook/`, the demo repos or the hub that relies on the fall-through would need qualifying. A one-line resolver change does not scope it.
+2. **It is cross-repo.** The rule lives in `mthds/` (the standard) and is implemented in `pipelex/`; our cross-repo spec suite would need the case, and any bundle in `pipelex-cookbook/`, the demo repos or the hub that relies on the fall-through would need qualifying. A one-line resolver change does not scope it.
3. **The direction of the fix is genuinely open, and it is not this track's call.** Either the runtime tightens to the spec, or the spec loosens to describe what every implementation actually does. The second is not obviously wrong — cross-domain bare resolution inside a single crate is convenient and has evidently been relied on. Picking one is a language-owner decision.
## What to do with it
-Raise it with whoever owns the MTHDS spec, together with D-1. Whichever way it settles, the change lands in one PR carrying: the resolver, the crate normalizer (they must move together — that is this track's whole lesson), the spec page, a `conformance/` case, and the sweep of any bundle that relied on the old behavior.
+Raise it with whoever owns the MTHDS spec, together with D-1. Whichever way it settles, the change lands in one PR carrying: the resolver, the crate normalizer (they must move together — that is this track's whole lesson), the spec page, a cross-repo spec-suite case, and the sweep of any bundle that relied on the old behavior.
**Do not fix one reader and not the other.** That is the defect class this entire track exists to remove, and it would be an unusually ironic way to reintroduce it.
diff --git a/wip/parity/parity-gaps-plan.md b/wip/parity/parity-gaps-plan.md
index a0a81603a..afb070faa 100644
--- a/wip/parity/parity-gaps-plan.md
+++ b/wip/parity/parity-gaps-plan.md
@@ -118,7 +118,7 @@ The re-verification the plan asked for happened against each PR's own branch rat
*The mechanism is obsolete.* Model-derived prompting style dates from when models were genuinely sensitive to prompt markup. Louis' ruling: rather than widen the derivation, the style becomes an explicit user choice defaulting to XML, and the derivation goes away. Building `model_for_object` here would mean constructing the two-setting derivation that refactor deletes.
-Deferred as **KF-16** in `wip/kernel/deferred-follow-ups.md`, with the design in `wip/prompting-style/README.md` — both ship on [PR #1081](https://github.com/Pipelex/pipelex/pull/1081), not on this branch, hence plain paths rather than links (they resolve once that PR merges to `dev`). Silenced in #1081 by *number the prompting-style follow-up KF-16 to keep the stack's* — a docstring on `llm_object` recording why its single `model` is correct, carrying the trap explicitly: *do not "fix" this by deriving the style from an object-only resolution, which would introduce the divergence rather than close it.*
+Deferred as **KF-16** in the kernel track's deferred-follow-ups doc (now tracked at workspace level), with the design in [`../prompting-style/README.md`](../prompting-style/README.md) — that design landed with [PR #1081](https://github.com/Pipelex/pipelex/pull/1081) and is present on this branch. Silenced in #1081 by *number the prompting-style follow-up KF-16 to keep the stack's* — a docstring on `llm_object` recording why its single `model` is correct, carrying the trap explicitly: *do not "fix" this by deriving the style from an object-only resolution, which would introduce the divergence rather than close it.*
### 2.3 Nothing in the kernel can build an `ImgGenPrompt`
diff --git a/wip/pipe-compose-whole-stuff-fix.md b/wip/pipe-compose-whole-stuff-fix.md
index c6109e3df..a37c94951 100644
--- a/wip/pipe-compose-whole-stuff-fix.md
+++ b/wip/pipe-compose-whole-stuff-fix.md
@@ -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: `../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.
+Full analysis with the user's original bundle and reasoning lives in an internal demos repo, alongside a runnable repro. Note: that write-up'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`
@@ -112,6 +112,6 @@ All changes in `pipelex/pipe_operators/compose/structured_content_composer.py` (
- [x] `pipelex-plugins/skills/pipelex-design/references/writing-mthds.md` (source of truth; per-target copies under `pipelex-plugins/{pipelex,pipelex-vibe,pipelex-codex}/skills/...`): added a worked whole-stuff copy example (ScreeningReport, mirroring the PipeCompose.md docs example) to the PipeCompose construct section; `make build` propagated to all target copies; no warning added
- [x] `mthds-plugins/templates/skills/shared/mthds-reference.md.j2` (the generated per-target copies come from this template): construct `from` row now reads "Reference a whole input or a nested field" + a note on the whole-native-stuff → native-field automatic conversion; `make build` propagated to all target copies
-- [x] `mcp-demos/wip/pipe-compose-issue/README.md`: annotated — update banner at top, correction blockquote in §5, update blockquote in §8 with the stale takeaways marked inline; root cause = implementation gaps fixed in pipelex v0.39.2, compose-based design recommended again
+- [x] The internal demos write-up: annotated — update banner at top, correction blockquote in §5, update blockquote in §8 with the stale takeaways marked inline; root cause = implementation gaps fixed in pipelex v0.39.2, compose-based design recommended again
-**Phase 4 executed 2026-07-18 — TRACK COMPLETE.** Committed per-repo: `pipelex-plugins` 2f97d2d, `mthds-plugins` 4e6288c, `mcp-demos` d422861.
+**Phase 4 executed 2026-07-18 — TRACK COMPLETE.** Committed per-repo: `pipelex-plugins` 2f97d2d, `mthds-plugins` 4e6288c, plus the internal demos repo.
diff --git a/wip/plugins/README.md b/wip/plugins/README.md
index 19e8654d2..de3ba02f4 100644
--- a/wip/plugins/README.md
+++ b/wip/plugins/README.md
@@ -19,7 +19,7 @@ This is deliberately **not** a `HubSlot` — hub slots are orchestrator-coupled
## Cross-cutting decisions (apply to both)
-- **DX-1 — Batch the plugin-API version bump.** Discovery version-checks `targets_api` against `PLUGIN_API_VERSION` with **strict equality** (`pipelex/plugins/discovery.py`, `_register_plugin`), so *any* additive menu growth is a breaking bump that forces every external plugin to re-declare `targets_api`. Introduce **both** new registrar menu methods (`add_storage_provider` and `add_secrets_provider`) under a **single** `PLUGIN_API_VERSION` bump (2 → 3), even though the two features land in sequence, to avoid double-breaking the external plugins. The known external plugins that must bump their `targets_api` to 3: `pipelex-temporal`, `pipelex-mistralai-workflows`. (Per the workspace "no backward compatibility" principle, that's acceptable — note it in changelogs; there is no transition shim.)
+- **DX-1 — Batch the plugin-API version bump.** Discovery version-checks `targets_api` against `PLUGIN_API_VERSION` with **strict equality** (`pipelex/plugins/discovery.py`, `_register_plugin`), so *any* additive menu growth is a breaking bump that forces every external plugin to re-declare `targets_api`. Introduce **both** new registrar menu methods (`add_storage_provider` and `add_secrets_provider`) under a **single** `PLUGIN_API_VERSION` bump (2 → 3), even though the two features land in sequence, to avoid double-breaking the external plugins. The known external plugins that must bump their `targets_api` to 3: our Temporal plugin and our Mistral Workflows plugin. (Per the workspace "no backward compatibility" principle, that's acceptable — note it in changelogs; there is no transition shim.)
- *Option not taken:* relax discovery to accept `targets_api <= PLUGIN_API_VERSION` for additive growth. That would make menu additions non-breaking but changes the plugin-system contract semantics — out of scope for this track; raise separately if the coarse-bump churn becomes painful.
- **DX-2 — The builtin provider plugin is unconditional.** Storage and secrets are required infra: if the config-selected method has no registered factory, boot must fail loud. The builtin `StoragePlugin` / `SecretsPlugin` therefore join `CORE_UNCONDITIONAL_PLUGIN_NAMES` (`pipelex/plugins/builtins.py`) so they can't be disabled into a broken boot.
- **DX-3 — External-provider config surface is a scoped follow-up.** `StorageProviderConfig` / the new `SecretsProviderConfig` have fixed, typed per-method sub-models. An out-of-tree provider (`azure`, `vault`) needs somewhere to read *its* config. Phase 1 of each plan lands the seam for the built-in methods only; a generic passthrough sub-config for external providers is captured as a follow-up in each plan, not built speculatively.
diff --git a/wip/plugins/secrets-provider-plugin.md b/wip/plugins/secrets-provider-plugin.md
index cdb382236..07e010d3b 100644
--- a/wip/plugins/secrets-provider-plugin.md
+++ b/wip/plugins/secrets-provider-plugin.md
@@ -1,6 +1,6 @@
# Secrets provider → `pipelex.plugins` plugin
-Status: **COMPLETE.** All phases delivered — this vertical (Phases 3–4 of the master plan) mirrors the storage pattern ([storage-provider-plugin.md](storage-provider-plugin.md), which defines the shared "keyed registry + config-selected singleton" mechanism this plan reuses wholesale). See [TODOS.md](../../TODOS.md) for the execution record (Phases 3–4 code + tests + docs, Phase 5 release gating). This plan reads as "mirror storage, swap the nouns."
+Status: **COMPLETE.** All phases delivered — this vertical (Phases 3–4 of the master plan) mirrors the storage pattern ([storage-provider-plugin.md](storage-provider-plugin.md), which defines the shared "keyed registry + config-selected singleton" mechanism this plan reuses wholesale). The execution record (Phases 3–4 code + tests + docs, Phase 5 release gating) lived in the branch's root tracker. This plan reads as "mirror storage, swap the nouns."
Goal: turn the secrets provider into a formal plugin seam so third parties can ship `pipelex-secrets-<backend>` packages (Vault, AWS Secrets Manager, GCP Secret Manager, …) discovered via `pipelex.plugins` and selected at deploy time. The built-in `EnvSecretsProvider` becomes an unconditional builtin plugin.
@@ -127,7 +127,7 @@ Because there's only one built-in method, introducing a config selector for a si
- [ ] Manual: `pipelex plugins list`; a run with default `method="env"`; confirm `get_secret(...)` still resolves env vars.
## Cross-repo consequence (release-gated)
-- Same as storage: `pipelex-temporal` / `pipelex-mistralai-workflows` bump `targets_api` to 3 (only once, if batched with storage per DX-1).
+- Same as storage: our Temporal and Mistral Workflows plugins bump `targets_api` to 3 (only once, if batched with storage per DX-1).
## Follow-ups (do not build now)
- **S4 external config passthrough** for out-of-tree secrets providers.
diff --git a/wip/plugins/storage-provider-plugin.md b/wip/plugins/storage-provider-plugin.md
index c0e6a0b4c..5a85bfc12 100644
--- a/wip/plugins/storage-provider-plugin.md
+++ b/wip/plugins/storage-provider-plugin.md
@@ -1,6 +1,6 @@
# Storage provider → `pipelex.plugins` plugin
-Status: **COMPLETE.** All phases delivered — this vertical (Phases 1–2 of the master plan) defines the shared "keyed registry + config-selected singleton" mechanism (§ The new mechanism) that the secrets plan reuses. See [TODOS.md](../../TODOS.md) for the execution record (Phases 1–2 code + tests + docs, Phase 5 release gating).
+Status: **COMPLETE.** All phases delivered — this vertical (Phases 1–2 of the master plan) defines the shared "keyed registry + config-selected singleton" mechanism (§ The new mechanism) that the secrets plan reuses. The execution record (Phases 1–2 code + tests + docs, Phase 5 release gating) lived in the branch's root tracker.
Goal: turn the storage provider into a formal plugin seam so third parties can ship `pipelex-storage-<backend>` packages discovered via the `pipelex.plugins` entry-point group and selected at deploy time by `storage_config.method`. The built-in providers (local / in_memory / s3 / gcp) become a single unconditional builtin plugin registering their factories — exactly as `OpenAIPlugin` registers several inference backends.
@@ -123,7 +123,7 @@ Net effect: `make_storage_provider_from_config` and its `match` are deleted; the
- [ ] Manual: `pipelex plugins list`; a real run with `method="local"`; flip to `method="in_memory"` and confirm selection.
## Cross-repo consequence (release-gated, not this PR)
-- `pipelex-mistralai-workflows` must bump `targets_api` to 3 (DX-1); it registers no storage provider and imports none of the removed symbols, so the bump is its only change. `pipelex-temporal` needs the bump **and** a code migration: its payload-codec factory (`pipelex_temporal/codec/codec_factory.py`) imports the now-removed `make_storage_provider_from_config` and must switch to `get_storage_provider_registry().get_required(method=...)`. Do both when the pipelex version carrying this lands, not before.
+- Our Mistral Workflows plugin must bump `targets_api` to 3 (DX-1); it registers no storage provider and imports none of the removed symbols, so the bump is its only change. Our Temporal plugin needs the bump **and** a code migration: it imports the now-removed `make_storage_provider_from_config` and must switch to `get_storage_provider_registry().get_required(method=...)`. Do both when the pipelex version carrying this lands, not before.
## Follow-ups (do not build now)
- **D3 external config passthrough** — generic `extra` sub-config on `StorageProviderConfig` for out-of-tree providers. This must also fix the **`uri_format` gap**: `StorageProviderConfig.uri_format` (read by `GeneratedContentFactory._build_storage_key` on every content store) is defined only for the four built-in methods and raises `StorageConfigError` on the `case _:` arm for any external token — so an external provider selects and boots cleanly but crashes on the first *generated-content* store. D3 must give external methods a `uri_format` (e.g. promote it to a top-level field, or a passthrough default). Until then the docs page flags external providers as usable for their own storage API but not yet as the generated-content backing store.
diff --git a/wip/pr-1059-review-notes.md b/wip/pr-1059-review-notes.md
index fd4315c21..f855d1e65 100644
--- a/wip/pr-1059-review-notes.md
+++ b/wip/pr-1059-review-notes.md
@@ -25,4 +25,4 @@ Triage record for the SWE-agent review threads on [PR #1059](https://github.com/
## Out of scope for this PR (other repo)
-- **`pipelex-platform` stale API-response docstring.** `pipelex-platform/src/pipelex_platform/routers/v1/runs.py:101-102` still describes `tokens_usages` as "token counts by category + **unit costs** + model id" — stale against the v0.40 `TokensUsageRecord` wire shape (which drops `unit_costs` and carries a server-computed `cost`). Unlike the wip trackers above, that one is a live API-response docstring. Fix belongs in the `pipelex-platform` repo; flagged here so it is not lost.
+One item, a stale API-response docstring in another repo — tracked at workspace level, since nothing about it belongs to `pipelex`.
diff --git a/wip/refactoring/README.md b/wip/refactoring/README.md
deleted file mode 100644
index 684fdc43d..000000000
--- a/wip/refactoring/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Refactoring working notes
-
-This folder holds working notes for refactors that outlived a single PR. Two tracks currently share it — read the section that matches what you are picking up.
-
-## Modularity refactors after the hub split
-
-The three modularity refactors (**M3** split the boot manifest by layer, **M1** made core's layer split physical, **M2** separated the plugin mechanism from the vendor adapters) plus the **F1** img-gen follow-up. They build on the `pipelex.hub` → `runtime_hub` + `interpreter_hub` split recorded in [`../hub/`](../hub/README.md).
-
-**Track parked, not archived** — all four pieces are complete, reviewed and on `dev`; what remains is the cross-repo sweep, which was release-gated and is **no longer blocked** now that v0.41.0 and v0.42.0 have shipped. The executable tracker was moved out of the repo-root `TODOS.md` slot into this folder on 2026-07-29 so that slot is free for whatever is actively being built.
-
-| Document | What it is |
-| --- | --- |
-| [`modularity-refactors-tracker.md`](modularity-refactors-tracker.md) | **The executable tracker** (formerly the repo-root `TODOS.md`) — ordered work, checkboxes, checkpoint records, decisions, measurements, review findings, cold-start brief. Authoritative for *what to do*. ⚠ Its Phase 5 table is the **M1 slice** of the cross-repo sweep, not the whole inventory — the other waves keep their tables in [`../hub/hub-split-tracker.md`](../hub/hub-split-tracker.md#cross-repo-sweep), which is the union home by [prior ruling](../layer-placement-completion.md). Start at its [Cold-start brief](modularity-refactors-tracker.md#cold-start-brief). ⚠ Its branch/PR header is a historical record — the work shipped under different numbers; the note at the top of the file says which. |
-| [`modularity-refactors.md`](modularity-refactors.md) | The design doc — the *why*, the rulings, the measurement snippets. Superseded in part by the tracker after the 2026-07-27 engineering review; kept as the record of the original reasoning. |
-| [`modularity-review-follow-ups.md`](modularity-review-follow-ups.md) | The review items recorded but not fixed, assessed and ready to implement — **FU-1** (an error-class rename is a silent wire break), **FU-2** (the img-gen neutrality guard is weaker than its comment), **FU-3** (the bookkeeping files a bulk rewrite breaks are ungated). Cite the ids. |
-| [`deferred-placement-follow-ups.md`](deferred-placement-follow-ups.md) | Placement and naming accuracy findings from the M1 checkpoint review — no silent bug, no boundary breach, deliberately deferred because the churn is not justified by the defect. |
-
-## Exec-track follow-ups (PR #1076 and `refactor/Follow-ups`)
-
-Unrelated to the modularity track — these are the residue of the execution refactor, kept here because they are refactor notes with no home of their own.
-
-| Document | What it is |
-| --- | --- |
-| [`leaf-conversion-and-search-follow-ups.md`](leaf-conversion-and-search-follow-ups.md) | What a full pre-landing `/review` of `refactor/Follow-ups` surfaced and did not fix. Every claim re-verified against the tree on 2026-07-31, with the command that produced each measurement inline. |
-| [`boundary-revalidation-round-trip-audit.md`](boundary-revalidation-round-trip-audit.md) | The audit of `revalidate_leaf_object`'s boundary conversion — what it established, the one real loss it found and fixed, and the two things still not established. |
-| [`func-registry-entries-outlive-their-library.md`](func-registry-entries-outlive-their-library.md) | PipeFunc registrations survive the teardown of the library that registered them. A genuine narrowing introduced by #1076, recorded rather than fixed because the only correct fix is a design change. |
diff --git a/wip/refactoring/boundary-revalidation-round-trip-audit.md b/wip/refactoring/boundary-revalidation-round-trip-audit.md
deleted file mode 100644
index 31418e9d0..000000000
--- a/wip/refactoring/boundary-revalidation-round-trip-audit.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# The boundary re-validation round trip, audited
-
-Supersedes `boundary-revalidation-round-trip-is-unaudited.md` (deferred out of PR #1076). The audit was done, it found one real loss, the loss is fixed, and the parts that turned out to be safe now have tests so they stay that way. This note records what was established, what was corrected, and the two things still not established.
-
-The conversion in question is the boundary arm of `revalidate_leaf_object` (`pipelex/cogt/content_generation/object_revalidation.py`): `object_class.model_validate(raw_obj.model_dump(mode=dump_mode, serialize_as_any=True, by_alias=True))`.
-
-## Who actually reaches it
-
-**Nothing in this repo.** Every branch of `ContentGenerator.make_object` / `make_object_list` returns an `isinstance` of `object_class`, so the short-circuit always fires and the conversion arm is dead code here:
-
-- **DRY** — `dry_llm_gen_object` resolves the caller's class unchanged and `build_mock_object` builds through polyfactory, whose `build()` instantiates `__model__` itself. The result is exactly `object_class`.
-- **LIVE** — every concrete LLM worker returns instructor's object untouched (`llm_worker_abstract.gen_object` only strips `_raw_response` and reports). Instructor's `prepare_response_model` wraps the class as `create_model(cls.__name__, __base__=(cls, OpenAISchema))`, a *subclass*, so `isinstance` holds. The Bedrock worker raises `LLMCapabilityError` instead of returning. Gateway / Portkey / Azure / OpenRouter are the OpenAI workers under a different factory, not separate classes.
-- **The list path** wraps only the top-level `ListSchema`; its `items` are constructed by pydantic against `list[item_class]`, so each item is exactly `item_class`.
-
-**The distributed boundary always reaches it.** The activity calls the leaves without a class, so the object is built from a `SchemaToModelFactory` rebuild; kajson re-execs that class from `__kajson_class_source__` on the workflow side and a per-call scoped registry makes the source-derived type win over the globally registered one. A rebuilt class is never a subclass of `object_class`, so the short-circuit cannot fire there — which is exactly the split the design intends.
-
-## What crosses it
-
-In production `object_class` is always a `StuffContent` subclass resolved **by name** from the class registry — the concept's `structure_class_name`. That registry holds the native content classes, the generated `<domain>__<Concept>` structure classes, everything `auto_register_all_subclasses(base_class=StructuredContent)` sweeps out of `sys.modules` (including the builder spec classes), and user classes from library folders. So the set is open: **any field name a user can write in a concept structure can cross this conversion.** That is what makes the loss below matter.
-
-## The loss, and the fix
-
-`datamodel-code-generator` cannot name a field `json`, `copy`, `schema` or `construct` — they shadow `BaseModel` attributes — nor can it use a python keyword. It renames the field (`construct_`) and records the schema's property name as the alias. Dumping **by field name** then emitted `construct_` for a field the caller's class calls `construct`, and re-validation failed with a bare `Field required` — on a field the caller had supplied.
-
-Reproduced, fixed by dumping `by_alias=True`, and pinned by `tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py` (which fails on every shadowing field without it, in both dump modes). The dump now emits exactly the schema's property names, which is what the round trip and the provider are both keyed on. Where nothing was renamed, the rebuilt class's alias *is* its field name, so nothing else changed — the native content classes are parametrized in that test as the control.
-
-The same fix was needed on the structured-search dry boundary arm (`dry_search_gen_structured`), which dumps its mock for the wire.
-
-**`PipeSearchSpec` / `PipeComposeSpec` were the models the old note worried about, and it had the mechanism wrong.** It supposed they survive thanks to `populate_by_name=True`. They do not: `PipeComposeSpec` **failed** this round trip before the fix, because its `construct` property is exactly a shadowed name — `populate_by_name` lets `construct_spec` through, but the dump emitted `construct_`, which matches neither the field name nor the alias. `PipeSearchSpec` survived only because its alias `query` is a legal field name that needed no rename.
-
-## What the old note worried about that is genuinely safe
-
-- **Plain aliases need no compensation.** `model_json_schema()` emits **by alias**, so the shipped schema's property names are the ones `object_class` accepts on the way in, and the rebuilt class's field name simply *is* the alias. This holds with or without `populate_by_name`. Pinned by `test_a_plain_alias_round_trips`.
-- **Subclass erasure is structurally unreachable**, not merely unobserved. The object that crosses is built from `object_class`'s own schema, so it cannot carry a field `object_class` lacks; and the one object that *is* a subclass — instructor's — hits the short-circuit and is never dumped. Nested erasure would need a leaf that produces a subclass instance inside a declared field, which neither arm does. There is no test for this because there is no way to construct the case through this path.
-- **`CompositeContent` survives.** Its `extra="allow"` config comes through the rebuild, so the components it keeps as pydantic extras are preserved rather than dropped as unknown keys. Parametrized in the round-trip test.
-- **`DateContent` / `TimeContent`'s `mode="before"` validators are total over their own serialized output.** They are the closest thing on this path to a validator that would not be, and they only see json mode (the distributed arm): an ISO date survives both the numeric-string and the time-bearing-string rejection.
-
-## Still not established
-
-- **`Mode.PARALLEL_TOOLS` / `VERTEXAI_PARALLEL_TOOLS` would break the short-circuit's premise.** Instructor returns a *generator* in those modes, not an instance of the response model. They are reachable from `StructureMethod` but **no model in the shipped TOMLs selects them**, so this is a config-reachable hazard rather than a live one. If one is ever configured, `make_object` returns something that is neither an instance nor dumpable the way this helper expects — worth a guard at that point, not before.
-- **Whether the json-mode round trip is lossless for every field type a user can write.** The audit covered the native content classes and the alias/rename mechanics; it did not enumerate arbitrary user field types under `mode="json"`. This is the residue of the original note, narrowed: it is now specifically about json-mode coercion on the distributed arm, not about the conversion in general.
-
-## The fix the old note proposed, and why it was not needed
-
-It suggested that if the audit found a real loss, the fix was "probably to have the boundary return raw data rather than a reconstructed instance, so there is one validation instead of a dump of one". That is a larger change — it alters what the object leaf returns across the payload boundary — and the loss found did not require it. Worth keeping in mind if the json-mode residue above ever turns up something `by_alias` cannot fix.
diff --git a/wip/refactoring/deferred-placement-follow-ups.md b/wip/refactoring/deferred-placement-follow-ups.md
deleted file mode 100644
index 6bdc80ea5..000000000
--- a/wip/refactoring/deferred-placement-follow-ups.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Deferred placement follow-ups
-
-Findings from the M1 checkpoint review round that are **placement or naming accuracy, not silent bugs**. Nothing here is broken, nothing here breaches the layer boundary, and no gate is failing because of any of it. Each is recorded rather than fixed because the fix is a rename-and-rewrite wave whose churn is not justified by the defect, and because two of the three are better folded into a later modularity commit than done alone.
-
-## 1. `mthds_parsing/` holds three modules that are not parsing
-
-The package is named for what most of it does, but three tenants do something else:
-
-- **`pipe_sorter.py`** — its only production caller is `pipelex/builder/bundle_spec.py`, the builder's *specs → blueprint* direction. The parser never sorts. It arrived here because it lived in `core/bundles/`, which M1a hoisted wholesale.
-- **`helpers.py`** — mixes two unrelated things. `MTHDS_EXTENSION` and `is_pipelex_file` are a generic file-extension predicate imported across `cli/`, `libraries/` and `builder/`; the rest is parse-error scoping used only inside this package. The generic half has no business behind a parser-named import path.
-- **`handle_pipe_errors.py`** — the M1b changelog says it followed "its importers" into `mthds_parsing`, which is half true: one of its two importers is `pipeline/validate_bundle.py`.
-
-**Why deferred.** None of this is a layering problem — all three are leaves or interpreter-layer consumers, so the closure test and the guard are both indifferent. Fixing it well means splitting the generic extension predicate out (a good candidate for `core/` or `tools/`, touching every one of its importers) and finding `pipe_sorter` a home nearer the builder. That is a coherent commit of its own, not a review-fix.
-
-**Worth noting for contrast:** `pipe_machinery/` was checked module by module in the same review and is accurately named throughout, `validation.py` and `template_guard_lint.py` included.
-
-## 2. Parser test fixtures stayed under `tests/unit/pipelex/core/`
-
-`tests/unit/pipelex/core/test_data/` holds the parser's fixture corpus — `interpreter_test_cases.py` exporting `InterpreterTestCases`, plus the `complex/`, `concepts/`, `domain/`, `errors/`, `pipes/` subtrees. Its consumers are now `tests/unit/pipelex/mthds_parsing/test_parser.py` and `tests/integration/pipelex/language/test_mthds_factory.py`; nothing under `tests/unit/pipelex/core/` uses it any more.
-
-It resolves fine — this is filing, not breakage. Moving it means rewriting the nested `from tests.unit.pipelex.core.test_data.…` imports throughout the subtree and renaming `interpreter_test_cases` / `InterpreterTestCases` to match the `MthdsParser` rename, which is exactly the kind of churn that should ride along with the next commit that touches those tests rather than land on its own.
-
-## 3. ~~The `pipeline` / `pipe_run` leak is now referenced from four places~~ — RESOLVED
-
-`core.pipes.pipe_output` reaches `pipeline.pipeline_models` for a single leaf constant, and `runtime_hub` reaches `pipe_run.pipe_run_mode`. Because of that, neither package can be named in the closure test's `INTERPRETER_PACKAGES` — naming them would fail every entry point on a placement wart rather than on a broken hub arrow.
-
-The M1 review round found that the *statement* of the property had quietly dropped this qualification in three places (the guard's `RUNTIME_LAYER_PACKAGES` note, and two spots in `hub-layering.md`), which is fixed. The underlying wart is not, and the qualification now has to be repeated wherever the property is stated: `runtime_hub`'s docstring, the guard note, `hub-layering.md` "Why the boundary exists", and `hub-layering.md` "Where core splits".
-
-**The remedy is known and is the one `mthds_parsing` already used** (D-M1-8): move the leaf models to a runtime-layer home, *then* widen the predicate. `SpecialPipelineId` and `PipeRunMode` are the two leaves. Doing it would let all four qualifications collapse back to the unqualified claim — which is the real argument for doing it, since a caveat repeated in four places is a caveat that will go stale in at least one.
-
-> **Resolved 2026-07-29** by `refactor/Layer-boundary` ([`../layer-placement-completion.md`](../layer-placement-completion.md)), which took exactly the remedy named above. Everything in this section is now historical and describes a state that no longer exists. The leaves went to runtime-layer homes — `SpecialPipelineId` to `system.job_metadata`, `PipeRunMode` to `system.pipe_run_mode`, plus two the count above missed, `PipeRunParamKey` to `system.pipe_run_param_key` and `PipeRunError` to `core.pipes.exceptions` — `INTERPRETER_PACKAGES` now names both packages, and the qualification is deleted everywhere. The estimate of *four* sites was also low: it was **six**, which is the section's own point about a repeated caveat proving itself.
-
-See also `wip/pr-1062-review-notes.md`, where this leak was first recorded.
diff --git a/wip/refactoring/func-registry-entries-outlive-their-library.md b/wip/refactoring/func-registry-entries-outlive-their-library.md
deleted file mode 100644
index 297aac353..000000000
--- a/wip/refactoring/func-registry-entries-outlive-their-library.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# PipeFunc registrations outlive the library that registered them
-
-Deferred out of PR #1076 (`refactor/Exec`), raised as a P1 by the Codex reviewer and independently by the pre-landing review pass. **This is a genuine narrowing introduced by that PR, not a pre-existing quirk** — recorded here rather than fixed because the only correct fix is a design change, and it is worth deciding on its own terms.
-
-## The scenario
-
-A long-lived process that loads bundles sequentially:
-
-1. `open_library()` → `load_libraries(library_id=A, library_dirs=[…])` — registers `summarize` from project A.
-2. `LibraryManager.teardown(library_id=A)` — tears down A's pipe/concept/domain libraries and its own `ClassRegistry`.
-3. `open_library()` → `load_libraries(library_id=B, …)` — project B also defines `summarize`, at a different path.
-
-Step 3 now raises `FuncRegistryError`. A's registration is still in the registry: `LibraryManager.teardown` does not touch `func_registry`, and only `RuntimeBoot.teardown` clears it. So the "collision" is with a **stale** entry from a library nobody can reach any more, not with a concurrently-live one.
-
-Before #1076 the same sequence silently overwrote, and B won — which for the sequential case was the right outcome. So this path regressed from *works* to *fails until the process restarts*.
-
-## Who this hits
-
-**No first-party host can reach this today** — an earlier revision of this note named two victims, and tracing the code shows both are immune:
-
-- A self-hosted, direct-mode `pipelex-api` cannot vary its PipeFunc directories within one process. `ApiRunner()` is constructed per request with `library_dirs=None`, which `resolve_library_dirs` resolves to instance defaults fixed at boot or `PIPELEXPATH` — both process-constant. The per-request variation is inline `.mthds` text, which registers no functions. Re-scanning the same constant dirs returns `sys.modules`-cached modules, so the same function objects re-register and the idempotent no-op absorbs them.
-- The local MCP workshop (`pipelex-mcp`) is a TypeScript stdio *client* of the Pipelex API — it runs no pipelex in-process, and `.mthds` contents travel as text with no Python. It can only hit whatever server backs it, which is the previous (immune) case or the hosted runner.
-
-Not the hosted runner either: `is_pipe_func_sandbox_hosted()` takes the source-capture branch and never registers in-process. The Temporal worker ignores `library_dirs` outright, and the transported-PipeFunc path is one-shot per process.
-
-The exposed population is a **third-party embedder**: a long-lived Python process passing *different* `library_dirs` per call through the public surface (`PipelexMTHDSProtocol(library_dirs=…)`, `validate_bundles_in_process(library_dirs=…)`, `acquire_library(library_dirs=…)`), where two projects' Python files share a registration name. That is a legitimate use of a public parameter, so the narrowing is real — but when it fires, the failure is loud and typed (`FuncRegistryError` naming both origins and the `@pipe_func(name=...)` remedy), not silent corruption. This is why the narrowing was ruled non-blocking for PR #1076 (decision 2026-07-31): ship with the gap documented, fix ownership in its own PR.
-
-Two loads of the **same** bundle are fine — `import_module_from_file` returns the module cached under its absolute-path key, so the second scan re-registers the identical object and the idempotent no-op absorbs it. The failure needs two *different* files that share a registration name.
-
-## Why it was not fixed in #1076
-
-There is no small correct fix. `func_registry` is a flat, process-global `dict[str, Callable]` with **no ownership dimension** — nothing records which library registered a name, so per-library eviction has nothing to key on. Note the asymmetry that makes this stand out: each `Library` already owns its own `ClassRegistry` (`Library.get_class_registry`, torn down with the library). Functions never got the same treatment.
-
-The reviewer's proposed remedy — "registrations need library ownership and removal on teardown, including rollback after a failed scan" — is correct in substance and is a design change: a new ownership side-table, a `library_id` threaded through `FuncRegistryUtils` into `register_function`, eviction wired into `_pop_and_teardown_library`, and transactional rollback when a scan fails partway. That is not something to slip into a PR at bot-clean state.
-
-## What doing it looks like
-
-Give functions the ownership `ClassRegistry` already has:
-
-1. Thread the owning library id into registration (`FuncRegistryUtils.register_funcs_in_folder` already runs inside `scoped_current_library`, but `func_registry` is runtime-layer and must not import the interpreter's `current_library` — pass the id in as a plain `str`).
-2. Keep a `name -> library_id` side table; evict that library's names in `_pop_and_teardown_library`.
-3. Roll back the names a scan registered when that scan raises partway, so a failed load does not leave half a library behind.
-4. Then the collision check keys on live entries only, and the stale case disappears rather than being papered over.
-
-Do **not** "fix" it by weakening the collision check back to a silent overwrite — that is the bug #1076 exists to remove.
-
-## Related
-
-- The other deferrals out of the same PR are done: the shared revalidation helper and the structured-search class threading landed on `refactor/Follow-ups` (see that branch's `TODOS.md`), and the boundary round trip is now audited in `wip/refactoring/boundary-revalidation-round-trip-audit.md`. This one is the last of the four, and stays its own PR.
diff --git a/wip/refactoring/leaf-conversion-and-search-follow-ups.md b/wip/refactoring/leaf-conversion-and-search-follow-ups.md
deleted file mode 100644
index f51f49fee..000000000
--- a/wip/refactoring/leaf-conversion-and-search-follow-ups.md
+++ /dev/null
@@ -1,315 +0,0 @@
-# Leaf-conversion and structured-search follow-ups — what the review of `refactor/Follow-ups` left open
-
-The items a full pre-landing `/review` of `refactor/Follow-ups` surfaced and **did not fix**. The branch itself carries the critical fixes that review found; this file is the residue.
-
-Every claim below was re-verified against the tree on **2026-07-31 at `2cc27966a` plus the review's own fixes** — that is, *after* the critical work landed, so nothing here is a stale reading of the pre-review tree. The command that produced each measurement is inline, so a new session can re-take it rather than trust it.
-
-**Stable ids:** cite these as **RF-1** … **RF-7**. They are deliberately not `FU-n`: that namespace belongs to the modularity track in [`modularity-review-follow-ups.md`](modularity-review-follow-ups.md), and the two docs sit in the same folder.
-
-| id | one line | verdict | size | blocked on |
-| --- | --- | --- | --- | --- |
-| [RF-1](#rf-1--the-live-validationerror-contract-is-inconsistent-and-the-plugins-own-two-arms-disagree-about-it) | The live-`ValidationError` contract is inconsistent; the plugin's own two arms disagree | **design decision needed** | small code, real thinking | nothing — decide before the sweep |
-| [RF-2](#rf-2--by_alias-and-dump_mode-reach-no-live-path-here-and-the-plugins-copy-diverges-on-the-announced-fix) | `by_alias` / `dump_mode` reach no live path here; the plugin's copy diverges on the announced fix | true, disclosed | small (a swap) | RF-1, then a `pipelex` release |
-| [RF-3](#rf-3--the-test-gaps-this-branch-left) | Test gaps this branch left — one of them lets the headline fix be deleted silently | true | small | nothing |
-| [RF-4](#rf-4--no-request-timeout-ever-reaches-the-linkup-sdk) | No request timeout ever reaches the Linkup SDK, so `LinkupTimeoutError` is unreachable | true, pre-existing | small + a config call | nothing |
-| [RF-5](#rf-5--the-llm-paths-schema-check-is-implicit-and-a-plausible-optimisation-would-delete-it) | The LLM path's schema check is implicit, and a plausible optimisation deletes it | true | small | nothing |
-| [RF-6](#rf-6--dry-search-leaves-report-no-usage) | Dry search leaves report no usage | true, pre-existing | small design | nothing |
-| [RF-7](#rf-7--the-relays-envelope-contract-is-unpinned-on-the-producing-side) | The relay's envelope contract is unpinned on the producing side | true | small, cross-repo | a `pipelex-relay` PR |
-| [RF-8](#rf-8--an-envelope-whose-data-is-neither-null-nor-an-object-is-called-empty-rather-than-malformed) | An envelope whose `data` is neither null nor an object is called *empty* rather than *malformed* | true, deliberate | small, but two workers | nothing — decide whether the split is worth it |
-
-**What the review already fixed, so you do not re-find it:** the direct Linkup backend silently validating a `{data, sources}` envelope into an all-defaults object; a billed search whose shape was rejected vanishing from the cost report; `pipelex validate` no longer catching an output class that cannot emit a JSON schema; the gateway's positional `.get("data")` unwrap; `JSONDecodeError` escaping unclassified; the misleading "try a different model" advice on an empty result; and `linkup/exceptions.py` not following the `<provider>_exceptions.py` convention.
-
----
-
-## RF-1 — The live-`ValidationError` contract is inconsistent, and the plugin's own two arms disagree about it
-
-**Not** "the plugin cannot adopt the shared helper" — it can, and on the object path it is a clean swap. The branch's review guide already frames the bare re-raise as deliberate, and that framing is right. What the review found is narrower and more interesting: **the intended adopter contradicts itself about whether a live `ValidationError` may escape workflow code**, and by its own comment the arm that lets it escape is the wrong one.
-
-### Verified
-
-The shared helper re-raises the bare `ValidationError` on the live path — `pipelex/cogt/content_generation/object_revalidation.py`:
-
-```python
-try:
- return object_class.model_validate(raw_data)
-except ValidationError as exc:
- if is_mock_built:
- raise DryRunObjectFidelityError.for_object_class(object_class.__name__) from exc
- raise
-```
-
-The plugin's **object** arm does exactly the same — so it can adopt the helper as-is:
-
-```bash
-sed -n '52,78p' ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py
-# ... Scoped to the dry path only — a LIVE provider's invalid output keeps its existing ``ValidationError``.
-# raw_data = raw_obj.model_dump(mode="json", serialize_as_any=True)
-# if not is_mock_built:
-# return object_class.model_validate(raw_data)
-```
-
-Its **search** arm does the opposite, and says why:
-
-```bash
-sed -n '548,561p' ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py
-# # ... a malformed structured response raises a bare ValidationError here in
-# # workflow code. Left raw it is neither WorkflowExecutionError nor PipelexError, so Temporal
-# # treats it as a workflow-task failure and retries forever, hanging the submitter — the exact
-# # failure mode this seam exists to prevent.
-# try:
-# return output_structure_class.model_validate(result_dict)
-# except ValidationError as exc:
-# ...
-# raise ContentGenerationError(msg) from exc
-```
-
-Both arms run in workflow code. If that comment is correct — and it has an integration test behind it — then the object arm has the same hang hazard and does nothing about it. If the object arm is fine, the search arm's conversion is unnecessary. They cannot both be right.
-
-### Why this lands here and not only in that repo
-
-The plugin sweep is already on the books as "swap the copies for the shared helper". Doing that swap **as written** propagates the inconsistency into the shared home: the helper would become the single documented source of a live-error contract that the plugin's search arm has to override anyway, without the helper saying so. Whoever does the sweep should resolve the disagreement first, not preserve it.
-
-### There is a second half, in this repo
-
-In-process, that same bare `ValidationError` is now the **primary live failure mode** of structured search — "the provider returned a payload that doesn't match your class" — and it escapes the Pipelex error taxonomy entirely: no `error_type`, no `error_domain`, no `type_uri`. Until this branch, structured search was broken on both backends, so that outcome was never reachable; it is now.
-
-### Options
-
-1. **Give the helper an explicit live-failure contract** — an `on_validation_error` callable, or a typed error class parameter. The plugin passes its `ContentGenerationError` on both arms; this repo passes a typed content-generation error. The disagreement resolves in one place and the in-repo taxonomy hole closes with it.
-2. **Keep the bare `raise`, decide the plugin question separately.** Legitimate — but then the helper's docstring must say that a submitter running in workflow code MUST NOT let the bare error escape, because right now nothing in the shared home warns the next adopter.
-
-Either way, the plugin's two arms need to agree before the sweep lands.
-
----
-
-## RF-2 — `by_alias` and `dump_mode` reach no live path here, and the plugin's copy diverges on the announced fix
-
-Disclosed in the CHANGELOG, so this is not a surprise — but the *shape* of the divergence is worse than "not adopted yet" and is worth stating plainly.
-
-### Verified
-
-The branch's own audit says nothing in this repo reaches the conversion arm ([`boundary-revalidation-round-trip-audit.md`](boundary-revalidation-round-trip-audit.md), "Who reaches the conversion"): every in-repo path hits the `isinstance` short-circuit. The boundary arm's only caller is out of repo:
-
-```bash
-grep -rn "await search_gen_structured(" ../pipelex-temporal/pipelex_temporal/
-# .../tprl_content_generation/act_search_generate.py:23: return await search_gen_structured(search_object_assignment=search_object_assignment)
-```
-
-(Grep for `search_gen_structured\b` instead and the word boundary matches inside `act_search_gen_structured`, burying the one real call site under the activity's own name.)
-
-And the plugin's copy of the conversion still dumps without `by_alias`:
-
-```bash
-grep -n "model_dump(mode=" ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py
-# 71: raw_data = raw_obj.model_dump(mode="json", serialize_as_any=True)
-```
-
-`dump_mode` likewise has no production caller anywhere — only tests pass a non-default value.
-
-### Why it matters more than "pending"
-
-Before the extraction the two copies differed only in `dump_mode`. They now differ **on the exact defect the CHANGELOG announces as fixed**: a field named `json` / `copy` / `schema` / `construct` still breaks the round trip on the distributed arm, which is the *only* arm that reaches that code. The divergence is invisible to both repos' CI.
-
-The one live path in this package that does get the fix is `dry_search_gen_structured` — reached only through the boundary arm, which again only the plugin calls.
-
-**Do this together with RF-1**, in the plugin sweep, and re-read the CHANGELOG entry's framing when it lands.
-
----
-
-## RF-3 — The test gaps this branch left
-
-Priority order. The first one is the one that matters.
-
-### (a) `by_alias=True` on the dry boundary search mock is untested
-
-`pipelex/cogt/content_generation/dry_mock.py`:
-
-```python
-return build_mock_object(boundary_class).model_dump(mode="json", by_alias=True)
-```
-
-No test builds a `SearchObjectAssignment` from a class whose properties the rebuild renames, so **deleting `by_alias=True` here leaves the whole suite green** while re-introducing the `Field required` failure the branch set out to fix. The sibling fix in `revalidate_leaf_object` *is* pinned, which makes this an asymmetry rather than an accepted gap:
-
-```bash
-grep -rln "construct: str\|json: str" tests/
-# tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py ← only the object arm
-```
-
-Fix: a boundary-dry case in `test_leaf_dry_object_mocks.py` using a `StructuredContent` with shadowing field names, asserting the returned dict is keyed by the schema property names and validates back into the original class.
-
-### (b) The live in-process search arm's return value is never asserted
-
-`tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.py`:
-
-```python
-await search_gen_structured_object(_live_search_assignment(), output_class=HintedName)
-
-assert mock_worker.search_structured.await_args.kwargs["schema"] is HintedName
-```
-
-The result is discarded. Its dry twin asserts the value, so the once-only-validation contract and the `is_mock_built=False` negative path (a malformed provider dict must raise `ValidationError`, never `DryRunObjectFidelityError`) are unpinned on the live arm.
-
-### (c) The SDK-exception branch of `_search_structured` is untested on both backends
-
-```bash
-grep -c "_search_sourced_answer" tests/unit/pipelex/providers/linkup/test_linkup_search_worker_semantic.py # 1
-grep -c "_search_structured" tests/unit/pipelex/providers/linkup/test_linkup_search_worker_semantic.py # 0
-```
-
-The semantic tests that parametrize every Linkup SDK exception only ever drive the sourced-answer arm. The structured arm's `try` now wraps a differently-shaped call (serialized schema, `include_sources=False`), so its error classification and `from exc` chaining ride on nothing. Parametrizing the existing tests over both arms is the cheap fix.
-
-### (d) The gateway test never asserts the caller's schema reaches the relay
-
-The Linkup contract test pins that the real schema — including a `json_schema_extra` hint a rebuild would drop — crosses the wire. Its gateway counterpart mocks `_call_relay` wholesale and never inspects what was sent, so item 2's contract is verified on one backend only, and the gateway is the one the hosted runner uses.
-
----
-
-## RF-4 — No request timeout ever reaches the Linkup SDK
-
-### Verified
-
-```bash
-grep -n "timeout" pipelex/providers/linkup/linkup_search_worker.py pipelex/providers/linkup/linkup_extract_worker.py
-# (none)
-```
-
-The SDK's `async_search` takes `timeout: float | None = None` and passes it straight to `httpx`, whose docs say `timeout=None` disables timeouts entirely — connect, read, write and pool. So a slow or hung provider blocks the task indefinitely.
-
-The design clearly assumes a timeout exists: the worker catches `LinkupTimeoutError` and classifies it. **The condition that raises it cannot be reached.**
-
-Pre-existing, and it affects the sourced-answer and extract paths too — but the structured call site was rewritten on this branch, which is why it surfaced now.
-
-Fix needs a decision, which is why it is deferred rather than patched: where does the value come from — a search setting, a provider config key, or a shared inference default? Once that is settled the code is one keyword argument per call site.
-
----
-
-## RF-5 — The LLM path's schema check is implicit, and a plausible optimisation would delete it
-
-This is a **trap**, recorded so the next person to "clean up" a redundant call does not spring it.
-
-### Verified
-
-`ObjectAssignment.make_for_class` computes a schema that the in-process path never reads:
-
-```bash
-grep -n "model_json_schema" pipelex/cogt/content_generation/assignment_models.py
-# 95: object_class_schema=object_class.model_json_schema(),
-# 184: output_class_schema=output_class.model_json_schema(),
-```
-
-`resolve_object_class` returns the live class immediately when one is in hand — which it always is from `ContentGenerator` — so `object_class_schema` is dead on both the live and the dry in-process LLM paths. It looks exactly like the waste this branch removed on the search arm by not building a `SearchObjectAssignment` at all. It measures around 290 µs per call for a modest nested model: noise beside a live LLM round trip, but roughly a fifth of the leaf's cost on the dry-run path `pipelex validate` walks per pipe.
-
-### Why you cannot just delete it
-
-That call is what still *incidentally* proves the output class can emit a JSON schema on the LLM path. The search arm now has an explicit check:
-
-```bash
-grep -rn "_validate_schema_is_generable" pipelex/
-# dry_mock.py:465: _validate_schema_is_generable(output_class=output_class)
-# dry_mock.py:470:def _validate_schema_is_generable(*, output_class: type[BaseModel]) -> None:
-```
-
-The LLM arm has none. Deleting the assignment's schema call without adding the explicit check there would re-open, on the LLM path, precisely the hole the review just closed on the search path: polyfactory mocks an undescribable class happily, `pipelex validate` passes, and the live run dies inside the worker on a bare `PydanticInvalidForJsonSchema` — a `RuntimeError`, so no model attribution, no remedy, no error identity.
-
-**Do them together or not at all:** add `_validate_schema_is_generable` to the LLM dry arm first, then the optimisation is safe.
-
----
-
-## RF-6 — Dry search leaves report no usage
-
-Carried over from the branch's own deferral list, which recorded it with no durable home. This section is that home.
-
-### Verified
-
-None of `dry_search_gen_sourced_answer`, `dry_search_gen_structured`, `dry_search_gen_structured_object` emits a usage event, where the dry LLM leaves report a synthetic job via `report_dry_llm_job` / `report_mock_usage_llm_job`:
-
-```bash
-grep -n "report_dry_llm_job\|report_mock_usage_llm_job\|def dry_search" pipelex/cogt/content_generation/dry_mock.py
-# 146:def report_dry_llm_job(...)
-# 158:def report_mock_usage_llm_job(...)
-# 411:def dry_search_gen_sourced_answer(...)
-# 419:def dry_search_gen_structured(...)
-# 441:def dry_search_gen_structured_object(...)
-```
-
-So a dry run's cost/usage report shows zero search calls for a method that will make one per run.
-
-Pre-existing — dry search never reported — and not introduced by this branch.
-
-Deferred because it is a small **design**, not a mechanical patch: it means choosing the synthetic-search-job conventions (model name / id placeholders, whether the per-request 1M-token cost convention applies, and the dry vs `is_mock_usage` variants), and improvising those would bake in a shape the cost report has to live with.
-
----
-
-## RF-7 — The relay's envelope contract is unpinned on the producing side
-
-Cross-repo; needs a `pipelex-relay` PR.
-
-### Verified
-
-The relay produces the envelope:
-
-```bash
-grep -n "include_sources" ../pipelex-relay/pipelex_relay/services/web_searcher.py
-# 97: include_sources=True,
-```
-
-Its own unit test asserts the **opposite** shape — a bare payload:
-
-```bash
-grep -n "search_structured" ../pipelex-relay/tests/unit/pipelex_relay/api/test_web_search.py
-# 32: mock_instance.search_structured = mocker.AsyncMock(return_value={"key": "value", "items": [1, 2, 3]})
-```
-
-So the contract the gateway worker consumes is encoded nowhere on the producing side, and the one test that touches it encodes something else.
-
-### Why it is now lower-stakes than it was
-
-The review changed the gateway worker to recognise the envelope **structurally** rather than demand it, so a relay that stops asking for sources no longer breaks every gateway structured search — the two sides are decoupled and this is no longer a coordinated deploy. What remains is that the relay could change its response shape with nothing to notice.
-
-Worth doing anyway, and cheap: a relay-side regression test pinning `{data, sources}`, plus a line in the relay's README or CHANGELOG naming the shape. The hazard is amplified by this branch's own reasoning — it changed the *direct* backend to `include_sources=False` because "a structured result has nowhere to put sources", and someone applying that same reasoning to the relay is the likeliest way this moves.
-
----
-
-## RF-8 — An envelope whose `data` is neither null nor an object is called *empty* rather than *malformed*
-
-Raised by a review bot on the v0.42.0 release PR (#1078) against `linkup_search_worker.py`. Verified true as a mechanic, judged **not worth fixing there** — recorded here rather than patched under a release.
-
-### Verified
-
-Both workers make the malformed-vs-empty split the extractor's docstring promises, and both make it the same way:
-
-```bash
-sed -n '178,182p' pipelex/providers/linkup/linkup_search_worker.py
-# payload = extract_structured_search_payload(response=response, schema=schema)
-# if payload is not None: return payload
-# if isinstance(response, dict): ← empty; else → malformed
-```
-
-`extract_structured_search_payload` returns `None` in exactly two places (`structured_search_payload.py`): the response is not a dict at all, or it *is* the envelope and `payload["data"]` is not a dict. The `isinstance` line excludes the first, so the empty branch is reachable iff an envelope arrived carrying `data` of `None`, `list`, `str`, `int`, `float` or `bool`. Only `data: null` is genuinely "the search found nothing"; a list or a scalar is a provider contract breach — the schema always crosses as `model_json_schema()`, which is always `"type": "object"` — and gets `CHANGE_INPUT` / "try a broader query" advice it does not deserve.
-
-The extractor's own docstring closes that sub-split on purpose: *"an envelope whose `data` is null **or not an object** (the search simply found nothing…)"*. So this is a documented simplification, not an oversight.
-
-### Why it was not fixed on the release PR
-
-- Blast radius is the advice string and the message wording, on a path that already raises a classified error in the right family. Nothing is silently wrong.
-- The only shape observed in practice is `data: null`, which is classified correctly today. `data: {}` never reaches the branch at all — it is a dict, so it is returned as the payload and the leaf decides.
-- `gateway_search_worker.py` is structurally identical here, so fixing linkup alone would *create* a divergence where there is currently none. The change is two workers plus the shared helper plus both contract suites.
-
-### If you do it
-
-Put the predicate in the module that owns the envelope rule, not in the call sites: a `structured_search_payload` helper returning "envelope present **and** `data` is null", and swap the `isinstance(response, dict)` line in both workers for it. Inlining `response["data"] is None` at each call site instead hard-codes the helper's internals in two places and breaks the day the helper grows a third `None` case. Then tighten the extractor docstring's "null or not an object" → "null", or it becomes the drifted artifact. Make the fall-through message name the offending `data` type rather than the outer `dict`.
-
-**Do not** reach for a three-way outcome enum + result type + `match/case` in both workers. That is the shape the docstring literally describes, but it is a lot of new machinery to change an advice string on a shape never observed.
-
-### Two coverage gaps found while verifying this
-
-Both are real, independent of whether RF-8 itself is ever done:
-
-1. **The shared rule has no direct test.** `pipelex/cogt/search/structured_search_payload.py` is exercised only indirectly, through the two worker contract suites. It is the one piece of logic both backends share, and the alias defect fixed on #1078 lived in it.
-2. **The linkup suite is missing the `DataAndSources` case.** `test_gateway_structured_search_contract.py` pins `test_an_output_class_that_declares_data_and_sources_is_not_unwrapped` — "the one shape a positional `.get('data')` unwrap would silently corrupt" — and its linkup counterpart has no equivalent, despite running the same shared rule. The aliased variants added on #1078 landed on the gateway side only, for the same reason.
-
----
-
-## Provenance
-
-Findings came from a `/review` pass on `refactor/Follow-ups`: specialist reviewers (testing, maintainability, security, performance, api-contract), a red-team pass, an independent fresh-context adversarial pass, and a Codex adversarial pass. Claims that survived were re-verified by hand — the silent-envelope corruption, the schema-generability regression and the `validate_by_alias` edge were each proven or disproven by running pydantic directly rather than by reading. Several confident-sounding findings did **not** survive and are deliberately absent: `by_alias=True` was attacked with `serialization_alias`≠`validation_alias`, `AliasChoices`, `AliasPath`, `extra="allow"` and the real spec classes without producing a regression, and the "json dump mode breaks strict types" claim is already the deliberately-deferred residue recorded in the branch's own notes.
diff --git a/wip/refactoring/modularity-refactors-tracker.md b/wip/refactoring/modularity-refactors-tracker.md
deleted file mode 100644
index 32305d567..000000000
--- a/wip/refactoring/modularity-refactors-tracker.md
+++ /dev/null
@@ -1,793 +0,0 @@
-# Modularity refactors — implementation tracker
-
-> **Moved here from the repo-root `TODOS.md` on 2026-07-29**, so that slot is free for whatever is actively being built — the same treatment the hub-split tracker got in [`wip/hub/`](../hub/hub-split-tracker.md). The track is **parked, not archived**: everything below is unedited except relative links, which now resolve from `wip/refactoring/`.
->
-> ⚠ **The branch/PR line below is a historical record — the work shipped under different numbers.** Verified 2026-08-01: M3 + M1 + M2 + F1 all reached `dev` inside the squash `8c0b99b3a` *"fix(hub): move the interpreter-touching built-in plugins out of the runtime layer, and make the layering guard transitive (#1064)"* — it is the commit that created `pipelex/pipe_machinery/`, `pipelex/mthds_parsing/`, `pipelex/providers/` and `pipelex/interpreter_plugins/`. PR **#1067 therefore has no commit of its own on `dev`**, and the branches (`refactor/Modularity-3`, `refactor/Modularity-4`, `refactor/Hub-2`) and the `_hub` worktree are all deleted. #1070 and #1071 landed as their own commits. Read the body as of 2026-07-28; re-verify any ref before acting on it.
->
-> **What is actually left: [Phase 5](#phase-5--close-out) — the release-gated cross-repo sweep**, shared with the hub split, the Phase 3 type moves and the `interpreter_plugins` relocation. It must land as one breaking wave. v0.41.0 and v0.42.0 have since shipped, so the release gate that deferred it is open.
-
-**Design doc:** [`modularity-refactors.md`](modularity-refactors.md) — the *why*, the rulings, the measurement snippets. This file is the *how*: ordered work, checkboxes, hard checkpoints.
-
-**Worktree:** `_hub/` · **Branch:** `refactor/Modularity-3` (M3 + M1 + M2 + F1, pushed at `6e74c6f26`; `refactor/Modularity-4` merged in via PR #1065 and deleted) · **Base:** `refactor/Hub-2` (PR #1064, still open — see [Gating](#gating)) · **PR:** [#1067](https://github.com/Pipelex/pipelex/pull/1067), open **against `refactor/Hub-2`** so the diff carries the modularity work only; GitHub retargets it to `dev` when #1064 lands · **Status:** **F1 complete and reviewed three times — CHECKPOINT F1 cleared.** All four tracks reviewed and their fixes committed. Only Phase 5 remains.
-
-**Reviewed 2026-07-27** (`/plan-eng-review`, 8 issues, all ruled). The review reversed **D-M1-2**, ruled **D-M1-4**/**D-M1-5**/**D-M1-6**, re-scoped **F1**, and corrected the cross-repo blast radius in both directions. The changes are folded in below; see [Review findings](#review-findings) for what moved and why.
-
-Three tracks, ordered by dependency: **M3 → M1** (M3 is a prerequisite slice of M1), **M2** independent, then one small follow-up. Each track is its own PR.
-
----
-
-## How to use this file
-
-- Work top to bottom. Tick a box only when the thing is *done and verified*, not when it is written.
-- **Checkpoints are hard stops.** At a `🛑 CHECKPOINT` you finish the phase, run the gates, update this file, fan out the reviews, and stop for the user. Do not start the next phase in the same session.
-- The [Cold-start brief](#cold-start-brief) at the bottom is what a fresh session reads first. Keep it true.
-- Measured numbers are recorded as of the date noted. Re-measure rather than trusting them; the *shape* (which modules, zero vs non-zero) is the criterion, not the absolute count.
-
----
-
-## Gating
-
-- [ ] **PR #1064 (`refactor/Hub-2`) is merged to `dev`.** All three tracks build on the F1 remedy (`pipelex/interpreter_plugins/`, the transitive guard rule). This branch is already based on it, so work can *start* before the merge — but no track may be opened as a PR against `dev` until #1064 lands, or the diff will carry #1064's changes.
-- [ ] **PR topology — ruled 2026-07-27: three PRs, with M1 STACKED on M3.** The plan previously said both "M3 → M1" and "each track is based on #1064 and opened against `dev`", which cannot both be true. The topology is:
-
- ```
- #1064 (refactor/Hub-2)
- └─ M3 ─────────── PR → dev
- └─ M1 ─────── PR → M3 (retarget to dev once M3 merges)
- └─ M2 ─────────── PR → dev (independent)
- └─ F1 ─────── PR → M2
- ```
-
- ⚠ **Superseded in practice by [D-M2-4](#decisions).** M3, M1 and M2 all landed as commits on `refactor/Modularity-3`, in that order. The prescribed *landing order* is what mattered and it is satisfied; splitting the branch into three PRs after the fact would re-create exactly the three-file conflict the topology existed to avoid. Open it as **one PR against `dev`** once #1064 merges (or split M3 off first if a smaller review is wanted — it is the only one of the three that is genuinely self-contained). F1 stays a separate PR on top, since it is the only behavior change in the track.
-
-- [x] **Landing order is prescribed, not optional.** M1 and M2 both modify `hub_layering_guard.py`, `test_runtime_layer_import_closure.py` and `docs/contribute/hub-layering.md`. They are *architecturally* independent but **not operationally** independent — parallel branches conflict on those three files. Land M3 → M1 first, then rebase M2. ⚠ **A drift ack does not survive the rebase**: the digest reads the git index, so re-review and re-ack `hub-layering-convention` after rebasing M2.
- → **Resolved by construction (D-M2-4): M2 was built directly on top of M1 on this branch, not on a parallel branch.** The prescribed landing order is satisfied, the three-file conflict never arises, and the rebase-and-re-ack step disappears — the `hub-layering-convention` ack recorded at CHECKPOINT M2 is already against the final tree. The PR topology below collapses accordingly.
-- [ ] **M2 is NOT release-gated.** Measured 2026-07-27 across every sibling repo: **zero** external consumers import `pipelex.plugins.<vendor>`. The "one breaking wave" argument covers M3 and M1 only. M2 may land whenever it is ready — it does not have to wait for the sweep, and its row comes out of the [Phase 5](#phase-5--close-out) table.
-
----
-
-## Ground rules for every move
-
-These are cross-cutting and each one has already been the cause of a confusing failure somewhere in this repo. Read them before the first `git mv`.
-
-- [ ] **Re-path `subject_grants.toml` in the same commit as the move — and *before* running `make agent-check`.** Grants are keyed `<path>::<qualname>` and staleness is symmetric: a grant whose def moved **hard-fails** `check-keyword-only`. Worse, `make agent-check` runs `fix-keyword-only` *first*, which will silently rewrite the now-"ungranted" subjects to keyword-only — corrupting the diff. Order is always: `git mv` → rewrite grant paths → `make cko` (read-only, must be green) → then `make agent-check`.
- Measured grant hits by moving path (2026-07-27): `core/bundles` 6 · `core/interpreter` 15 · `core/pipes/pipe_abstract` 5 · `core/pipes/rendering` 15 · `core/pipes/pipe_factory` 0 · `core/registry_models` 0 · `plugins/` 160.
-- [ ] **Regenerate error pages when an exceptions module moves.** `docs/errors/<slug>.md` carries a `Defined in | <module path>` row, so every moved error class churns its page. Verified: the page **filename and `type_uri` derive from the class name, not the module path** — so a pure move is URL-stable, and only a class *rename* changes a published `type_uri`. Run `make gep` after each move and inspect the diff.
-- [ ] **Mirror the test tree in the same commit** — and **derive the list from each test module's actual subject, never from an inventory written in advance.** M1 proved this twice: the tracker's M1a and M1b test inventories were both materially incomplete. Grep each candidate for the source module it imports and route it by that. For M2: `tests/unit/pipelex/plugins/`, `tests/integration/pipelex/plugins/`.
-- [ ] **Check every moved test for a path derived from its own depth.** `Path(__file__).parents[N]` silently resolves to a different directory after a move — no import rewrite, type checker or import-graph tool sees a parent count, and it fails only when the test runs. M1b hit exactly this. Re-anchor on a named directory (`next(p for p in Path(__file__).parents if p.name == "tests")`) rather than fixing the index.
-- [ ] **`make cleanderived` after every batch of moves**, before running linters or pytest — stale `__pycache__` and collection state make the linters chase ghosts.
-- [ ] **Rewrite imports by exact module path, never by prefix substring.** Two live traps:
- - `pipelex.plugins.secrets` (vendor dir) vs `pipelex.plugins.secrets_provider_registry` (mechanism module) — same for `storage`. A prefix `sed` corrupts the mechanism modules.
- - `pipelex.core.interpreter` (the package) vs `pipelex.interpreter_hub` / `interpreter_plugins` (unrelated). Anchor on `pipelex.core.interpreter.` and `pipelex.core.interpreter import`.
-- [ ] **Rewrite string-literal module references too — they are not imports and nothing sees them.** `mocker.patch("pipelex.plugins.fal.fal_img_gen_worker.ImgGenArgsFactory.make_args_for_model")` is a module path that no import rewrite, no type checker, and no import-graph tool will touch. They fail loudly at test time, but only *after* the move, and a naive import-only rewrite turns the suite red in bulk. Measured 2026-07-27: **M2 = 189** literals, **M1 = 15** (the closure test's own config strings are among them). The `secrets` / `storage` ambiguity above is worse in string form — the sample includes `"pipelex.plugins.storage.storage_plugin..."`.
-- [ ] **Use `git mv`** so history follows the file; do the import rewrite as a separate hunk in the same commit.
-- [ ] **Sweep with `git grep` or `/usr/bin/grep`, never a bare `grep -r`.** This shell's `grep` is a **ugrep wrapper that honours `.gitignore`** — from the workspace root it silently skips every sibling repo, and inside `_hub` it skips the stale `site/` tree. It returns a *false clean* on exactly the completeness sweep a rename refactor depends on, and it fails silently by construction. Found during M2's review round; M2's own verdict survived re-verification only because the load-bearing pass happened to use `git grep`.
-- [ ] **A brace-glob is a module reference no per-name regex will match.** `plugins/{google,openai}/*_img_gen_factory.py` names two modules and matches neither a `google` nor an `openai` substitution keyed on a single vendor. Same class of miss as a string literal, one level further out — and it survives into *unchecked plan items*, where it is worst, because those are instructions for work not yet done. Grep for the brace form explicitly before declaring a rename complete.
-- [ ] **Every measurement/guard set is a matched set.** Whenever a module changes layer or package, four places must agree: `RUNTIME_LAYER_PACKAGES` (the guard), `INTERPRETER_PACKAGES` (the closure test), the `INTERPRETER` set in `docs/contribute/hub-layering.md`'s verification snippet, and the classification snippet's `I` in the design doc. Updating one and not the others makes a check pass vacuously.
- **Two of the four are now mechanically bound** (M1c): a test asserts the closure predicate and the doc snippet name the same packages, and two more assert that every entry in `RUNTIME_LAYER_PACKAGES` / `INTERPRETER_PACKAGES` resolves on disk — so a typo can no longer guard nothing. `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` are **gone**; do not re-add them. The design doc's copy stays manual (it lives in `wip/`, which is archived at track end).
-
----
-
-## Phase 0 — baseline
-
-Cheap, and it is what every exit criterion is measured against.
-
-- [x] Confirm the tree is clean and gates are green *before* touching anything: `make agent-check`, `make agent-test`, `make drift-check`, `make chl`. — all green on `95a1e9bf7`.
-- [x] Re-run the [core classification snippet](modularity-refactors.md#measurement) and paste the result into [Measurements](#measurements) below with today's date. — reproduced the [Measurements](#measurements) table exactly (97 / 51×3 / 33 / 30×4, same nine modules).
-- [x] Note any drift from the design doc's numbers. **Known already:** re-measured on `bc30149c7` the counts are uniformly higher than the doc's (`registry_models` 97 vs 92, the 48s are 51, the 30 is 33, the 28s are 30). The *set of nine* modules and their ordering are unchanged, so the plan holds; only the absolute figures moved. — confirmed on `95a1e9bf7`; no further drift.
-- Also baselined here because M3's exit criteria need them: **43** inverted `core → pipe_*` import statements (24 `registry_models` · 12 `pipelex_bundle_blueprint` · 4 `bundle_elaborator` · 2 `output_renderer` · 1 `pipe_abstract`).
-- ⚠ **Gotcha, cost ~10 min:** `make cleanderived` deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`, which is gitignored but *not* regenerated by `agent-check` — only by the test targets. So the ground rules' "`cleanderived` before the linters" order makes pyright fail with 12 unrelated `reportMissingImports` in `model_selection.py`. Regenerate with `.venv/bin/pipelex-dev preprocess-test-models --generate-fixtures --profile ci` before re-running `agent-check`.
-
----
-
-## M3 — split the boot manifest by layer
-
-Removes core's fattest interpreter edge and seeds `pipe_machinery/`. Small, self-contained, no behavior change.
-
-### Work
-
-- [x] Create `pipelex/pipe_machinery/__init__.py` (empty, per repo convention).
-- [x] Create `pipelex/pipe_machinery/registry_models.py` holding `PipeRegistryModels(RegistryModels)` with the six pipe lists: `PIPE_OPERATORS`, `PIPE_OPERATORS_FACTORY`, `PIPE_CONTROLLERS`, `PIPE_CONTROLLERS_FACTORY`, `PIPE_SIGNATURES`, `PIPE_SIGNATURES_FACTORY`, plus the ~24 `pipe_operators` / `pipe_controllers` / `pipe_signature` imports that come with them. — 24 imports, as measured.
-- [x] Strip those six lists and their imports out of `pipelex/core/registry_models.py`. `CoreRegistryModels` keeps `STUFF`, `EXPERIMENTAL`, `FIELD_EXTRACTION` and the `core.stuffs` imports only. It should end up importing nothing from `pipe_operators` / `pipe_controllers` / `pipe_signature`, and no longer needing `PipeAbstractType` / `PipeFactoryProtocol` / `Any`. — all three dropped as predicted.
-- [x] `pipelex/pipelex.py`: import both and register both — two adjacent `register_classes` lines. (`RegistryModels.get_all_models()` reflects over `dir(cls)` and dedups through a `set`, so the split is mechanical and double-registration is impossible.)
-- [x] Add `"pipe_machinery"` to `INTERPRETER_PACKAGES` **and** drop `"pipelex.core.registry_models"` from `INTERPRETER_CORE` in `tests/unit/pipelex/test_runtime_layer_import_closure.py`. Do this in M3, not M1 — the moment an interpreter module lives under a new top-level package the predicate must count it, or the test under-counts silently. (The design doc puts this in M1 move 4; it belongs here for `pipe_machinery`, and in M1 for `mthds_parsing`.)
- Also **proved the new token is live**, rather than trusting `DIRTY_ENTRY_POINT` (which only proves *some* token matches): ran `_CLOSURE_SCRIPT` against `pipelex.pipe_machinery.registry_models` and asserted both that it exits 1 and that the offenders list contains a `pipe_machinery` module of its own. This is M1c's "one leaf probe per new package" step, done early for M3's token.
-- [x] Update the guard's `RUNTIME_LAYER_PACKAGES` docstring where it enumerates `registry_models` as part of core's interpreter half (`hub_layering_guard.py` ~line 101). The declaration tuple itself does not change in M3.
-- [x] `docs/contribute/hub-layering.md`: update the two places naming `core.registry_models` as Pipe machinery inside `core/` (~lines 111, 242).
- ⚠ **There were four, not two.** The drift review found two more, and they are the load-bearing ones: the *"`runtime_hub` must not name anything from …"* list under "Why the boundary exists" (line 80) and the **`INTERPRETER` set inside the page's own verification snippet** (line 91). Both enumerate the interpreter top-level packages, so both go stale on any new one — and a reader running the stale snippet measures zero interpreter modules and believes it. Expect the same pair in M1a (`mthds_parsing`). The tracker's grep for `registry_models` finds neither; grep for `interpreter_plugins` to find them.
-- [x] Write the **registration-surface doc** — new page under `docs/contribute/`, registered in **two** places in `mkdocs.yml`: the `llmstxt-md` plugin's section list (~line 330) and the real `nav:` (~line 569). Missing the first one silently drops the page from `llms.txt`. Content: adding a pipe kind touches the kind's package, the type tag (`PipeType`/`PipeCategory`), the blueprint union in `core/bundles/pipelex_bundle_blueprint.py`, `PipeRegistryModels`, and the spec map (`builder/pipe/pipe_spec_map.py` + `pipe_spec_union.py`). Include the note that the spec-layer parallel in `builder/pipe/` is deliberate (see `pipelex/builder/CLAUDE.md`, spec vs blueprint), not duplication to collapse. — `docs/contribute/registration-surface.md`, both mkdocs registrations done.
-- [x] **Not doing:** the `PipeBlueprintUnion` extraction (cut in design doc v2 — it would move twice, since M1 hoists `core/bundles/` wholesale). **Not doing:** moving `PipeType` / `PipeCategory` out of `core/pipes/pipe_blueprint.py` — measured 0, runtime-layer, stays in `core/` permanently (D-M1-2). — respected; note `PipeType`/`PipeCategory` move with `pipe_blueprint.py` in M1b under the *reversed* D-M1-2, so "stays in `core/` permanently" here is superseded by the reversal (see [Decisions](#decisions)).
-- [x] **CRITICAL — regression test for the split registration.** Nothing in the suite asserts that pipe classes reach the class registry: `tests/unit/pipelex/test_hub_lifecycle.py:39-51` asserts hub singletons and scoping, and the class-registry tests use a synthetic `ScopedModel`. If either `register_classes` line is dropped or mis-wired, **boot still succeeds** and kajson deserialization of a pipe fails later, in production.
- **Assert the full set, not a sample.** One pipe + one stuff only catches a missing *whole* registration call — it cannot catch dropping one of the six lists, or one model out of a list, while hand-splitting `core/registry_models.py:53-93`. So: freeze the pre-split `CoreRegistryModels.get_all_models()` set, assert `CoreRegistryModels ∪ PipeRegistryModels` equals it exactly, **and** assert the two manifests are disjoint. That pins every model across the split and is the only new failure mode M3 introduces.
- → **`tests/unit/pipelex/test_registry_models_split.py`** (new module — the repo's one-TestClass-per-module rule rules out appending to `test_hub_lifecycle.py`, which T1 named). Three tests, and the third is the one T1's verify step is about: the frozen-set and disjointness assertions are computed *from the manifests* and would stay green if `Pipelex.make` never registered them, so a third test reads the **booted class registry** through `get_class_registry()`. **Both mutation checks run, both red as intended:** deleting the `PipeRegistryModels` `register_classes` line → *"booted class registry is missing 24 registered model(s)"*; deleting one model from `PIPE_OPERATORS` → set-equality failure *and* *"missing 1 registered model(s): ['PipeSearch']"*. The frozen set is 42 class names; names are unique, and the test asserts that too so the set comparison cannot lie.
-- [x] **`make drift-ack CONTRACT=hub-layering-convention`.** M3 edits `hub_layering_guard.py` (the docstring above the tuple), which is a trigger file in `drift.toml:65-69` — so the contract opens and M3's checkpoint `make drift-check` fails without an ack. Review `docs/contribute/hub-layering.md` for real first: M3 moves the pipe manifest out of `core/`, which the doc describes in two places. Stage the trigger files before acking (the digest reads the git index).
-- [x] Changelog entry under `[Unreleased] → ### Changed`, marked **breaking** (`CoreRegistryModels` no longer carries the pipe lists; `pipelex.pipe_machinery.registry_models.PipeRegistryModels` is new).
-- [x] **Not in the plan, done anyway (matched-pair ground rule).** The design doc's classification snippet gained `"pipe_machinery"` in its `I` set — it is the *third* copy of the interpreter-package list, alongside the closure test's `INTERPRETER_PACKAGES` and the hub-layering page's `INTERPRETER`. The plan deferred this to M1 ("after M1, extend `I` with …"); leaving it would have made the design doc's own measurement under-count for the whole M3→M1 window. Snippet preamble now names all three copies explicitly so the next package cannot update one and miss two.
-- [x] **Not in the plan, done anyway.** `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py:52` asserted `not is_runtime_layer("pipelex.core.registry_models")` under the comment *"Everything that names a `Pipe` … stays in the interpreter layer"*. Post-M3 that module names no `Pipe`, so the assertion was still passing under a false rationale — it now belongs with `pipelex.core.qualified_ref` (undeclared because `pipelex.core` is not a declared package). Regrouped, and added `assert not is_runtime_layer("pipelex.pipe_machinery.registry_models")` for the new home. ⚠ This is the same test M1c rewrites wholesale (T5) — expect a conflict there and resolve in M1c's favour.
-
-### Exit criteria
-
-| | baseline | target | **actual** |
-| --- | --- | --- | --- |
-| interpreter modules loaded by `pipelex.core.registry_models` | 97 | **0** | ✅ **0** (and `hub=0`) |
-| inverted `core → pipe_*` import statements | 43 | 19 | ✅ **19** |
-| pipe-kind manifests filed inside `core/` | 2 | 1 | ✅ **1** (`PipeBlueprintUnion` only; it moves in M1a) |
-| tests pinning pipe classes into the class registry | 0 | **1** | ✅ **1** module / 3 tests, all three mutation checks red |
-
-> **On the "97 interpreter modules" framing.** `registry_models.py` is a boot-time composition manifest with exactly one consumer (`pipelex.py:500`) and it appears in no runtime entry-point closure — so the 97 is not a live problem, and M2's exit criteria explicitly bless the same shape (`builtins.py`, "by design"). M3's real justification is the *directory*: a pipe-kind manifest filed in `core/` makes `core` look like it depends on pipes. Do not oversell the metric in the PR description.
-
-### 🛑 CHECKPOINT M3 — HARD STOP
-
-1. **Gates** (in this order): `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make tb`.
-2. **Verify:** re-run the core classification snippet; `pipelex.core.registry_models` must report `0 0`. Confirm the closure test still passes *and* that its `DIRTY_ENTRY_POINT` control still fails (it is what proves the predicate is live).
-3. **Update this file:** tick the boxes, record measured actuals in [Measurements](#measurements), refresh the [Cold-start brief](#cold-start-brief), log any decision taken or question raised.
-4. **Commit** the phase, then **fan out the reviews** per [Review fan-out protocol](#review-fan-out-protocol) with the commit SHA. M3 reviews: `correctness-and-boot` + `over-engineering`.
-5. **Stop.** Report the review verdicts to the user and wait.
-
-#### Review round — done 2026-07-27, fixes applied on Louis' call
-
-`correctness-and-boot`: **no defects.** It re-derived the move independently (six lists byte-identical, both `register_classes` calls live, no other call-site rebuilds from `CoreRegistryModels` alone, no new cycle, no cross-repo consumer of the old path) and re-ran the gates itself.
-
-`over-engineering`: **production change clean and load-bearing**; three defects, all in the new test module. All three confirmed against the code and fixed:
-
-- **The frozen 42-name `PRE_SPLIT_REGISTERED_MODEL_NAMES` literal was spent scaffolding.** Its job — "nothing dropped while hand-splitting" — expired at commit time, after which it billed a hand-edit on every legitimate addition. Confirmed non-hypothetical: the registered-model set grew in each of the last four substantive commits to that file (#953, #1014, #1028, #1039). Replaced with a **derived structural invariant**: every pipe kind must declare the factory that `pipe_factory.py:121` will look up for it by string (`f"{pipe_type.value}Factory"`). That catches the realistic error (a half-dropped kind/factory pair), stays green on a deliberate removal of both halves, and needs no maintenance ever.
-- **The disjointness assertion was redundant** with the name-collision check in the same module (`union` is a list concat, so `len(names) == len(union)` already fails on exactly that input) and guarded a runtime-harmless state. Dropped; the collision check was **kept and is load-bearing** — the registry is keyed by class name and kajson's `register_classes` skips a name it already holds.
-- **The name-prefix assertions were tautological or wrong.** `all(startswith("Pipe"))` over the pipe manifest cannot fail; `not any(startswith("Pipe"))` over core encoded a layer heuristic our own [`hub-layering.md`](../../docs/contribute/hub-layering.md) contradicts — `PipeOutput` is **runtime-layer** ("reads as Pipe machinery but is not"), so registering it in `CoreRegistryModels` would be correct and would have tripped the assertion. Both dropped.
-
-Two further items, one from each reviewer:
-
-- **Module-level docstring** violated `pipelex/kit/agent_rules/pytest_standards.md:80` ("not on top of the file and not on top of the class"). Rewritten as a comment block — same rationale preserved, correct placement. (Both agents cited the rule as `.claude/rules/pytest-standards.md`, which does not exist; the kit file is the real one.)
-- **The matched triple disagreed on `pipe_signature`** — present in the design doc's `I`, absent from the closure test's `INTERPRETER_PACKAGES` and `hub-layering.md`'s `INTERPRETER`. Pre-dates M3 (verified at `95a1e9bf7`), but this commit is the first to *write the invariant down*, so leaving it would have been dishonest. Added to both shipped copies after confirming `pipelex/pipe_signature/` is a real top-level package that imports `interpreter_hub` directly (`signature_walk.py:11`) and is loaded by **zero** of the closure test's runtime entry points — so the predicate got stricter with no red. The prose must-not-name list at `hub-layering.md` gained `pipe_signature` **and** `interpreter_plugins`, which it had also been missing. All three copies verified equal by script.
-
-⚠ One reviewer claim was **wrong and rejected**: the `over-engineering` agent asserted the three copies were "correctly in sync". They were not — verified directly. It had also, in an earlier message, attributed conclusions to two sub-agents before hearing from them, and retracted that itself.
-
-Mutation checks on the rewritten module, each red on exactly the intended test: drop a pipe kind → factory-pairing test; delete a `register_classes` line → liveness test (still caught, which is what made the derived rewrite safe); duplicate a class name across manifests → collision test.
-
-**Gap noticed, deliberately not closed here — decide it in M1.** The `hub-layering-convention` drift contract triggers on `hub_layering_guard.py` + the two hub modules and reviews `hub-layering.md`. The closure test's `INTERPRETER_PACKAGES` is **not** a trigger, and `hub-layering.md`'s `INTERPRETER` snippet is the thing that drifted from it — so no contract binds the matched triple, which is exactly why the `pipe_signature` disagreement survived unnoticed. Adding the closure test as a trigger (or a contract binding the three copies) is a drift-registry decision, and M1 touches all three files anyway. Raised now so it is not rediscovered the hard way.
-
----
-
-## M1 — make core's layer split physical
-
-Hoists the eight interpreter-layer modules (plus four measured-zero leaf modules that move for cohesion) out of `core/` into two new packages, then collapses the guard declaration to a single entry. This is the big one — split into three commits.
-
-### D-M1-4 — RULED 2026-07-27: rename, and treat it as a wire break
-
-**Rename `PipelexInterpreterError` → `MthdsParserError`.** But the premise the original recommendation rested on was wrong. The plan said *"No external consumer imports `PipelexInterpreter`, so the class rename adds nothing to the sweep."* Measured — it is consumed in five repos, and four of them consume it **as a string, not an import**:
-
-```
-pipelex-temporal/pipelex_temporal/temporal_bundle_validator.py:26 from ... import PipelexInterpreter
-mthds-starter-js/src/lib/errors.ts:176 case "PipelexInterpreterError":
-pipelex-starter-js/src/lib/errors.ts:257 case "PipelexInterpreterError":
-vscode-pipelex/.../cliValidationBackend.test.ts:99 error_type: 'PipelexInterpreterError'
-playroom/src/app/api/graph/route.ts:119 message.includes("PipelexInterpreterError")
-```
-
-Those four TypeScript consumers branch on the class name as the `error_type` **wire value**. Renaming does not break their build — they silently stop matching and fall through to a generic error branch. This is the exact failure the guard's own docstring names: *a missed import is an ImportError, a missed string is not.*
-
-- [x] Rename the class. `BundleElaboratorError` (its subclass) keeps its name.
-- [x] Add the `mkdocs.yml` `redirect_maps` entry (`errors/pipelex-interpreter-error.md` → the new page) so the retired `type_uri` still resolves. Verified: the page filename and `type_uri` derive from the **class name**, not the module path (`docs/errors/pipelex-interpreter-error.md:18` carries `| Defined in | pipelex.core.interpreter.exceptions |` as a body row) — so the pure module moves are URL-stable and only this rename churns a URL.
-- [x] Changelog: **wire-visible** break, not merely an import break. Name the `error_type` value change explicitly.
-- [x] Carry all five repos into the [Phase 5](#phase-5--close-out) sweep table. The redirect fixes the human-facing docs link and does **nothing** for the four machine consumers — they need a coordinated string change.
-
-### M1a — `pipelex/mthds_parsing/`
-
-- [x] `git mv` into a new `pipelex/mthds_parsing/`: `core/interpreter/interpreter.py` → `parser.py`, `bundle_elaborator.py`, `helpers.py`, `validation_error_categorizer.py`, `core/bundles/pipe_sorter.py`, `pipelex_bundle_blueprint.py`.
-- [x] **Create `pipelex/mthds_parsing/__init__.py` (empty).** Not optional: ruff runs `select = ["ALL"]` (`pyproject.toml:346`) and `INP001` is per-file-ignored **only** for `tests/**` (`:469`), so a source package without an `__init__.py` fails lint. M1a deletes two package initializers, so this is easy to miss.
-- [x] **Add `"mthds_parsing"` to `INTERPRETER_PACKAGES` in THIS commit, not M1c**, and run the closure gate here. Between M1a and M1c the package would otherwise exist as an interpreter home that the predicate does not count — the merged exceptions module could enter a runtime closure with the test staying green. (The tracker previously deferred this to M1c.)
-- [x] Merge `core/bundles/exceptions.py` + `core/interpreter/exceptions.py` into one `mthds_parsing/exceptions.py` (topical split only if a circular import forces it, per the error-class location convention).
-- [x] Delete `core/bundles/` and `core/interpreter/` (including their empty `__init__.py`).
-- [x] Rename the class `PipelexInterpreter` → `MthdsParser` across the tree (33 Python files, ~76 references incl. docs). Apply the D-M1-4 ruling to `PipelexInterpreterError`.
-- [x] Rewrite importers. ⚠ **Do not work from a hand-written list** — the previous one was materially incomplete (26 importer files exist; it named ~11 and missed `builder/conventions.py`, `builder/operations/runner_code_ops.py`, `cli/bundle_target_resolution.py`, `language/mthds_schema_generator.py`, agent-CLI commands, …). Rewrite mechanically, then **assert zero surviving references to the old paths** — imports *and* string literals — as the completion check.
-- [x] Move tests: `tests/unit/pipelex/core/{bundles,interpreter}/` → `tests/unit/pipelex/mthds_parsing/`.
-- [x] **Re-path subject grants AND fix the embedded qualname.** `core/bundles` 6 + `core/interpreter` 15 hits — but `subject_grants.toml:2615` is `["pipelex/core/interpreter/interpreter.py::PipelexInterpreter.make_pipelex_bundle_blueprint"]`, which embeds the **renamed class**. Re-pathing alone leaves a stale grant that hard-fails `check-keyword-only`; the qualname must become `MthdsParser.make_pipelex_bundle_blueprint`. Then `make cko`.
-- [x] `make gep` and inspect the `docs/errors/` diff (expect `Defined in` row churn; a filename/`type_uri` change only if D-M1-4 says rename).
-
-### M1b — `pipelex/pipe_machinery/`
-
-**D-M1-2 was REVERSED 2026-07-27** — see [Review findings](#review-findings). The original ruling classified modules by the measurement snippet, which counts **outbound** edges ("how many interpreter modules does X load?"). That answers "is X a leaf?", not "which layer owns X?". The layer question is **inbound: who needs this?** Under the inbound test, four more `core/pipes/` modules are interpreter-only and move with the rest:
-
-| `core/pipes/` module | runtime-layer importers | verdict |
-| --- | --- | --- |
-| `pipe_output` | 4 | runtime — **stays** |
-| `variable_multiplicity` | 5 | runtime — **stays** |
-| `exceptions` | 1 | runtime — **stays** |
-| `pipe_blueprint` | **0** | interpreter — **moves** |
-| `validation` | **0** | interpreter — **moves** |
-| `template_guard_lint` | **0** | interpreter — **moves** |
-| `handle_pipe_errors` | **0** | interpreter — **moves** |
-
-Every importer of `pipe_blueprint` is `pipe_operators/` (7), `pipe_controllers/` (4), `pipe_signature/` (2), `builder/` (4), `libraries/` (1), `pipeline/` (1), plus the four modules M1 already hoists. **Runtime genuinely does not know about pipes** — which is what the original rule of thumb said all along.
-
-- [x] `git mv` into the package M3 created: `core/pipes/pipe_abstract.py`, `core/pipes/pipe_factory.py`, `core/pipes/rendering/` (both renderers + `__init__.py`), **plus `pipe_blueprint.py`** (D-M1-2 reversed).
-- [x] Home the other three flagged modules. `validation.py` is imported by `pipe_blueprint` and `pipe_abstract` → `pipe_machinery/`. `template_guard_lint.py` is imported only by `pipe_operators/` + `pipe_controllers/` → `pipe_machinery/`. `handle_pipe_errors.py` is imported by `validation_error_categorizer` (going to `mthds_parsing/`) and `pipeline/validate_bundle.py` → **`mthds_parsing/`**. Verify each against the closure test after the move; the inbound test used *declared* runtime packages, and `pipeline/` / `pipe_run/` are undeclared straddlers.
-- [x] Rewrite importers tree-wide (`pipe_abstract` is imported very widely — expect the largest single hunk of the track). Include the 15 string literals (ground rules).
-- [x] Move tests. The previous inventory was incomplete; the actual set under `tests/unit/pipelex/core/pipes/` is `rendering/`, `test_pipe_abstract_namespace_strip.py`, `test_pipe_abstract_signature_surface.py`, `test_pipe_blueprint.py`, `test_pipe_blueprint_presence_markers.py`, `test_pipe_blueprint_signature_enums.py`, `test_validation.py` → **`pipe_machinery/`**; `test_handle_pipe_errors_suffix.py` → **`mthds_parsing/`** (it follows its module, not the package). Plus `tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py` → the integration mirror. Re-derive the list at move time rather than trusting this one.
-- [x] Re-path subject grants (`core/pipes/pipe_abstract` 5 + `core/pipes/rendering` 15 hits, plus whatever the four newly-moved modules carry — re-measure), then `make cko`.
-- [x] Confirm `core/pipes/` now holds exactly its runtime half: `inputs/`, `stuff_spec/`, `pipe_output.py`, `variable_multiplicity.py`, `exceptions.py`. **Do not** name the new package `pipelex/pipes/` — two `pipes` packages in adjacent layers would be actively confusing.
-
-### M1c — collapse the declaration and the docs
-
-- [x] Collapse `RUNTIME_LAYER_PACKAGES` in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`: the six `pipelex.core.*` entries become the single `"pipelex.core"`. Rewrite the long `#:` note above the tuple (~lines 97-105) — it currently justifies the package-by-package listing, which no longer exists.
-- [x] **Rewrite `test_core_is_split_between_the_layers` wholesale** in `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`. (The tracker previously pointed at line 52; that line asserts `pipelex.toolsmith.thing` and is unrelated.) The real block carries **six** core assertions, all of which invert or go stale — including `assert not is_runtime_layer(module_qname="pipelex.core.qualified_ref")`, commented *"the split is deliberate, not an omission"*, which is precisely what M1c reverses. The test's name and docstring become false too. Replace with a `test_core_is_wholly_runtime_layer` asserting the positive, and draw negatives from `mthds_parsing/` and `pipe_machinery/` so they assert the new boundary rather than the absence of the old one.
- ⚠ **Vacuous-green window.** `is_runtime_layer` is a pure string predicate over qnames — it never checks that a module exists. Between M1b and M1c, four of those assertions reference module paths that no longer exist **and keep passing**. Do the rewrite in the same commit as the collapse. (Standalone hardening deferred — see [Follow-ups](#follow-ups-from-the-review).)
-- [x] Closure test (`test_runtime_layer_import_closure.py`): add `"mthds_parsing"` to `INTERPRETER_PACKAGES`; then **delete `INTERPRETER_CORE`, `INTERPRETER_CORE_EXCLUDED` and the `is_interpreter` branches that read them.** With D-M1-2 reversed and `pipe_blueprint` moving too, this is now correct **as stated** — nothing is left for them to name. (Under the *original* D-M1-2 it would have silently relaxed a live constraint: `hub-layering.md:220` says `pipe_blueprint` is the one entry not caught transitively, so it was the only name in the tuple doing real work. Reversing D-M1-2 is what makes the deletion honest.) Also update the module docstring's "two documented interpreter homes are deliberately absent" paragraph.
-- [x] **Prove each new `INTERPRETER_PACKAGES` token is spelled right.** `DIRTY_ENTRY_POINT` only proves that *at least one* configured token matches — it imports `interpreter_hub`, whose closure contains several old interpreter packages, so a typo in `mthds_parsing`, `pipe_machinery` or `pipe_signature` leaves the suite green while that token guards nothing. The predicate lives inside a `textwrap.dedent` string, so nothing type-checks it. Add one leaf probe per new package (a case that must be flagged), or lift the predicate out of the embedded string and unit-test it directly.
-- [x] **D-M1-6 — RULED: add `"pipe_signature"` to `INTERPRETER_PACKAGES`.** Verified 2026-07-27 against all five runtime entry points: **zero** `pipe_signature` modules loaded by any of them, so this is safe and surfaces no pre-existing leak. It is independent of the moves — pull it forward to Phase 0 or M3 if you want it out of M1c's diff.
-- [x] **Verify the straddler did not become a failure.** `PipelexBundleBlueprintValidationErrorData` (moving into `mthds_parsing/exceptions.py`) is imported by `pipeline/` and `libraries/`. Measured 2026-07-27: **no runtime-layer entry point currently loads it** — `runtime_hub`, `plugins.builtins` and `content_generator` pull in only `pipelex.pipeline` + `pipeline.pipeline_models` — so the deleted exclusion should cost nothing. If the closure test *does* fail on it, do **not** re-add an exclusion: move the data class to a runtime-layer home instead, and record the decision here.
-- [x] **Spec + conformance, in this same change.** `conformance/tests/pipelex_transport/test_data.py:45` pins `("pipelex.core.pipes.pipe_abstract", "PipeAbstract", "class")` in `ALLOWED_SURFACE` — an active, unskipped test — and `docs/specs/pipelex-transport-boundary.md:133` names the same path. Workspace CLAUDE.md requires both sides to change with the code, and `make check-spec-links` gates it. ⚠ `_hub`'s `make agent-test` **structurally cannot catch this** — different repo. Also check `docs/specs/pipelex-transport-boundary.md:164` (`pipelex.plugins.orchestrator_registry` — survives M2, it is a mechanism module) and `docs/specs/pipelex-mthds-protocol.md:47` (`PipelexBundleBlueprint` — class name unchanged, path only).
-- [x] `docs/contribute/hub-layering.md`: (a) **keep the rule of thumb as written** — *"if it names a `Pipe`, it belongs to the interpreter layer"* (line 115) is correct, and was only slated for rewrite to accommodate the `pipe_blueprint` misclassification that D-M1-2's reversal removes; (b) delete the `core.pipes.pipe_output` carve-out paragraph (line 110) — the collapsed declaration now covers it; (c) **rewrite line 220's predicate paragraph** — it justifies naming core's Pipe-machinery modules one by one and singles out `pipe_blueprint`; both disappear (this target was missing from the tracker); (d) update the Known-inversions (line 242) and "Where core splits" (line 111) sections for the new package names; (e) update line 80's `runtime_hub` must-not-name list.
-- [x] Update the classification snippet in `wip/refactoring/modularity-refactors.md` → Measurement (`I` gains `mthds_parsing`, `pipe_machinery`) so the design doc does not go stale.
-- [x] `make drift-plan` → the `hub-layering-convention` contract triggers on `hub_layering_guard.py`; review the doc for real, `git add` the trigger files, then `make drift-ack CONTRACT=hub-layering-convention RATIONALE="…"`.
-- [x] Changelog entry, **breaking**: the two new packages, the class rename, and the `type_uri` change if D-M1-4 says rename.
-
-### Exit criteria
-
-| | baseline | target | **actual** |
-| --- | --- | --- | --- |
-| `RUNTIME_LAYER_PACKAGES` entries naming `pipelex.core.*` | 6 | **1** (`pipelex.core`) | ✅ **1** |
-| `core` modules loading > 0 interpreter modules | 9 (8 after M3) | **0** | ✅ **0** (4 after M1a, 0 after M1b) |
-| `core/pipes/` modules with 0 runtime-layer importers (inbound test) | 4 | **0** | ✅ **0** — what remains scores 4 / 5 / 1 |
-| doc carve-outs for `core.pipes.pipe_output` | 1 | 0 | ✅ **0** |
-| inverted `core → pipe_*` import statements | 19 (after M3) | **0** | ✅ **0** (3 after M1a) |
-| `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` entries | 7 / 2 | **deleted** | ✅ **deleted** — `EXCLUDED` in M1a, `CORE` in M1b |
-
-### 🛑 CHECKPOINT M1 — HARD STOP
-
-1. **Gates:** `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make gep` (diff must be reviewed, not just generated).
-2. **Verify:** re-run the classification snippet with the extended set — every remaining `pipelex.core.*` module reports `0 0`. **Re-run the inbound test too** (see [Measurements](#measurements)) — every module left in `core/pipes/` must have ≥1 runtime-layer importer. `make chl` passes with the collapsed declaration *and* the transitive rule reports zero breaching runtime-layer modules. Closure test green including the dirty control.
-3. **Cross-repo gate (cannot be run from `_hub`):** in the `conformance/` repo, update `ALLOWED_SURFACE` and `docs/specs/pipelex-transport-boundary.md`, then run `make check-spec-links`. This is a hard checkpoint item, not sweep work.
-4. **Update this file** + [Cold-start brief](#cold-start-brief) + [Measurements](#measurements).
-5. **Commit**, then **fan out reviews** with the commit range. M1 reviews: `correctness-and-imports` + `boundary-and-naming` + `over-engineering` + `test-and-docs-sync`.
-6. **Stop.** Report verdicts and wait.
-
-#### Checkpoint record — reached 2026-07-27, commits `0f0309b8f` · `c9c45c475` · `10080cf26`
-
-**All gates green** at `10080cf26`: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check`, `chl`, `gep` (no churn — no error class moved in M1b/M1c), `tb`. Every exit-criterion actual is in the table above.
-
-**Decisions taken during implementation** (each one the plan authorized in advance):
-
-- **D-M1-8 — `PipelexBundleBlueprintValidationErrorData` moved to `pipelex.core.exceptions`, not into `mthds_parsing/`.** M1c's plan said to verify the straddler "did not become a failure" and, if it did, to move the data class to a runtime-layer home rather than re-add an exclusion. It did: the claim "no runtime-layer entry point currently loads it" was wrong — `pipelex.core.memory.working_memory_factory` reaches it, and the closure test's own docstring said so all along (`core.bundles.exceptions` was in `INTERPRETER_CORE_EXCLUDED` precisely because it lands in every runtime closure). Moved to `core/exceptions.py`, which already holds the two sibling structured error-data models it shares `PipeValidationErrorType` with. That is what let `INTERPRETER_CORE_EXCLUDED` be deleted outright in M1a instead of being carried forward.
-- **`INTERPRETER_CORE` deleted in M1b, not M1c.** M1b is the commit that empties it; leaving a four-entry tuple whose comment says "not under a top-level package of its own" for one commit would have been the exact "passing under a false rationale" shape M3's review flagged.
-- **Test moves were re-derived, and the tracker's inventory was again incomplete** — it missed `test_execution_data_coverage.py`, `test_pipe_validate_before_run.py`, `test_run_pipe_tracer_metadata.py` and `test_inputs_template_toml.py`. Derived instead from each module's actual subject (grep each test for the `core.pipes.*` module it imports).
-- **`tests/unit/pipelex/core/test_data/` stays put.** It is a shared MTHDS corpus consumed from `tests/integration/pipelex/language/` as well as by the parser tests, so it is not a mirror of a source module. Noted rather than silently left.
-
-**The one real bug the move introduced, and nothing static could have caught it.** `tests/integration/.../test_input_renderer_light_golden.py` derived its fixture paths from `Path(__file__).parents[4]`. Moving it one level shallower silently repointed that at the repo root, and it failed only in the full suite — no import rewrite, type checker or import-graph tool sees a parent count. Re-anchored on `tests/` **by name**; every other moved test was then swept for the same shape (none had it). Worth carrying into M2: a depth index is a module-location dependency that looks like a constant.
-
-**Cross-repo gate (item 3) — done, and it reports more than M1 caused.** `conformance/tests/pipelex_transport/test_data.py` and `docs/specs/pipelex-transport-boundary.md` now pin `pipelex.pipe_machinery.pipe_abstract`; `make check-spec-links` passes. Running the transport arm against this branch (`CONFORMANCE_PIPELEX_PYTHON=_hub/.venv/bin/python`) then reports two failures, and the split matters:
-
-- **7 provider-side symbols missing — all pre-existing**, none touched by M1: `pipelex.hub.*` (5, retired by the hub split) plus `pipelex.pipeline.job_metadata.JobMetadata` and `pipelex.graph.trace_context.TraceContext` (moved by the Phase 3 type moves). `ALLOWED_SURFACE` is stale w.r.t. two *earlier* tracks. This is release-gated sweep debt that predates M1 and should be folded into the same wave.
-- **1 consumer-side hit — M1-caused and working as designed**: `pipelex-transport/pipelex_transport/primitives/pipe_classification.py` still imports `pipelex.core.pipes.pipe_abstract`. The deny-by-default AST scan is pointing at the Phase 5 sweep item. **Deliberately not fixed here** — `pipelex-transport` pins a *released* `pipelex`, so changing it now breaks it immediately; it lands with the wave.
-
-⚠ **Both cross-repo edits are left UNCOMMITTED in their own repos** (`conformance/` on `dev`, workspace-root `docs/specs/`), one line each. Committing them to `dev` would break those repos against the released `pipelex` before the wave lands. Whoever runs the sweep must pick them up.
-
-**Two follow-ups closed early, both mutation-checked.** T10 (guard against vacuously-green string-predicate tests) is **done**, in the form the plan preferred: `RUNTIME_LAYER_PACKAGES` entries and `INTERPRETER_PACKAGES` tokens must each resolve on disk. And the gap M3's checkpoint flagged as "no contract binds the matched triple" is now bound by a test rather than a drift contract — the closure predicate and `hub-layering.md`'s snippet must name the same set. ⚠ **The design doc's third copy is deliberately not asserted**, since `wip/` is archived at track end; it stays a manual concern for M2, which adds no interpreter package and so should not disturb it.
-
-#### Review round — M1, done 2026-07-28, fixes applied
-
-Four reviews over `6d5b9418a..a23c1b70b`. **All four cleared the moves themselves**, each by measurement rather than reading: every module under the three packages imports cleanly, the only module-level cycle in `pipelex/` (`core.stuffs.stuff` ↔ `stuff_artefact`) is unchanged and untouched, `pipelex/core/**` holds zero imports of any interpreter package, and the collapse to one `pipelex.core` entry *widens* enforcement — `core.exceptions`, `core.registry_models`, `core.qualified_ref` and bare `core.pipes` were previously undeclared and unchecked. The D-M1-8 placement was tested skeptically and stands: 6 of 9 runtime entry points transitively load `pipeline.exceptions`, so filing the straddler with the parser would have broken the property for real.
-
-**Every defect was documentation, fixture or test-quality drift — none in the moves.** All confirmed against the code before fixing.
-
-- **The user-facing regression, and the one no gate could catch.** `_SUBSYSTEM_SECTIONS` in `pipelex/errors/error_pages_generator.py` never got an `mthds_parsing` row. `_subsystem_key` reads the module's *second segment*, so the rename silently reclassified both parser errors through `_FALLBACK_MACRO_SLUG` — the two errors a method author hits most moved from **Authoring & language** to **Platform & tooling**. Fixed with the missing row. ⚠ **The lesson is about the check, not the row:** `make gep` reporting "no diff" was read as evidence the rename propagated, and it is not — it proves committed matches generated, and the pages matched *because* they baked in the wrong fallback. The generator is deliberately built so a missing curation entry still renders rather than failing. **Read the generated diff, never just the exit code.**
-- **A wire-visible brand defect the rename introduced.** `title()` auto-derives from the class name, so `MthdsParserError` published the RFC 7807 title `"Mthds parser"` — the standard's brand, mis-cased, on every error report. Fixed with `_declared_title = "MTHDS parser"`. The five error-report fixtures that paired the new `error_type` with the retired `title`/`type_uri` are corrected, and the identity triple is now **pinned by a test** (`test_mthds_parser_error_identity_is_pinned`) — nothing asserted it before, which is exactly how the fixtures came to carry a shape the class cannot produce.
-- **An overclaim I wrote into the M1c rewrite.** "Every `pipelex.core.*` module loads zero interpreter modules" is false as stated: `core.pipes.pipe_output` loads `pipeline.pipeline_models`, and `runtime_hub` also loads `pipe_run.pipe_run_mode`. It holds only under the closure predicate's deliberate `pipeline`/`pipe_run` carve-out — which line 228 of the same page states plainly. The base commit had said the honest opposite at that spot. Qualified in all four places the property is stated. See [deferred follow-ups](deferred-placement-follow-ups.md) §3: the caveat now repeats in four places, which is itself the argument for moving those two leaves.
-- **Eighteen assertions carrying three bits.** The two guard tests M1c rewrote were an *inventory*, not an invariant: with `pipelex.core` a single prefix entry, any string under it is True and any string under `pipe_machinery.`/`mthds_parsing.` is False, invented names included. This repeats the defect M3's own review round found and recorded as a lesson. Replaced with derived invariants: `pipelex.core` is declared with **no** `pipelex.core.*` sub-entry (re-splitting core fails), and `RUNTIME_LAYER_PACKAGES` ∩ `INTERPRETER_PACKAGES` = ∅ — which also binds two declarations maintained in separate modules and never previously compared.
-- **The regex scraper was self-inflicted.** `INTERPRETER_PACKAGES` lived inside the `textwrap.dedent` string, which is what forced a regex to read it back and was the stated justification for the new tests. Hoisted to a real module-level constant handed to the subprocess **as argv** — no interpolation, no scraper, names now lint-visible. Mutation-checked that the argv path is load-bearing: emptying the set makes the negative control fail.
-- **`parents[5]`, and why it was worse than a style point.** `test_hub_layering_guard.py` validated the declaration against `Path(__file__).resolve().parents[5] / "pipelex"` while the sibling test added in the *same commit* carries a comment condemning depth indices. Not merely fragile: `parents[6]` is the workspace root, which holds a sibling `pipelex/` checkout — so a module moved one level shallower would validate a **different repo** and pass. Re-anchored on `tests/` by name.
-- **Stale prose, all fixed:** `runtime_hub.py`'s "one rule" docstring (still forbade two deleted packages, omitted the four current ones — and it is a declared trigger of the drift contract whose ack reviewed only the doc copy); `hub-layering.md` placing the renderers in `core/pipes/rendering/` in the present tense, plus the paragraph arguing for that regrouping; two adjacent paragraphs on the same premise reaching opposite conclusions; the closure test's own entry-point and `pipe_machinery` comments; `handle_pipe_errors.py` citing a now-sibling module; the blueprint-location enumeration in the kit rules source and `builder/CLAUDE.md`; `tests/CLAUDE.md` missing rows; the CHANGELOG naming a package deleted later in the same unreleased cycle.
-
-**Deferred, not fixed** — placement and naming accuracy, no silent bug, recorded in [`deferred-placement-follow-ups.md`](deferred-placement-follow-ups.md): three modules in `mthds_parsing/` that are not parsing (`pipe_sorter`, the generic half of `helpers`, `handle_pipe_errors`); the parser fixture corpus still filed under `tests/unit/pipelex/core/`; and the `pipeline`/`pipe_run` leaf leak. `pipe_machinery/` was checked module by module and is accurately named throughout.
-
-**Fixed in passing** (pre-existing, same class): `tests/CLAUDE.md` had no row for `pipelex/codegen/` or `pipelex/pipe_signature/` either.
-
----
-
-## M2 — separate the plugin mechanism from the vendor adapters
-
-`pipelex/plugins/` is two things under one name: the mechanism (17 top-level modules) and the built-in vendor adapters (17 directories). Splitting them makes the one-way dependency visible: adapters → mechanism, engine → mechanism, mechanism → nothing.
-
-### Work
-
-- [x] **Create `pipelex/providers/__init__.py` (empty)** — same `INP001` reason as `mthds_parsing/` (ruff `select = ["ALL"]`, tests-only exemption). The commit fails lint without it.
-- [x] `git mv` the 17 vendor directories to a new `pipelex/providers/`: `anthropic`, `azure_rest`, `bedrock`, `blackboxai`, `docling`, `fal`, `gateway`, `google`, `huggingface`, `linkup`, `mistral`, `openai`, `openrouter`, `portkey`, `pypdfium2`, `secrets`, `storage`. (D-M2-1: `providers/` over `backends/` — `backends/` would collide with `pipelex/cogt/model_backends/`, and the code's own vocabulary for the non-inference adapters is already "provider": `secrets_provider_registry`, `storage_provider_registry`.)
-- [x] `pipelex/plugins/` keeps the mechanism only: `contract.py`, `registrar.py`, `discovery.py`, `exceptions.py`, the seven `*_registry.py`, `model_handle.py`, `sdk_client_registry.py`, `sdk_client_manager.py`, `backend_extras_factory.py`.
-- [x] `builtins.py` follows the vendors → `pipelex/providers/builtins.py`, still exporting `RUNTIME_BUILTIN_PLUGINS` / `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES`. Re-point the downward import in `pipelex/interpreter_plugins/builtins.py`. Both stay parameters of `build_registrar` — unchanged.
-- [x] Rewrite imports. **Watch the `secrets` / `storage` trap** (ground rules): `pipelex.plugins.secrets` is a vendor dir, `pipelex.plugins.secrets_provider_registry` is a mechanism module that must not move. Same for `storage`.
-- [x] **Rewrite the 189 string-literal module references** (ground rules) — `mocker.patch("pipelex.plugins.<vendor>...")` targets, invisible to import rewrites and to pyright. They fail loudly at test time, so `make agent-test` is the gate, but budget them as real work: an import-only rewrite turns the suite red in bulk and reads as a catastrophic move rather than expected residue.
-- [x] **Add `"pipelex.providers"` to `RUNTIME_LAYER_PACKAGES`, and add a guard test that proves it.** This is the one step where a mistake is invisible — dropping the vendors from the guard silently un-declares the largest runtime package.
- ⚠ **The plan previously claimed "the transitive rule is what catches it." That is backwards.** Verified at `pipelex/cli/dev_cli/commands/hub_layering_guard.py:677`: the rule iterates `sorted(module for module in reaching if is_runtime_layer(module_qname=module))`. An **undeclared** package is excluded from the rule's domain, so omitting it makes the guard go *quieter*, not louder. **No existing gate catches this.** Add an explicit assertion to `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` that a representative `pipelex.providers.*` module `is_runtime_layer`.
-- [x] Add `pipelex/providers/builtins.py` to the closure test's `RUNTIME_LAYER_ENTRY_POINTS` (replacing `pipelex.plugins.builtins`, which after the move no longer aggregates anything). Its presence there is load-bearing history: that module and three neighbours breached the boundary transitively while both gates stayed green.
-- [x] Move tests: `tests/unit/pipelex/plugins/` and `tests/integration/pipelex/plugins/` — split so vendor tests land under a `providers/` mirror and mechanism tests stay under `plugins/`.
-- [x] Re-path subject grants (160 hits under `plugins/` — the bulk are vendor workers), then `make cko`.
-- [x] `make gep` — several vendor directories carry exceptions modules (`gateway`, `portkey`, `bedrock`, `google`, `mistral`, `openai`, …), so expect a wide `Defined in` diff. Filenames and `type_uri`s must be **unchanged** (no class renames in M2); if one changes, something got renamed by accident.
-- [x] Docs sweep for `pipelex/plugins/<vendor>/` paths: `docs/under-the-hood/reasoning-controls.md` (a table of ~10 paths), `error-model.md` (3 refs to `pipelex/plugins/*/`), `inference-backend-plugins.md`, `secrets-provider-plugins.md`, `orchestrator-plugins.md`. **Do not touch the entry-point group name** `"pipelex.plugins"` — it is a group identifier, not a module path, and it is the third-party contract.
-- [x] **Sweep architectural prose in *source*, not just `docs/`.** Two module docstrings describe the pre-M2 layout and go stale silently: `pipelex/plugins/contract.py:33-35` ("``pipelex.plugins`` for the runtime half, ``pipelex.interpreter_plugins`` for the interpreter half" — after M2 the runtime *adapters* are in `pipelex.providers`), and `pipelex/interpreter_plugins/builtins.py:3-8` (describes `pipelex.plugins` as the neighbouring runtime adapter package). Both are the kind of comment the repo's own diagram-maintenance rule says must move with the code.
-- [x] `docs/contribute/hub-layering.md` → **Known inversions**: record the four `cogt → provider config` imports (`anthropic`, `google`, `mistral`, `openai` config classes reached from `cogt/config_cogt.py`) as a deliberate, documented exception. Rationale (D-M2-2): the main config model is statically typed end-to-end (`configs.py` ⇄ `pipelex.toml` structural sync); making vendor config sections plugin-contributed would trade that static typing for a dynamic registry.
-- [x] **`make drift-ack CONTRACT=hub-layering-convention`.** M2 adds `pipelex.providers` to `RUNTIME_LAYER_PACKAGES`, a trigger file in `drift.toml:65-69`, so the contract opens and M2's checkpoint `make drift-check` fails without an ack. Review the doc for real — M2 adds a whole runtime-layer package, which the "Where core splits" and Known-inversions sections both describe.
-- [x] Changelog entry, **breaking**: `pipelex.plugins.<vendor>` → `pipelex.providers.<vendor>`. Two things to state explicitly: (a) the *plugin entry-point contract is unaffected* — an external plugin imports `pipelex.plugins.contract` / `pipelex.plugins.registrar`, both of which stay put; (b) **no known external consumer imports the vendor paths** (measured 2026-07-27: zero hits across every sibling repo), so the break is in-tree only. Do not imply a consumer migration that nobody needs.
-
-### Exit criteria
-
-| | baseline | target | **actual** |
-| --- | --- | --- | --- |
-| mechanism modules importing a vendor | 1 (`builtins.py`, by design) | **0 in `plugins/`**, 1 in `providers/` | ✅ **0 / 1** — `providers/builtins.py` names all 17, nothing under `pipelex/plugins/` names any |
-| vendor modules importing outside `providers/` + `plugins/` | 0 | 0 (unchanged) | ✅ **0** |
-| guard test asserting `pipelex.providers.*` is runtime-layer | 0 | **1** | ✅ **1**, derived from disk and mutation-checked red |
-| `cogt → <specific vendor>` statements | 7 | 7 (4 documented, 2 in F1, 1 self-resolving) | ✅ **7**, and they are the *only* three source files outside `providers/` naming a vendor |
-| `RUNTIME_LAYER_PACKAGES` covers every vendor module | yes | yes | ✅ **17 / 17** |
-
-⚠ **Measurement trap, cost ~10 min and it under-counted silently.** `pypdfium2` contains a digit, so a `[a-z_]*` character class in a grep pattern skips it — the first pass reported 16 of 17 vendor imports in `builtins.py` and would have reported a clean `cogt` count even if a `pypdfium2` import existed. Use `[a-z0-9_]+` for anything matching a vendor segment. The *rewrite* script was never at risk (it uses literal vendor names), only the measurements taken afterwards — which is the worse of the two, because a measurement is what tells you the rewrite was complete.
-
-> **The "vendor imports nothing but the mechanism" metric was false by construction** and is restated above. The design doc deliberately preserves cross-vendor edges (`blackboxai` / `openrouter` / `portkey` → `openai`; `gateway` → `fal` / `google` / `openai` / `portkey`) because they stay inside the new package — e.g. `blackboxai/blackboxai_completions_factory.py:9` and `openrouter/openrouter_completions_factory.py:8` import `OpenAICompletionsFactory` at module level. A metric targeting zero could never be met. Measure "imports outside `providers/` **and** `plugins/`" instead.
-
-### 🛑 CHECKPOINT M2 — HARD STOP
-
-1. **Gates:** `make cko` → `make cleanderived` → `make agent-check` → `make agent-test` → `make drift-check` → `make chl` → `make gep` (review the diff).
-2. **Verify:** transitive layering rule reports zero breaching runtime-layer modules; closure test reports zero interpreter modules for every runtime entry point *including the new `providers.builtins`*; the dirty control still fails.
-3. **Update this file** + [Cold-start brief](#cold-start-brief) + [Measurements](#measurements).
-4. **Commit**, then **fan out reviews**. M2 reviews: `correctness-and-imports` + `boundary-and-naming` + `over-engineering`.
-5. **Stop.** Report verdicts and wait.
-
-#### Checkpoint record — reached 2026-07-28
-
-**All gates green**: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check` (two contracts acked), `chl`, `gep` (diff reviewed, see below), `tb`. Every exit-criterion actual is in the table above.
-
-**Scale of the move:** 17 vendor packages + `builtins.py` out of `pipelex/plugins/`; **1364 substitutions across 136 files**, of which **191 were string literals** (the plan predicted 189 — the drift is two, both in test mock targets). The completion check was the one that makes "did I get them all?" answerable: grep the whole tree for the old paths and assert the only survivors are in the deliberately excluded files (`CHANGELOG.md`, `TODOS.md`, `wip/`, `docs/errors/` — history and generated pages, which must not be textually rewritten; the error pages are regenerated by `make gep` instead).
-
-**The `secrets` / `storage` trap was real and was avoided by construction.** Every substitution anchors the vendor name on a `(?![A-Za-z0-9_])` lookahead, so `plugins.secrets` (vendor dir) rewrites while `plugins.secrets_provider_registry` (mechanism module) does not. Verified after the fact by asserting that no mechanism module is reachable at a `pipelex.providers.*` path, and that the `pipelex.plugins` **entry-point group name** — a group identifier, not a module path, and the third-party contract — is untouched.
-
-**Decisions taken during implementation:**
-
-- **D-M2-4 — M2 was built on top of M1 on this branch, not on a parallel branch off #1064.** The plan's topology had M2 independent and rebased after M1, with a mandatory drift re-ack because a rebase invalidates the digest. Building it stacked satisfies the prescribed landing order, eliminates the three-file conflict the plan warned about, and makes the ack recorded here final. See [Gating](#gating).
-- **Test split derived per module, not from the plan's two-line instruction.** The vendor subdirectories were unambiguous, but the flat modules needed reading. `test_linkup_plugin_guard.py`, `test_secrets_plugin.py` and `test_storage_plugin.py` are *vendor* tests despite sitting at the `plugins/` root (they moved into the matching `providers/<vendor>/` mirrors); `test_transport_retry_wiring.py` and `test_plugin_pipelex_storage_images.py` are cross-vendor and moved to the `providers/` root; `test_inference_backend_coverage.py` reads as a vendor test by name but is a *mechanism* round-trip over `BUILTIN_PLUGINS` and stayed. On the integration side `conftest.py` moved with the four vendor tests, because all four of its consumers moved and the three modules that stayed use none of it.
-- **`tests/CLAUDE.md` gained a `pipelex/providers/` row.** The source-to-test mapping is 1:1 by convention; a new source package with no row silently drops out of every targeted test run.
-
-**The one user-facing defect, and it is the same shape M1 hit three weeks ago.** `_SUBSYSTEM_SECTIONS` in `pipelex/errors/error_pages_generator.py` had a `plugins` row and no `providers` row. `_subsystem_key` reads a module's **second dotted segment**, so every vendor error class would have silently reclassified out of *Inference & providers* into the `_FALLBACK_MACRO_SLUG` (*Platform & tooling*) — with `make gep` exiting 0 and producing an entirely plausible diff. This is M1's `mthds_parsing` regression repeating on the next module move, and it was caught **only** because M1's recorded lesson was to read the generated diff rather than trust the exit code. Fixed by splitting the row in two, which the content wanted anyway: **Provider adapters** (a vendor SDK rejected the call) and **Plugin system** (a plugin failed to load or claimed a taken slot). Verified by the negative: `docs/errors/platform-and-tooling.md` is byte-identical, so nothing fell through. No page was added or removed, so no `type_uri` changed.
-
-**Two drift contracts opened, not one.** `hub-layering-convention` was predicted. `config-docs` was not — re-pathing the four vendor config imports touches `cogt/config_cogt.py`, a trigger. Reviewed for real and logged as **friction**: `docs/configuration/` cites no Python import path anywhere, so an import-only diff cannot affect it *by construction*. That is the second such opening on that contract from a pure refactor sweep, and the dogfood log now carries a concrete narrowing proposal (ignore diffs confined to import statements) backed by two data points.
-
-#### Review round — M2, done 2026-07-28, fixes applied
-
-Three reviews over `7beda698f..dee323e28`. **All three cleared the move itself, by measurement rather than reading.** The `correctness-and-imports` pass found **no import defect at all**: it AST-walked every `.py` under `pipelex/` and `tests/`, resolved all 944 `pipelex.`-prefixed string constants against the live interpreter (which covers every `mocker.patch` target), imported all 111 modules under `pipelex.providers` in one process, and confirmed that importing the entire `pipelex.plugins` mechanism pulls in **zero** `providers` modules — so the one-way dependency is empirically true, not merely asserted. `boundary-and-naming` independently verified the same and confirmed the "omitting the entry makes the guard quieter, not louder" premise by monkeypatching the tuple and watching the guard report zero violations either way.
-
-**Every defect was in the documentation of the boundary, or in the test that guards it. None in the move.**
-
-- **The new guard test repeated a defect this track has now made three times.** `is_runtime_layer` matches by dotted prefix, so reading the vendor list off disk and looping over it carried exactly one bit — `is_runtime_layer("pipelex.providers.totally_invented.x")` is `True`, the assert fires on the first entry, and the remaining iterations can never execute. Two reviewers flagged it, and both correctly noted the test must **not** be deleted: it is the only thing in the suite that catches a dropped declaration, because the guard CLI itself stays green. The clincher is that `test_core_is_declared_as_one_whole_package`, which M1c added *to this same file*, has a docstring condemning precisely this shape. Replaced with a membership assertion over **both** halves of the split — which is strictly stronger than what it replaced (dropping `pipelex.plugins` now fails too, where the disk-scan version only caught `pipelex.providers`), carries two bits instead of one, and drops a real second failure mode the reviewers spotted: an adapter added without an `__init__.py` is importable as a namespace package but was silently skipped by the filter. Both mutations checked red.
-- **A boundary claim my own commit contradicted two sections later.** "Where the built-in plugins split" asserted the one-way dependency as three clauses, and the third — *"the engine depends only on the mechanism"* — is false: importing `cogt.config_cogt` alone loads **8** `pipelex.providers.*` modules, which the Known-inversions bullet added in the *same commit* documents and justifies. One document, two opposite claims about the same word. This is the identical shape M1's review found ("two adjacent paragraphs on the same premise reaching opposite conclusions"), and it is the worst defect of the round: a layering page that states the boundary wrongly is more harmful than one that omits it. Clause dropped and scoped explicitly to the two packages, with a pointer to the inversions.
-- **"One directory per vendor" is wrong twice over.** `providers/secrets/` registers the built-in `env` backend — no vendor exists — and `providers/storage/` registers local, in-memory, S3 and GCP behind a single directory; in both cases only the registration shim moved, the implementations are under `pipelex/tools/`. The package *name* survives this (all three reviewers agree `providers` is right, and it is exactly why `vendors/` would have been wrong), but the prose overreached. Corrected, and the exception is now stated rather than glossed.
-- **Hardcoded counts, flagged independently by all three reviewers**, against an explicit workspace rule ("Never hardcode counts… they create diff churn, go stale silently, and add no value"). Four live locations pinned "seventeen" / "the seven capability registries". The irony was pointed out and is fair: the neighbouring test went out of its way to avoid becoming an inventory while the prose beside it hardcoded the number. Fixed. Left alone deliberately: the same words inside the recorded drift-ack rationales and the dogfood log, which are append-only records of a decision at a point in time — rewriting them would falsify the record.
-- **Two unchecked F1 items named paths M2 had moved** (`plugins/{google,openai}/*_img_gen_factory.py`). Completed items' historical references are correct as written; it is specifically the open ones that must name the current tree, because F1 is the next work on this branch and this file is its handoff. Fixed.
-
-**One reviewer claim was wrong and is rejected:** `correctness-and-imports` reported a fifth hardcoded count at `hub_layering_guard.py:114`. There is no numeral in that file — verified by grep. The other four locations it named were correct.
-
-**Two method findings worth more than the defects.**
-
-- **This shell's `grep` is a ugrep wrapper that honours `.gitignore`.** Run from the workspace root it silently skips every sibling repo; inside `_hub` it skips the stale `site/` tree. A naive `grep -r` therefore returns a **false clean** on exactly the sweep a rename refactor depends on. The whole-tree completion check was re-run with `/usr/bin/grep` and the verdict held — but it held by luck of using `git grep` for the load-bearing pass, not by design. **Use `/usr/bin/grep` or `git grep` for any completeness sweep.**
-- **A brace-glob evades a per-vendor regex.** `plugins/{google,openai}/` is a real module reference that no substitution keyed on a single vendor name will match — it is the same class of miss as a string literal, one level further out. Worth adding to the ground rules before the release-wave sweep; the same shape exists in a `pipelex-api/wip/` note.
-
-**Reported and not reproduced:** one reviewer saw the new guard test fail once in five full-suite runs, with `is_runtime_layer` returning `False` for a module the committed tuple covers — impossible against this tree, and the run carried the `bringing up nodes...`-twice signature that `docs/agents/debugging-hanging-pytest-runs.md` names as xdist worker crash-and-replace. Re-run 25 times under xdist after the rewrite: **zero failures**. The rewritten test no longer touches the filesystem, which removes one of the two moving parts. Recorded as an unreproduced observation rather than closed — if it recurs it needs root-causing, not tolerating.
-
-**Not done here, deliberately:** the `wip/` docs that still describe the pre-M2 layout (`wip/plugins/*.md`, the design doc's own prose) were excluded from the rewrite along with `CHANGELOG.md` and `TODOS.md`, per M1's method. The design doc's classification snippet needs **no** change — M2 adds a runtime-layer package, not an interpreter one, so the matched triple is undisturbed.
-
----
-
-## Follow-up F1 — the two `cogt → vendor` img-gen factory imports behind a registry
-
-Deliberately **not** inside the 127-file M2 move: this is a behavior change and would be invisible in that diff (D-M2-2).
-
-**Re-scoped 2026-07-27 from three imports to two.** Two corrections:
-
-1. **`backend_factory.py:53` (VertexAI) is dropped.** VertexAI support is being removed, so the edge self-resolves. Do not build auth-dispatch machinery for a vendor on its way out — it would outlive its reason. The import is already deferred (`# noqa: PLC0415`), so it costs nothing while it remains.
-2. **No registry. There is no dispatch key.** The first review proposed an arg-builder slot on `inference_backend_registry`; the outside voice showed that cannot work, and it is verified:
- - `ImgGenArgsFactory.make_args_for_model(cls, model_rules, *, img_gen_job, nb_images, model_id, model_name)` — **receives no `sdk`** (`img_gen_args_factory.py:54-62`).
- - Dispatch is a `match` over **`AspectRatioTaxonomy`**, not over a provider (`img_gen_args_factory.py:367-396`): `GPT_IMAGE_LEGACY` / `GPT_IMAGE_2` → `OpenAIImgGenFactory.size_for_*`, `GEMINI_*` → `GoogleImgGenFactory.resolve_image_config`, `QWEN_IMAGE` → …
- - The gateway worker is **one SDK that executes both** OpenAI and Google taxonomies (`gateway_img_gen_worker.py:78-84`), so an `(family, sdk)` key cannot select the right helper at all.
-
-**Ruled: move the helpers, do not dispatch them.** Extract the OpenAI/Google taxonomy and geometry helpers into a **neutral mapping module under `cogt/img_gen/`**, then have both `ImgGenArgsFactory` and the provider workers import *inward*. These are taxonomy utilities keyed by a `cogt`-owned enum — they were never independently dispatched workers.
-
-- [x] Extract the taxonomy/geometry helpers from `providers/google/google_img_gen_factory.py` and `providers/openai/openai_img_gen_factory.py` into a neutral `cogt/img_gen/` mapping module. (Both re-pathed by M2 — F1 is unstarted work, so its paths must name the current tree.) — **two** modules, not one (D-F1-1): `cogt/img_gen/img_gen_gemini_mapping.py` + `cogt/img_gen/img_gen_gpt_mapping.py`.
-- [x] Re-point `img_gen_args_factory.py:37-38` (currently **module-level**, not deferred) and the provider workers to import inward from it. Net import-cost improvement: removes two eager vendor imports from a `cogt` module. — done; the inward importers are `providers/google/google_img_gen_worker.py` and `providers/gateway/gateway_factory.py`.
-- [x] Tests covering each taxonomy branch, including the unmapped-taxonomy path. — the branch coverage already existed and moved with the module (`test_img_gen_gemini_mapping.py`, incl. the non-Gemini-taxonomy rejection; the GPT-Image branches are covered from the args-factory side). What was **missing** is the invariant F1 actually buys, added as `test_img_gen_mapping_neutrality.py` (D-F1-4).
-- [x] Changelog entry.
-- [x] Leave `backend_factory.py:53` alone; re-check after VertexAI removal lands. — untouched; it is now the *only* remaining `cogt → specific vendor` edge of this kind.
-
-**Why this beats the registry**, recorded so it is not re-litigated: no hub wiring, no registrar menu entry, and therefore **no plugin-API version bump**. `plugins/contract.py:5-19` uses strict coarse API equality and explicitly versions registrar changes, so adding a menu capability would force a coordinated plugin wave — for two import sites. It also fixes the dependency *direction* rather than routing it through machinery, and it leaves `pipelex.plugins.contract` untouched, which is what M2's changelog promises.
-
-### Exit criteria
-
-| | baseline | target | **actual** |
-| --- | --- | --- | --- |
-| `cogt → specific vendor` import statements | 7 | **5** (4 config + 1 deferred VertexAI) | ✅ **5** |
-| source files outside `providers/` naming a vendor module | 3 | **2** | ✅ **2** (`config_cogt.py`, `backend_factory.py`) |
-| eager vendor imports in `cogt/img_gen/` | 2 | **0** | ✅ **0** |
-| third-party imports in the mapping modules | 1 (`openai`) | **0** | ✅ **0**, and pinned by a test |
-| tests pinning the neutrality of the new home | 0 | **1** | ✅ **1** module / 2 tests, both mutation-checked red |
-
-### 🛑 CHECKPOINT F1 — HARD STOP
-
-Gates as above (this one *does* change behavior, so `make agent-test` is the real gate, not a formality). Reviews: `correctness-and-boot` + `over-engineering`. Then stop.
-
-#### Checkpoint record — reached 2026-07-28
-
-**All gates green**: `cko`, `cleanderived` + fixture regen, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), full `agent-test`, `drift-check`, `chl`, `gep` (diff reviewed — empty, and *verified* empty rather than assumed: no error class moved, and `cogt` already had its `_SUBSYSTEM_SECTIONS` row, so the M1/M2 regression shape could not repeat here), `tb`.
-
-**Scale:** 2 source modules + 1 test module moved, 127 substitutions across 11 files plus the durations file. Same rewrite method as M1/M2 (ordered longest-first substitutions over `git ls-files`, `CHANGELOG.md` / `TODOS.md` / `wip/` / `docs/errors/` excluded, then a whole-tree `git grep` completion check asserting the only survivors are in those excluded files). ⚠ `.test_durations` is **not** an exclusion — M1 and M2 both rewrote it, and it carries test node ids that a test move invalidates.
-
-**One near-miss the completion sweep caught by construction:** `OpenAIImageURL` is a live local alias for the OpenAI SDK's `ImageURL` in four completions factories. A substitution keyed on `OpenAIImage` would have corrupted all four; the list keys on the full type names (`OpenAIImageLegacySizeType`, `OpenAIImageModerationType`, `OpenAIImageInputFidelityType`), so none matched. Verified after the fact — the four sites are untouched.
-
-**Decisions taken during implementation** — see [Decisions](#decisions) for D-F1-1 … D-F1-4.
-
-#### Review round — F1, done 2026-07-28, fixes applied
-
-`correctness-and-boot`: **no defects.** It reconstructed both pre-move files, applied only the documented renames, and diffed against the new ones — the **entire** functional delta is `moderation_literal`'s `omit` → `None`, everything else being docstrings. It then traced every consumer of that value and confirmed the branch is identical (`Omit` is not a `str`, so the old `isinstance` test and the new `is None` test agree on every input), verified all three `mocker.patch` targets followed the class, confirmed no orphan `.test_durations` entries, and recomputed the neutrality property independently — 43 modules in the mapping closure, zero `pipelex.providers`, zero `pipelex.config`, no deferred or dynamic import anywhere in it. It also confirmed boot is untouched: the moved modules are lookup tables, present in no manifest and no entry point.
-
-⚠ **Its one unreproduced observation has a mundane explanation, and it is reassuring rather than worrying.** It saw the closure subprocess fail exactly once, reporting **10** `pipelex.providers` modules, and could not reproduce it in 8 further full-suite runs or 15 standalone ones. Ten is the exact count [Measurements](#post-f1-measured-2026-07-28) records for the deliberate mutation used to prove the guard discriminates — so the reviewer observed that mutation in flight, in a shared worktree, and what it actually witnessed is the guard firing correctly on a genuinely coupled tree. Its suggested hardening (`-I` plus explicit `cwd=`/`env=`) is **not applied**: cwd on `sys.path[0]` is what makes the subprocess measure the *working tree* rather than an installed copy, and the sibling `test_runtime_layer_import_closure.py` is built the same way. Recorded rather than silently dismissed — if it ever appears with no concurrent editing, that reasoning is what to re-examine.
-
-`over-engineering`: **the move itself is clean and not over-engineered** — verified as a pure placement fix with no registry, no plugin slot, no dispatch layer and no shim, and the `omit` → `None` change *removes* machinery rather than adding it. The equivalence was confirmed independently rather than taken on trust (the old caller never put the sentinel in the dict either, and the worker reads the key's absence). Grants correctly re-pathed; `bc22ba934` verified a pure re-sort by identical line multiset.
-
-**Every defect was in the new guard test, and the headline one is this track's own recurring shape — a check that cannot fail.**
-
-- **`assert MAPPING_MODULE_PATHS` sat at the top of a test parametrized over that same list, so it was unreachable.** pytest never calls a body for an empty parameter set: it reports `SKIPPED [1] got empty parameter set` and exits 0. Verified directly with a throwaway repro against this venv rather than taken on the reviewer's word. The line therefore could not catch the one failure it named — a stale glob turning the check into a silent green skip — and **D-F1-4's written justification for the glob was false as a result**. The sibling assertion in the *non*-parametrized test is reachable and does the job for real, so the fix is a deletion, not an addition: the dead assert goes, the third copy of the same check inside `_CLOSURE_SCRIPT` goes with it (its only caller is already gated by the reachable one), and the surviving guard now carries a comment explaining why it cannot live in the parametrized sibling. Mutation-checked: with the glob pointed at a non-matching pattern the module reports **1 failed, 1 skipped** — loud, which is the whole point.
-- **Kept the glob, against the reviewer's preferred fix.** Replacing it with a two-item literal would retire all three vacuity checks at once, which is true and tempting. But the glob is the only thing that covers a third taxonomy family on the day it lands, and this invariant is invisible to every other gate in the repo (D-F1-4) — a new mapping module silently outside the check is a worse failure than one reachable assertion is a cost. One reachable guard, one line of cost.
-- **Duplicated closure machinery with `test_runtime_layer_import_closure.py`: judged, not drifted.** The reviewer is right that this branch's M1/M2 rounds were about killing near-duplicate guard mechanics, so it deserved a ruling rather than silence. Ruling: **keep them separate.** After the deletions above the shared surface is a ten-line script, a timeout constant and one `subprocess.run` — and the two guards must be able to diverge (the closure test's detector is parameterized by interpreter packages passed as argv and carries a dirty-control entry point; this one has a fixed prefix and no entry-point list). Extracting a helper would couple them to save less than it costs.
-- **Stale grant rationale fixed** — `input_fidelity_literal` still read *"Derives the OpenAI fidelity literal"* after the de-vendoring rename D-F1-2 motivated. Re-recorded through `make sgr` so the registry stays machine-written and sorted.
-- **Stale tense in this file fixed** — the re-sort was still described as pending future work inside the very range that landed it.
-
-**An overclaim I caught while verifying one of the reviewer's "cleared" items, and it is the M2 shape again.** My own docstring, changelog entry and `hub-layering.md` bullet all said the GPT Image family is "served by three different SDKs (OpenAI, Azure REST, the Pipelex gateway)". The shipped decks prove **two** — `openai.toml` and `azure_openai.toml` are the only ones declaring a `gpt_image_*` taxonomy. The gateway *worker* is genuinely written for these models (it routes through the same args factory and carries the OpenAI `/images/generations` → `/images/edits` split), but its catalog is fetched remotely, so no shipped config settles it. The two proven adapters already defeat "file it in the OpenAI adapter", so the argument never needed the third. Reworded in all three places to what the config proves. ⚠ The reviewer had marked this claim *checked and accurate*; a reviewer confirming a claim is not the same as the claim being verifiable from the tree.
-
-**One finding confirmed against the code and rejected:** the `"not supported by OpenAI image model '<name>'"` error strings. They name the *model the user chose*, which is an OpenAI model whichever SDK routes to it — Azure and the gateway serve OpenAI's models, they do not make them theirs. The module docstring's neutrality claim is about the *mapping*, not the model, so the two do not contradict. Rewriting them would churn several test `match=` patterns to make the messages less accurate.
-
-**Fixed alongside, in its own commit** — `subject_grants.toml` had stopped being sorted by key, which its own documentation calls an invariant (`docs/contribute/keyword-only-arguments.md:37`: *"machine-written and sorted by key, so diffs stay stable and merge conflicts resolve trivially"*). Measured 11 out-of-order pairs; F1 contributed 2 of them and **M1 and M2 the rest** — a bulk path rewrite re-paths a grant key without moving its block, and `check-keyword-only` does not gate order, so the invariant broke silently and stayed broken across three commits. Kept out of F1's diff as branch debt rather than F1 debt: it is `bc22ba934`, a pure reordering (304 insertions against 304 deletions, with the key set, every `param` and every `rationale` asserted unchanged before writing).
-
-#### Third review round — `/review`, done 2026-07-28
-
-Run against `origin/refactor/Modularity-3` (the F1-only diff), after the two agent rounds above. **No correctness defect.** The move is complete and the consumer set closes: enumerating every pre-move reference to the two classes and their six type aliases at the base yields exactly the sites F1 touched, with no survivor anywhere in the tree outside `CHANGELOG.md` / `TODOS.md` / `wip/`. The `omit` → `None` equivalence re-verified independently (`Omit`/`omit` now appear nowhere in `pipelex/`; the only reader of the `moderation` key is `openai_img_gen_worker.py:78`, which pops it). The neutrality property re-measured in a fresh interpreter: **0** `pipelex.providers` modules and **0** vendor-SDK roots in the mapping closure. Gates re-run green: `cko`, `agent-check` (ruff / pyright 0 / mypy 0 / cko / chl), `drift-check`, `tb`, full `agent-test`. Codex, given the same scoped diff adversarially, returned **no findings** and reproduced the closure measurement itself.
-
-Five items, none critical. Three fixed mechanically, two ruled by Louis:
-
-- **The corrected three-SDK claim survived in a fourth copy, and it was inside the very test that pins the property.** `test_img_gen_mapping_neutrality.py`'s header said *"GPT Image by the OpenAI, Azure REST and gateway workers"* — the exact wording `fd141d4ed` set out to retire from the docstring, the changelog and `hub-layering.md`. Same matched-set failure as `pipe_signature` in M3 and the four-not-two occurrences in M3's doc sweep: the sweep found the three copies someone had listed, not the copies that exist. Reworded to what the decks prove (re-verified: `openai.toml` and `azure_openai.toml` are still the only two declaring a `gpt_image*` taxonomy).
-- **Two subject-grant rationales describe an operand that is not the granted param.** `ImgGenGeminiMapping.img_gen_taxonomy` and `.optional_img_gen_taxonomy` grant `param = "inference_model"` but read *"Operates on the aspect-ratio taxonomy"* — copied from the seven siblings that really do take `taxonomy`. Pre-existing (identical at the base), but this round's own fix list already re-recorded `input_fidelity_literal` for exactly this defect and stopped at one. Re-recorded both through `make sgr`; sort invariant re-asserted over all keys.
-- **A comprehension variable shadowed the parameter interpolated two lines below it.** `img_gen_gpt_mapping.py:89` built its "supported aspect ratios" list with `for aspect_ratio in …` while `aspect_ratio` is the function's own parameter, used at line 91 in the error message. Correct only because comprehensions carry their own scope — and the sibling builder at line 120 already names it `supported_ratio`. Renamed to match. Pre-existing, moved unchanged.
-- **`.test_durations` carried 112 orphan entries and `test_parser.py`'s 54 tests had none — M1 debt, fixed here in its own commit.** The ground rules call `.test_durations` a non-exclusion precisely because a test move invalidates its node ids, but M1's rewrite re-pathed *directories* and missed *basename renames*: `test_interpreter.py` → `test_parser.py` (52 entries), `test_interpreter_preliminary_text.py` → `test_parser_preliminary_text.py`, plus the renderer moves into `pipe_machinery/rendering/`, `test_job_metadata_request_id.py` into `system/`, and `test_hub_class_registry.py` → `test_class_registry_scoping.py`. Nothing gated it: the file is generated, pytest-split silently treats an unknown node id as average duration, so the only symptom was CI shard imbalance. Reconciled against a full unfiltered `--collect-only` (`-m ""` — the marker filter in `addopts` hides ~312 items and would have "orphaned" every `e2e` entry), matching each dead id to a live one by its `Class::test` tail: **125 remapped, 0 ambiguous, 0 dropped.** The two surviving dead ids are `pipe_img_gen` parametrizations keyed on the generated model-set fixture, so they are profile-dependent rather than orphaned, and were left alone. ⚠ **This is a third instance of the same shape** (`subject_grants.toml` order, the matched triple, now durations): a *generated or bookkeeping* file that no gate validates, broken by a bulk rewrite, invisible until someone measures it.
-- **The test module that still named the vendor is renamed.** `test_img_gen_args_openai_sizes.py` / `TestImgGenArgsOpenAISizes` → `test_img_gen_args_gpt_sizes.py` / `TestImgGenArgsGptSizes`. It exercises `AspectRatioTaxonomy.GPT_IMAGE_2` / `GPT_IMAGE_LEGACY` and patches `pipelex.cogt.img_gen.img_gen_gpt_mapping.log`, so it was the last "OpenAI" that D-F1-2 should have taken. (`test_safety_openai_moderation_mapping` keeps its name — `SafetyCheckerTaxonomy.OPENAI_MODERATION` is a real enum member.) Its 13 durations entries were re-pathed in the same reconciliation.
-
-**One gap recorded, deliberately not closed** — see [Follow-ups from the review](#follow-ups-from-the-review): the neutrality guard is weaker than its comment claims in two ways. The AST check reads only the mapping modules' *own* import statements and the closure check counts only `pipelex.providers`, so a vendor SDK reached **transitively** through another `pipelex.cogt` module passes both. Unexercised today — measured **zero** vendor-SDK imports anywhere in `pipelex/` outside `providers/`, which is the stronger invariant and is itself unguarded. And `_MAPPING_DIR.glob("img_gen_*_mapping.py")` is non-recursive and name-keyed, so *"a third taxonomy family is covered the day it lands"* holds only for a family landing in that exact directory under that exact suffix. Both are cheap to close and neither is worth the machinery F1 exists to avoid; recorded so the claim is not mistaken for a proof.
-
----
-
-## Phase 5 — close out
-
-- [x] **One PR is open — [#1067](https://github.com/Pipelex/pipelex/pull/1067), based on `refactor/Hub-2` rather than `dev`.** [Gating](#gating) said no track may open against `dev` until #1064 lands, or the diff carries #1064's changes. Stacking on the base branch satisfies that without waiting: the diff is the modularity work only, and GitHub retargets the PR to `dev` automatically when #1064 merges. **Still verify the retarget happened** once #1064 lands — an auto-retarget is not a merge, and the base must read `dev` before this one goes in.
-- [ ] Write the **cross-repo sweep handoff** into `wip/refactoring/` — the sweep is release-gated and shared with several other tracks, each of which keeps its own consumer table in [`../hub/hub-split-tracker.md`](../hub/hub-split-tracker.md): the [hub split](../hub/hub-split-tracker.md#cross-repo-sweep), the [Phase 3 type moves](../hub/hub-split-tracker.md#cross-repo-impact-added-by-phase-3), the [Phase 4 `concept_provider=` signature break](../hub/hub-split-tracker.md#cross-repo-impact-added-by-phase-4), the [`interpreter_plugins` relocation](../hub/hub-split-tracker.md#cross-repo-impact-added-by-the-f1-remedy), and the [layer-placement third wave](../hub/hub-split-tracker.md#third-wave--the-layer-placement-track-refactorlayer-boundary). It must land as **one breaking wave**, not one per track. Known external hits **for the M1 module set**:
-
- **Re-measured 2026-07-27 across every repo in the workspace.** The previous table was materially incomplete — it named one repo; there are eight. It also called `pipelex-temporal` "private and unchecked" when it is checked out at the workspace root and carries the most hits of any consumer.
-
- ⚠ **This table is the M1 slice — it is not the sweep inventory.** The inventory is the union of it and the hub tracker's tables linked above. Repos appear there that appear nowhere below — the [layer-placement third wave](../hub/hub-split-tracker.md#third-wave--the-layer-placement-track-refactorlayer-boundary) alone adds `test-bed`, `pipelex-workshop`, `pipelex-demos`, `pipelex-demo-frostbeam`, `pipelex-demo-mistral` and `pipelex-demo-vibe`. Read a repo's absence from both columns below as *"not measured for this wave"*, never as *"clear"* — that misreading is what the hub tracker records as the way the first pass silently lost six real breaking sites.
-
- | repo | hits | what |
- | --- | --- | --- |
- | `pipelex-temporal` | **13** | `PipelexInterpreter` (class, 3 files) · `PipeAbstract` · `PipeFactory` · `PipelexInterpreterError` in a comment |
- | `pipelex-api` | 5 | `PipelexBundleBlueprint` · `PipeAbstract` · `PipelexBundleBlueprintValidationErrorData` |
- | `pipelex-transport` | 3 | `PipeAbstract` (`primitives/pipe_classification.py` + 2 tests) — **was missing from the table entirely** |
- | `mthds-starter-js` | 2 | `"PipelexInterpreterError"` — **wire string**, `src/lib/errors.ts:176` + test |
- | `pipelex-starter-js` | 2 | `"PipelexInterpreterError"` — **wire string**, `src/lib/errors.ts:257` + test |
- | `conformance` | 1 | `ALLOWED_SURFACE` pin — **handled at CHECKPOINT M1, not here** |
- | `vscode-pipelex` | 1 | `error_type: 'PipelexInterpreterError'` — **wire string** |
- | `playroom` | 1 | `message.includes("PipelexInterpreterError")` — **wire string** |
-
- **The four wire-string consumers are the dangerous ones**: they branch on the error class name as an `error_type` value, so the rename does not break their build — they silently fall through to a generic error branch. No Python grep or type checker finds them.
-
- Verified clean **for the M1 module set only** — this is not a clearance for the sweep: `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows`, `pipelex-worker`, `pipelex-starter-python`, `pipelex-relay`, `sandbox`, `pipelex-daytona-sandbox` (it imports `pipelex.plugins.contract` / `registrar`, which do not move). ⚠ The first three of those **do** carry hits in the other waves — `cocode` and `pipelex-cookbook` in the hub split and the layer-placement third wave, `pipelex-mistralai-workflows` in the hub split, Phase 3 and the third wave — so they must still be visited. **M2 and F1 contribute nothing to this sweep** — zero external consumers import `pipelex.plugins.<vendor>`, and zero import either img-gen mapping under any name (re-measured across every repo at F1 time; the only hit anywhere is the released `pipelex/` checkout itself). No kajson-registered class moves, so serialized payloads are untouched.
-
- **Partly executed in the field, re-measured 2026-08-01** (`for repo in $(ls -d */ | tr -d '/'); do grep -rln --include='*.py' -E 'pipe_run\.pipe_run_mode|pipeline\.pipeline_models|from pipelex\.hub import|pipelex\.graph\.graph_rendering' "$repo"; done`, skipping the `_*` worktrees). That pattern covers the **hub-split and layer-placement** paths only — the M1 renames above are a different set and are not measured by it. On those paths most consumers were already swept as they bumped: `pipelex-temporal`, `pipelex-api`, `pipelex-transport`, `pipelex-mistralai-workflows`, `pipelex-cookbook`, `cocode`, `test-bed`, `pipelex-workshop`, `pipelex-demos` and `pipelex-demo-frostbeam` all measure zero. **The only consumers still on removed paths are `pipelex-demo-mistral` and `pipelex-demo-vibe`, 10 files each** — and both pin `pipelex[...]>=0.35.0` *unbounded*, so they resolve to the current release and are broken on a fresh install right now, not at sweep time. They are also exactly the two repos that appear nowhere in the table above, which is the concrete cost of reading this slice as the inventory.
-
-- [ ] **Fix the workspace repo table first.** `pipelex-transport` and `pipelex-daytona-sandbox` are real consumer repos missing from the workspace-root `CLAUDE.md` table — which is the table every cross-repo sweep is built from, and the reason `pipelex-transport` was missed here. Add both (and audit for others) before the sweep runs.
-- [ ] Archive this tracker to `wip/refactoring/` when the track completes (repo convention — see how `wip/hub/hub-split-tracker.md` was handled).
-- [ ] Update the memory entry `project_modularity_refactors.md`.
-
----
-
-## Review fan-out protocol
-
-At every checkpoint, spawn the reviews **in parallel, in one message**, each as a **fresh sub-agent with no inherited context**. Hand each one *only* a pointer to the changes — never this plan, never the design doc, never the rationale, never your own conclusions. A reviewer that has read the justification cannot independently find the flaw in it.
-
-Prompt template (fill the bracketed parts, change nothing else):
-
-> Run the `/code-review` skill on the following changes in the repo at `/Users/lchoquel/repos/Pipelex/_hub`:
-> `[git diff <base>..<sha>` — or the list of unstaged files]
->
-> Focus dimension: **[dimension]**.
->
-> We want clean, solid software — not over-engineering. Report concrete defects with file:line, and say plainly if you find none. Do not propose speculative features or abstractions.
-
-Dimensions to draw from:
-
-| dimension | what the reviewer is asked to hunt |
-| --- | --- |
-| `correctness-and-imports` | broken/circular imports, a moved symbol whose importers were missed, a rewrite that hit the wrong module (`plugins.secrets` vs `secrets_provider_registry`), test files left behind their source |
-| `correctness-and-boot` | behavior change hiding in a mechanical move; boot-sequence registration correct and complete |
-| `boundary-and-naming` | does the new package boundary actually hold, or did the move just relabel the problem? are the names right for what is inside them? |
-| `over-engineering` | anything introduced that is not load-bearing: speculative abstraction, indirection with one caller, a guard entry that guards nothing, machinery kept alive after its reason expired |
-| `test-and-docs-sync` | guard config / closure-test predicate / design-doc snippet in agreement; docs describing the old tree; a check that now passes vacuously |
-
-**Reading the verdicts:** treat a finding as a real defect only after you confirm it against the code. Reviewers with no context will sometimes flag an intentional ruling from the [Decisions](#decisions) table as a bug — that is expected and is not a reason to reverse the ruling; note it and move on. Design tradeoffs that are not silent bugs get captured as deferred follow-ups in `wip/refactoring/`, not reflexively fixed.
-
----
-
-## Decisions
-
-Inherited from the design doc (already ruled — do not re-litigate):
-
-| id | ruling |
-| --- | --- |
-| **D-M1-1** | Pipe manifest → `pipelex/pipe_machinery/registry_models.py` as `PipeRegistryModels`; M3 creates the package, M1 fills it |
-| **D-M1-3** | `core/interpreter/` + `core/bundles/` → `pipelex/mthds_parsing/`; `PipelexInterpreter` → `MthdsParser` |
-| **D-M2-1** | Vendors → `pipelex/providers/`, flat, no capability nesting |
-
-Ruled during the **2026-07-27 review**:
-
-| id | ruling | why |
-| --- | --- | --- |
-| **D-M1-2** | ~~`pipe_blueprint.py` is runtime and stays in `core/`~~ → **REVERSED. It is interpreter-layer and moves**, along with `validation.py`, `template_guard_lint.py` and `handle_pipe_errors.py` | The measurement snippet counts **outbound** edges, which answers "is X a leaf?" not "which layer owns X?". The layer question is **inbound**: zero declared runtime-layer modules import any of these four. Runtime does not know about pipes |
-| **D-M1-4** | **Rename** `PipelexInterpreterError` → `MthdsParserError`, add the `redirect_maps` entry, and carry **five** repos into the sweep | The premise "no external consumer imports `PipelexInterpreter`" was false; four TS repos consume it as an `error_type` **wire string**, which the redirect does not help |
-| **D-M1-5** | **Delete** `INTERPRETER_CORE` / `INTERPRETER_CORE_EXCLUDED` and their `is_interpreter` branches | Correct *because* D-M1-2 was reversed. Under the original ruling this would have silently relaxed the one entry `hub-layering.md:220` calls load-bearing |
-| **D-M1-6** | **Add** `"pipe_signature"` to `INTERPRETER_PACKAGES` | Verified against all five runtime entry points: zero `pipe_signature` modules loaded. Safe, no pre-existing leak, and independent of the moves |
-| **D-M2-2** | The four `cogt` config imports: accepted + documented (unchanged). The factory imports: **two**, not three, fixed by a **neutral `cogt/img_gen/` mapping module** — **no registry** | VertexAI is being removed so its edge self-resolves. The registry cannot dispatch these: `make_args_for_model` takes no sdk, dispatch is by `AspectRatioTaxonomy`, and gateway is one SDK spanning both taxonomies. A registry slot would also force a plugin-API bump for two import sites |
-| **D-M1-7** | **M1 stacks on M3** (PR → M3, retargeted to `dev` on merge). M2 lands after M1 and re-acks drift post-rebase | The plan asserted both "M3 → M1" and "each track branches from #1064 against `dev`"; M1 cannot be both. M1/M2 share three files, so they are not operationally parallel |
-| **D-M2-3** | **M2 is not release-gated** and comes out of the sweep table | Measured: zero external consumers import `pipelex.plugins.<vendor>` |
-| **D-M1-8** | **`PipelexBundleBlueprintValidationErrorData` moved to `pipelex.core.exceptions`**, not into `mthds_parsing/` with the parser that raises it | Ruled during M1a under the authority M1c's plan granted ("if the closure test *does* fail on it, move the data class to a runtime-layer home instead"). It does fail: `core.memory.working_memory_factory` reaches it, and the closure test's `INTERPRETER_CORE_EXCLUDED` existed for exactly that. `core/exceptions.py` already holds the two sibling structured error-data models keyed on the same `PipeValidationErrorType`. Moving the leaf is what let the exclusion be deleted outright rather than carried forward |
-| **D-M2-4** | **M2 is stacked on M1 on one branch**, not a parallel branch off #1064 rebased afterwards | The plan's own [Gating](#gating) already prescribed the landing order M3 → M1 → M2 and warned that the three shared files make them non-parallel. Stacking satisfies the order, removes the conflict, and removes the mandatory post-rebase drift re-ack — the ack recorded at CHECKPOINT M2 is against the final tree rather than a tree that will move |
-| **D-R-1** | **No third layer** between runtime and interpreter | A layer encodes a forbidden arrow; there is only one (`runtime_hub ↛ interpreter_hub`). The shared kernel a third layer would hold already exists as `core/`'s value model, which both layers use. The pipe vocabulary fails the entry test — only the interpreter needs it |
-| **D-F1-1** | **Two mapping modules, not one.** `cogt/img_gen/img_gen_gemini_mapping.py` + `cogt/img_gen/img_gen_gpt_mapping.py` | The plan said "a neutral `cogt/img_gen/` mapping module", singular. The two taxonomy families share **zero** code, come to ~500 lines together, and cover disjoint `AspectRatioTaxonomy` members; the repo files one topic per module, and the existing tests were already split per family. Named on the package's own `img_gen_*` prefix convention, with classes `ImgGen<Family>Mapping` to match `ImgGenArgsFactory` / `ImgGenParamSupport` |
-| **D-F1-2** | **Rename the classes and the vendor-suffixed methods**, rather than carrying `GoogleImgGenFactory` / `OpenAIImgGenFactory` into `cogt/` | Two things were wrong in the new home, and both are the defect this track keeps finding — a name that describes where the code used to live. (a) The **vendor** is not what the mapping is keyed by: dispatch is by model *family*, and the gateway resolves Gemini geometry through a Portkey SDK, so "Google" names a party that is not always involved. (b) "Factory" contradicts the repo's own convention (`make_from_*`); these are lookup tables and validators. Renames measured in-tree only: **zero** consumers in any sibling repo |
-| **D-F1-3** | **`moderation_literal` returns `None` instead of the OpenAI `omit` sentinel** | Load-bearing for the move, not a drive-by simplification: `Omit`/`omit` come from `from openai import …`, so keeping the sentinel would have put a hard vendor-SDK import in the neutral layer — exactly what F1 exists to remove. Verified equivalent rather than assumed: the sole caller already collapsed the non-`str` case to "emit no key" (`img_gen_args_factory.make_args_from_safety_checker`), and `openai_img_gen_worker.py:78` only ever pops a `str`. The emitted API arguments are identical on every path |
-| **D-F1-4** | **Add a neutrality test** (`tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py`) | Nothing in the repo can catch a regression here. `pipelex.cogt` and `pipelex.providers` are **both** runtime-layer, so the hub-layering guard and the import-closure test are blind to an edge between them *by construction* — the property F1 buys would otherwise be unguarded from the moment it landed, which is the shape of the M2 finding Codex #5 caught. Two complementary checks because the coupling has two routes back: an AST read of the modules' own imports (catches a fresh `from openai import omit`) and a subprocess closure measurement (catches a `pipelex.cogt.*` import that drags an adapter in behind it). The module list is globbed from disk so a third family is covered the day it lands. ⚠ **The first version guarded that glob in the wrong place** — see the [F1 review round](#review-round--f1-done-2026-07-28-fixes-applied) |
-
----
-
-## Measurements
-
-Baseline, measured **2026-07-27** on `bc30149c7` (venv-synced, subprocess per module — see the design doc's snippet).
-
-Core modules loading > 0 interpreter modules (`interp_mods`, `pulls interpreter_hub`):
-
-| module | interp_mods | hub | moved by |
-| --- | --- | --- | --- |
-| `core.registry_models` | 97 | yes | M3 |
-| `core.pipes.pipe_factory` | 51 | yes | M1b |
-| `core.pipes.rendering.input_renderer` | 51 | yes | M1b |
-| `core.pipes.rendering.output_renderer` | 51 | yes | M1b |
-| `core.pipes.pipe_abstract` | 33 | no | M1b |
-| `core.bundles.pipe_sorter` | 30 | no | M1a |
-| `core.bundles.pipelex_bundle_blueprint` | 30 | no | M1a |
-| `core.interpreter.bundle_elaborator` | 30 | no | M1a |
-| `core.interpreter.interpreter` | 30 | no | M1a |
-
-Measured **0** outbound and therefore worth restating: `core.pipes.pipe_blueprint` (**moves anyway — D-M1-2 reversed**, see the inbound test below), and the four leaf modules that move for cohesion — `core.bundles.exceptions`, `core.interpreter.exceptions`, `core.interpreter.helpers`, `core.interpreter.validation_error_categorizer`.
-
-### The inbound test — added 2026-07-27, and it is the one that decides layer
-
-The classification snippet above counts **outbound** edges. That tells you whether a module is a *leaf*, not which layer owns it. A module can import nothing and still be exclusively interpreter business. The layer question is **who needs this** — measured against the *declared* runtime-layer packages:
-
-```bash
-RUNTIME='pipelex/(cogt|plugins|reporting|system|tools|runtime_hub|core/(concepts|domains|memory|stuffs)|core/pipes/(inputs|stuff_spec))'
-for m in pipe_blueprint pipe_output validation variable_multiplicity template_guard_lint handle_pipe_errors exceptions; do
- n=$(grep -rln "core\.pipes\.$m\b" pipelex/ --include="*.py" | grep -cE "$RUNTIME")
- printf "core.pipes.%-24s %s\n" "$m" "$n"
-done
-```
-
-Result on `89ae4950b`: `pipe_output` 4 · `variable_multiplicity` 5 · `exceptions` 1 → **runtime, stay**. `pipe_blueprint` 0 · `validation` 0 · `template_guard_lint` 0 · `handle_pipe_errors` 0 → **interpreter, move**.
-
-The control matters: `pipe_output` and `variable_multiplicity` score non-zero, so the test discriminates rather than flagging everything. ⚠ It measures against *declared* runtime packages; `pipeline/` and `pipe_run/` are undeclared straddlers, so re-verify any move against the closure test.
-
-Other baselines: `cogt → specific vendor` = 7 statements (4 config, 2 img-gen factory, 1 inline `vertexai_factory`). Runtime entry-point closures (`runtime_hub`, `plugins.builtins`, `content_generator`) currently pull in only `pipelex.pipeline` + `pipeline.pipeline_models` from the straddler zone.
-
-### Post-M3, measured 2026-07-27
-
-Baseline above re-taken on `95a1e9bf7` before any edit: **identical** to the table — same nine modules, same counts. No drift since `bc30149c7`.
-
-After M3, with `"pipe_machinery"` added to the snippet's `I` set:
-
-| module | interp_mods | hub | moved by |
-| --- | --- | --- | --- |
-| ~~`core.registry_models`~~ | ~~97~~ → **0** | **0** | ✅ M3, done |
-| `core.pipes.pipe_factory` | 51 | yes | M1b |
-| `core.pipes.rendering.input_renderer` | 51 | yes | M1b |
-| `core.pipes.rendering.output_renderer` | 51 | yes | M1b |
-| `core.pipes.pipe_abstract` | 33 | no | M1b |
-| `core.bundles.pipe_sorter` | 30 | no | M1a |
-| `core.bundles.pipelex_bundle_blueprint` | 30 | no | M1a |
-| `core.interpreter.bundle_elaborator` | 30 | no | M1a |
-| `core.interpreter.interpreter` | 30 | no | M1a |
-
-Nine → eight. Every other module's count is **unchanged**, which is the expected shape: `registry_models` had exactly one consumer and was on no other module's import path.
-
-Inverted `core → pipe_*` import statements: **43 → 19** — `pipelex_bundle_blueprint` 12 · `bundle_elaborator` 4 · `output_renderer` 2 · `pipe_abstract` 1. All 19 belong to modules M1 hoists, so M1's target of **0** needs no further work in `core/` beyond the moves already planned.
-
-### Post-M1, measured 2026-07-27 on `10080cf26`
-
-Classification snippet with `I` = the nine interpreter packages: **zero** `pipelex.core.*` modules report a non-zero `interp_mods` or `hub`. The table is empty — M1's headline criterion, reached in two steps (M1a took it 8 → 4 by hoisting the parser, M1b took it 4 → 0 by hoisting the Pipe machinery).
-
-Inverted `core → pipe_*` import statements: **43 → 19 (M3) → 3 (M1a) → 0**. The 3 that survived M1a were `pipe_abstract`'s one `pipe_signature.exceptions` import and `output_renderer`'s two deferred `pipe_controllers` imports under `TYPE_CHECKING` — both modules M1b moved, so no further work in `core/` was needed.
-
-Inbound test, re-derived at move time rather than trusted: everything that moved scored **0** declared runtime-layer importers (`pipe_blueprint`, `validation`, `template_guard_lint`, `handle_pipe_errors`, `pipe_abstract`, `pipe_factory`, `rendering`); everything that stayed scored non-zero (`pipe_output` 4, `variable_multiplicity` 5, `exceptions` 1). The control still discriminates, which is what makes the verdict meaningful.
-
-`core/pipes/` final contents: `inputs/`, `stuff_spec/`, `exceptions.py`, `pipe_output.py`, `variable_multiplicity.py` — exactly the runtime half the plan predicted.
-
-### Post-M2, measured 2026-07-28
-
-The move: **17** vendor packages + `builtins.py` from `pipelex/plugins/` to `pipelex/providers/`. **136** files rewritten, **1364** substitutions, of which **191** string literals (predicted 189) and **145** `subject_grants.toml` path keys (12 grants stay, all on mechanism modules).
-
-| | before | after |
-| --- | --- | --- |
-| directories under `pipelex/plugins/` | 17 vendors + mechanism | **0 vendors** — mechanism modules only |
-| `RUNTIME_LAYER_PACKAGES` entries | 7 | **8** (`pipelex.providers` added) |
-| source files outside `providers/` naming a specific vendor | 3 | **3** (unchanged — the documented `cogt` edges) |
-| `pipelex/plugins/` modules naming a vendor | 1 (`builtins.py`) | **0** |
-
-`INTERPRETER_PACKAGES` is **unchanged** — M2 adds a runtime-layer package, so the matched triple (guard tuple / closure predicate / hub-layering snippet / design-doc snippet) is undisturbed, and the design doc needed no edit. Verified by script rather than assumed: the closure predicate and the doc snippet still name the same set.
-
-### Post-F1, measured 2026-07-28
-
-| | before | after |
-| --- | --- | --- |
-| `cogt → specific vendor` import statements | 7 | **5** — the four `config_cogt.py` config classes (documented, D-M2-2) + the deferred `VertexAIFactory` |
-| source files outside `providers/` naming a vendor module | 3 | **2** (`cogt/config_cogt.py`, `cogt/model_backends/backend_factory.py`) |
-| third-party packages imported by the img-gen mapping modules | 1 (`openai`) | **0** |
-| `pipelex.providers.*` modules in the mapping modules' import closure | — | **0**, measured in a fresh interpreter |
-
-⚠ The vendor-segment character class matters here too (the M2 trap): `[a-z0-9_]+`, not `[a-z_]*`. The measurement above is the whole verdict for F1 — the rewrite itself was keyed on literal module paths and was never at risk.
-
-The mutation that proves the closure check discriminates: adding one `pipelex.providers.google.google_factory` import to a mapping module makes it report **10** provider modules, not one — `google_factory` reaches `pipelex.config`, which reaches `config_cogt`, which names the four vendor configs. The documented `cogt → config` inversion is therefore also the shortest path back to full vendor coupling, which is worth knowing before anyone calls it harmless.
-
-*(Append post-phase re-measurements here as each checkpoint clears.)*
-
----
-
-## Review findings
-
-`/plan-eng-review`, 2026-07-27, against `89ae4950b`. Eight issues, all ruled. Recorded so the reasoning survives the checkpoint.
-
-| # | finding | ruling |
-| --- | --- | --- |
-| 1 | "No external consumer imports `PipelexInterpreter`" was false — 5 repos, and 4 consume it as an `error_type` **wire string** that renaming breaks silently | Rename; carry all 5 into the sweep (D-M1-4) |
-| 2 | `conformance/` `ALLOWED_SURFACE` + `docs/specs/` pin `core.pipes.pipe_abstract`; unmentioned by the plan, and `_hub`'s suite cannot catch it | Hard item at CHECKPOINT M1, not sweep work |
-| 3 | D-M1-2 classified by **outbound** imports; the inbound test says `pipe_blueprint` + 3 more are interpreter-only | D-M1-2 reversed; all four move; this makes D-M1-5's deletion honest and saves a doc rewrite |
-| 4 | M2 has **zero** external blast radius; the "one wave" argument does not cover it | M2 de-gated from the sweep (D-M2-3) |
-| 5 | The `hub-layering-convention` drift contract fires in all 3 tracks; only M1c had an ack | Ack steps added to M3 and M2 |
-| 6 | The guard test needs a full rewrite, not a one-line fix — and 4 assertions go **vacuously green** between M1b and M1c | Rewrite wholesale in the collapse commit |
-| 7 | 189 (M2) + 15 (M1) **string-literal** module references that no import rewrite or type checker sees | Added to ground rule 5, budgeted per track |
-| 8 | F1's "dispatch through `inference_backend_registry`" does not typecheck — it is `MakeWorkerFn`-only | F1 re-scoped to 2 imports + a new registry slot (D-M2-2) |
-
-Also settled: **no third layer** is needed (D-R-1).
-
-### Outside voice — Codex, same day, 15 further findings
-
-Run in-repo at `reasoning_effort=high`, told what the review above had already found. Verdict: *"not implementation-ready."* Eight claims were verified against the tree; all held. All 15 are folded in.
-
-| # | finding | where it landed |
-| --- | --- | --- |
-| **5** | **The M2 guard claim was backwards.** The plan said omitting `"pipelex.providers"` is caught by the transitive rule. It cannot be — `hub_layering_guard.py:677` filters through `is_runtime_layer`, so an **undeclared** package is excluded from the rule's domain. The plan named its riskiest step and pointed at a safety net that does not exist | M2 — explicit guard test |
-| **14/15** | F1 had no workable dispatch key (`make_args_for_model` takes no sdk; dispatch is by taxonomy; gateway is one SDK spanning both) and implied an unplanned plugin-API bump | **F1 rewritten** — neutral mapping module, no registry |
-| **3** | PR topology was self-contradictory (M3→M1 *and* each track based on #1064) | Gating — M1 stacks on M3 |
-| **1** | `mthds_parsing` unguarded between M1a and M1c | Predicate updated in **M1a** |
-| **2** | `mthds_parsing/` and `providers/` had no `__init__.py` step; ruff `INP001` fails the commit | Both tracks |
-| **4** | M1 and M2 are architecturally but **not operationally** independent; a rebase invalidates the drift ack | Gating — landing order + re-ack |
-| **6** | `DIRTY_ENTRY_POINT` proves *a* token matches, not that each new one is spelled right | M1c — leaf probe per package |
-| **7** | The M3 regression test was too weak — one pipe + one stuff misses a dropped list or model | M3 — full-set + disjointness |
-| **8** | `subject_grants.toml:2615` embeds `PipelexInterpreter.make_pipelex_bundle_blueprint`; re-pathing alone leaves it stale | M1a |
-| **9/10** | Hand-written importer and test-move inventories were materially incomplete (26 importer files, not ~11) | M1a / M1b — assert-zero-old-paths |
-| **11** | The design doc still contradicted this tracker | Superseded banner added to the design doc |
-| **12** | M2's "vendor imports nothing but mechanism = 0" is false by construction — cross-vendor edges are deliberately kept | Metric restated |
-| **13** | Stale architectural prose in *source* (`contract.py:33-35`, `interpreter_plugins/builtins.py:3-8`) | M2 sweep |
-
-Clean on two axes it checked independently: pydantic/kajson (the discriminated union keys on the stable `type` field and no registered concrete pipe class moves) and entry-point metadata / relative imports.
-
-## Follow-ups from the review
-
-Not in this wave. Captured with their evidence so they are not re-derived.
-
-> **Assessed and written up as an implementation handoff: [`modularity-review-follow-ups.md`](modularity-review-follow-ups.md).** Each of the three open items below was re-verified against the tree on 2026-07-28 at `7ddb77f87` and carries a stable id there — **FU-1**, **FU-2**, **FU-3** — plus a concrete recommendation, reproduction commands and sizing. Cite the ids. The bullets below remain the record of *what was noticed*; the handoff is the record of *what to do*. Target branch: `refactor/Hub-2`, after #1067 merges into it.
-
-- [ ] **FU-1 — Decouple `error_type` from the Python class name.** Give each `PipelexError` an explicit stable wire identifier instead of deriving `error_type` and the docs `type_uri` from the class name. Every error-class rename is currently a silent break for any consumer switching on the string, and nothing in the repo flags it. Evidence: `mthds-starter-js/src/lib/errors.ts:176`, `pipelex-starter-js/src/lib/errors.ts:257`, `vscode-pipelex/.../cliValidationBackend.test.ts:99`, `playroom/src/app/api/graph/route.ts:119` — **all four re-confirmed live 2026-07-28, still branching on the retired `PipelexInterpreterError`**. Would also remove the need for the `redirect_maps` workaround. Independent of all three tracks; touches the error model and the agent-CLI JSON envelope, so it needs a matching spec/conformance change. → The assessment **splits this in two**: a golden identity snapshot closes the "nothing flags it" half cheaply and with no spec change, and is what should land before the sweep; the `_declared_error_type` refactor is deferred, since the no-backward-compat rule means it cannot save the four consumers anyway. Note `title` / `type_uri` already have the `_declared_*` hatch — `error_type`, the only one machines branch on, is the one that lacks it. See [FU-1](modularity-review-follow-ups.md#fu-1--nothing-flags-an-error-class-rename-and-it-is-a-wire-break).
-- [ ] **FU-2 — Close the two holes in the img-gen neutrality guard, or downgrade its comment to what it proves.** Raised by the [third F1 review round](#third-review-round--review-done-2026-07-28); recorded rather than fixed because both are cheap and neither is worth machinery on a track whose whole argument was "placement, not indirection". (a) **Transitive vendor SDKs are unguarded.** `_import_roots` reads only the mapping modules' own import statements and `_CLOSURE_SCRIPT` counts only `pipelex.providers`, so an `openai` import reached through some other `pipelex.cogt` module passes both checks. ~~Measured clean today — **zero** vendor-SDK imports anywhere in `pipelex/` outside `providers/` — and *that* is the stronger invariant, unguarded and worth a repo-wide test of its own rather than a denylist bolted onto this one.~~ (b) **The glob under-claims its own coverage.** `_MAPPING_DIR.glob("img_gen_*_mapping.py")` is non-recursive and suffix-keyed, so "a third taxonomy family is covered the day it lands" holds only for a family landing in that exact directory under that exact name. Either bind the convention with a test or soften the comment.
-
- ⚠ **Correction, 2026-07-28 — the struck sentence is false, and it was the stated justification for a test that would be red on day one.** Struck rather than silently rewritten, because the defect is instructive: five modules outside `providers/` do import a vendor SDK — `tools/pdf/pypdfium2_renderer.py` (module-level), `tools/storage/s3_storage_provider.py`, `tools/storage/gcp_storage_provider.py`, `tracing/dynamodb_event_log.py`, `reporting/reporting_manager.py`. All legitimate: they are *infrastructure* SDKs (pypdfium2, boto3/botocore, google.cloud), which is exactly the shim-vs-implementation split M2's own review recorded for `providers/storage/`. The invariant that **is** true and worth pinning is narrower — `pipelex/cogt/**` imports zero vendor SDKs, and `cogt → pipelex.providers` is exactly the documented five statements. [FU-2](modularity-review-follow-ups.md#fu-2--the-img-gen-neutrality-guard-is-weaker-than-its-comment-and-its-recorded-remedy-is-wrong) carries the scan that produced this and the corrected remedy. **This is the fourth time on this branch that a check's justification, rather than the check, was the defect** — and the first where the bad justification was written into a *deferred* item, where nothing would have re-tested it before someone acted on it.
-- [ ] **FU-3 — Gate the bookkeeping files a bulk rewrite silently breaks.** ⚠ Re-measured 2026-07-28: **both artifacts are clean today** (`subject_grants.toml` 0 out-of-order pairs; `.test_durations` 0 dead file paths, 2 node-id orphans that are the known profile-dependent `pipe_img_gen` parametrizations) — so this is about the *missing gate*, not a live defect. [FU-3](modularity-review-follow-ups.md#fu-3--the-bookkeeping-files-a-bulk-rewrite-breaks-are-still-ungated) recommends doing the sort check inside the existing `keyword_only_guard.py` and gating durations on the **file path** rather than the node id — a path check is unambiguous, needs no collection run, and needs no tolerance policy for the two benign orphans. Three instances on this branch, each found by hand well after the fact: `subject_grants.toml` losing its sort (fixed in `bc22ba934`), the matched triple disagreeing on `pipe_signature` (fixed in M3), and `.test_durations` carrying 112 orphan node ids across three commits (fixed in the third F1 round). All three share a shape — a generated or bookkeeping artifact that no gate validates, invalidated by a bulk path rewrite, invisible until someone measures it. A cheap `make check` addition covers two of them: assert `subject_grants.toml` keys are sorted, and assert every `.test_durations` node id resolves against a full unfiltered collection. ⚠ The collection must run with `-m ""` — the marker filter in `addopts` hides ~312 items, so a naive check would report every `e2e` entry as an orphan.
-- [x] **Guard against vacuously-green string-predicate tests.** ✅ **Done in M1c** — see T10. Assert that every module qname referenced as a string literal in the guard and closure tests resolves to a real module. `is_runtime_layer` never checks existence, so a moved module silently converts assertions into tests of nonexistent paths — the M1b→M1c window is the worked example. Best done **after M1**, when the guard config is in its final shape.
-
-## Cold-start brief
-
-**Read this first in a new session.** Keep it true at every checkpoint.
-
-- **Where — updated 2026-08-01: everything below shipped; start a fresh branch off `dev`.** The code is on `dev` and only [Phase 5](#phase-5--close-out) is left. The historical record: the work was built in worktree `_hub/` on one branch `refactor/Modularity-3` (`6e74c6f26`, carrying M3 + M1 + M2 + F1), based on `refactor/Hub-2` (PR #1064), with F1 developed on `refactor/Modularity-4` and merged in through PR #1065 — the separate-PR topology [Gating](#gating) prescribed, honoured and closed. All of it reached `dev` inside the squash `8c0b99b3a` (#1064), so **PR #1067 has no commit of its own on `dev`**; the worktree and all three branches are deleted. Related memory: `project_modularity_refactors.md`, `project_hub_split_refactor.md`.
-- **What:** three refactors continuing the hub split — M3 (split the boot manifest, seed `pipe_machinery/`), M1 (hoist core's interpreter half into `mthds_parsing/` + `pipe_machinery/`, collapse the guard declaration), M2 (split `plugins/` into mechanism + `providers/`), then follow-up F1 (the two img-gen factory imports, fixed by moving the mappings inward — **no registry**, see D-M2-2).
-- **Why now:** **M3 and M1** break external imports, and the repo already owes a release-gated cross-repo sweep for the hub split — landing them first means consumers absorb one breaking wave instead of several. **M2 and F1 do not** (measured zero external consumers for both) and can land on their own schedule.
-- **State:** **M3, M1, M2 and F1 all done and committed on one branch — sitting at CHECKPOINT F1.** M1 is three commits: `0f0309b8f` (M1a, parser → `mthds_parsing/`), `c9c45c475` (M1b, Pipe machinery → `pipe_machinery/`), `10080cf26` (M1c, declaration collapse + guards + docs), plus `7beda698f` for the review fixes. M2 is one commit on top (D-M2-4 — stacked, not parallel) plus `fa6f4fae9` for its review fixes, then F1. All gates green at every checkpoint, all exit criteria met. **Every track's review round is done and its fixes committed** — the moves cleared every time, every defect was docs/fixture/test-quality drift, and three placement items are deferred to `wip/refactoring/deferred-placement-follow-ups.md`. **F1 has had three rounds** (`correctness-and-boot`, `over-engineering`, then `/review` against the F1-only diff): no correctness defect in any of them, and the third round's fixes are the last of it. Only Phase 5 remains.
-- **Blocking:** ~~PR #1064 must merge before #1067 can retarget to `dev` and go in.~~ **Nothing — #1064 merged, and v0.41.0 / v0.42.0 have shipped, so the release gate on the Phase 5 sweep is open too.** **No open decisions.**
-- **✅ The two cross-repo edits survived and are committed** — `conformance/tests/pipelex_transport/test_data.py` (`ALLOWED_SURFACE` now reads `pipelex.pipe_machinery.pipe_abstract`) and workspace-root `docs/specs/pipelex-transport-boundary.md`, both verified clean in their own repos on 2026-08-01. They were flagged here as uncommitted and at risk; they are neither. Nothing to recover before Phase 5.
-- **What M3 actually changed:** no module moved paths and no class was renamed — only the six pipe lists moved from `CoreRegistryModels` to `pipelex.pipe_machinery.registry_models.PipeRegistryModels`. M3 contributes **nothing** to the cross-repo sweep. **M1 is where the sweep debt is incurred**, and it is bigger than the module moves: `PipelexInterpreterError` → `MthdsParserError` is the `error_type` **wire string** four TypeScript consumers branch on, and the docs redirect does nothing for them.
-- **What M2 confirmed, and the one thing it adds:** every M1 lesson below fired again. The test inventory in the plan was incomplete a third time (six flat modules needed per-module classification, and one — `test_inference_backend_coverage.py` — reads as a vendor test by name while being a mechanism test by subject). The generated-output lesson paid off directly: `_SUBSYSTEM_SECTIONS` was missing a `providers` row, the identical defect M1 hit with `mthds_parsing`, and `make gep` exits 0 either way. **The new one: a grep character class is a measurement bug.** `pypdfium2` has a digit, so `[a-z_]*` silently skips it — the rewrite was safe (literal vendor names) but the *verification* under-counted, which is worse, because the verification is what licenses "done". Use `[a-z0-9_]+`.
-- **What M1 learned that M2 will hit again:**
- 1. **Test inventories written in advance are wrong.** Both of M1's were materially incomplete. Derive the move list from each test's actual subject, at move time.
- 2. **A `Path(__file__).parents[N]` in a moved test is a silent bug** — nothing static sees a parent count, and it fails only under the full suite. Sweep for it after every test move.
- 3. **Doc enumerations are where `hub-layering.md` rots** — and the ones that go stale are rarely in the paragraph your diff touches. M1c found two (`The layer rule`, the must-not-name list) well away from the change. Grep for a *sibling* package name, not for the thing you moved.
- 4. **Moving the leaf beats excluding it.** M1a's straddler decision is the general lesson: an exclusion records a placement problem, a move removes it. `pipeline` / `pipe_run` are the two left.
- 5. `make cleanderived` deletes a gitignored generated test fixture that only the test targets rebuild, so pyright fails on unrelated errors until you regenerate it (command in [Phase 0](#phase-0--baseline)).
-- **The four things that will bite you:** (1) re-path `subject_grants.toml` *before* `make agent-check`, or `fix-keyword-only` silently rewrites your subjects — note that a whole-tree textual rewrite re-paths them for free, including qualnames embedded in the key, which is how M1a's `PipelexInterpreter.make_pipelex_bundle_blueprint` fixed itself; (2) `pipelex.plugins.secrets` is a vendor dir but `pipelex.plugins.secrets_provider_registry` is a mechanism module — no prefix `sed`; (3) the guard tuple, the closure-test predicate, the hub-layering snippet and the design-doc snippet are a matched set — **the first three are now mechanically bound by tests** (M1c), the design doc's is not; (4) **string literals are module references too** — 189 in M2, invisible to every import tool.
-- **What the rewrite method looked like, since M2 is the same shape at larger scale:** one Python script over `git ls-files`, an ordered longest-first substitution list (dotted paths, then filesystem paths, then test paths, then the class rename), excluding `CHANGELOG.md` / `TODOS.md` / `wip/` / `docs/errors/` — history and generated pages must not be rewritten. Then `grep` the whole tree for the old paths and assert the only survivors are in those excluded files. That completion check is what makes "did I get them all?" answerable.
-- **The measurement trap that already caught this plan once:** the classification snippet counts *outbound* imports. It tells you whether a module is a leaf, **not** which layer owns it. Use the [inbound test](#the-inbound-test--added-2026-07-27-and-it-is-the-one-that-decides-layer) for layer decisions.
-- **What F1 adds, and it generalizes past this track:** a placement fix *inside one layer* has no gate. Both `pipelex.cogt` and `pipelex.providers` are runtime-layer, so the hub guard and the closure test cannot see an edge between them by construction — every `cogt → vendor` inversion on this page is invisible to both. Whenever you fix one, the invariant you just bought is unguarded from that moment on unless you write the test yourself (D-F1-4). The same is true of the four `config_cogt` edges that stay, which is why they are documented rather than merely tolerated.
-
----
-
-## Implementation Tasks
-
-Synthesized from the review's findings. Each derives from a specific finding above.
-
-- [x] **T1 (P1, human: ~3h / CC: ~20min)** — M3 — Add the regression test pinning pipe + stuff classes into the class registry after boot
- - Surfaced by: Test review — M3 splits `register_classes`; nothing asserts registry contents; failure is silent at boot
- - Files: ~~`tests/unit/pipelex/test_hub_lifecycle.py`~~ → **new `tests/unit/pipelex/test_registry_models_split.py`** (one TestClass per module is a repo rule), `pipelex/pipelex.py`
- - Verify: `make tb`, then drop one `register_classes` line and confirm the test goes red — ✅ done, and the stronger mutation too (drop one model from one list)
-- [x] **T2 (P1, human: ~1d / CC: ~40min)** — M1b — Hoist `pipe_blueprint`, `validation`, `template_guard_lint`, `handle_pipe_errors` out of `core/`
- - Surfaced by: Issue 3 — D-M1-2 classified by outbound imports; inbound test shows 0 runtime-layer importers
- - Files: `pipelex/core/pipes/`, `pipelex/pipe_machinery/`, `pipelex/mthds_parsing/`
- - Verify: inbound test reports ≥1 runtime importer for every module left in `core/pipes/`; `make chl`; closure test
-- [x] **T3 (P1, human: ~2h / CC: ~15min)** — M1c — Update `conformance` ALLOWED_SURFACE + `docs/specs/pipelex-transport-boundary.md`
- - Surfaced by: Issue 2 — active unskipped test pins `pipelex.core.pipes.pipe_abstract`; `_hub`'s suite cannot catch it
- - Files: `conformance/tests/pipelex_transport/test_data.py`, `docs/specs/pipelex-transport-boundary.md`
- - Verify: `make check-spec-links` in `conformance/`
-- [ ] **T4 (P1, human: ~4h / CC: ~30min)** — Phase 5 — Expand the sweep table to 8 repos incl. the 4 `error_type` wire-string consumers
- - Surfaced by: Issue 1 — the table named one repo; there are eight, and four consume a wire string
- - Files: `TODOS.md`, workspace-root `CLAUDE.md` (✅ done)
- - Verify: re-run the cross-repo grep; every hit appears in the table
-- [x] **T5 (P2, human: ~2h / CC: ~15min)** — M1c — Rewrite `test_core_is_split_between_the_layers` wholesale
- - Surfaced by: Issue 6 — six assertions invert or go stale; four go vacuously green between M1b and M1c
- - Files: `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`
- - Verify: `.venv/bin/pytest tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`
-- [x] **T6 (P2, human: ~1h / CC: ~10min)** — M3 + M2 — Add `drift-ack` steps for `hub-layering-convention`
- - Surfaced by: Issue 5 — `drift.toml:65-69` triggers on the guard; all three tracks touch it, only M1c acked
- - Files: `TODOS.md`, `drift.toml`
- - Verify: `make drift-check` green at each checkpoint — ✅ M3 half done: the contract opened exactly as predicted (only after `git add`; the digest reads the index), was reviewed for real, acked, and logged in `wip/drift-contracts/dogfood-log.md` (mandatory per ack). M2's ack landed at CHECKPOINT M2 — and M2 opened a *second* contract the plan did not predict, `config-docs`, because re-pathing the four vendor config imports touches `config_cogt.py`. Both reviewed for real, both acked, both logged.
-- [x] **T7 (P2, human: ~1d / CC: ~30min)** — M2 — Rewrite the 189 string-literal module references
- - Surfaced by: Issue 7 — invisible to import rewrites and pyright; 189 in M2, 15 in M1
- - Files: `tests/unit/pipelex/plugins/`, `pipelex/plugins/`
- - Verify: `make agent-test`; zero surviving `pipelex.plugins.<vendor>` literals
-- [x] **T8 (P2, human: ~1d / CC: ~30min)** — F1 — Extract the taxonomy/geometry helpers into a neutral `cogt/img_gen/` mapping module; both sides import inward
- - Surfaced by: Issue 8 + Codex #14/#15 — `make_args_for_model` takes no sdk, dispatch is by `AspectRatioTaxonomy`, gateway is one SDK spanning both; a registry slot would force a plugin-API bump
- - Files: `pipelex/cogt/img_gen/img_gen_args_factory.py`, `pipelex/providers/{google,openai}/*_img_gen_factory.py`
- - Verify: a test per taxonomy branch incl. the unmapped-taxonomy path; `pipelex.plugins.contract` untouched
-- [x] **T11 (P1, human: ~2h / CC: ~15min)** — M2 — Add a guard test asserting `pipelex.providers.*` is runtime-layer
- - Surfaced by: Codex #5 — the transitive rule filters through `is_runtime_layer`, so an omitted declaration is excluded from the check, not caught by it. No existing gate covers this
- - Files: `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`
- - Verify: drop `"pipelex.providers"` from the tuple and confirm the test goes red
-- [x] **T12 (P2, human: ~2h / CC: ~15min)** — M1a — Fix the embedded qualname in `subject_grants.toml:2615` alongside the re-path
- - Surfaced by: Codex #8 — the key carries `PipelexInterpreter.make_pipelex_bundle_blueprint`; re-pathing alone leaves it stale and hard-fails `check-keyword-only`
- - Files: `subject_grants.toml`
- - Verify: `make cko`
-- [x] **T13 (P2, human: ~1h / CC: ~10min)** — ~~M1a~~ + ~~M2~~ — Create the two missing `__init__.py` files — ✅ both done (`pipelex/mthds_parsing/__init__.py`, `pipelex/providers/__init__.py`)
- - Surfaced by: Codex #2 — ruff `select = ["ALL"]`, `INP001` exempt only for `tests/**`; both commits fail lint as written
- - Files: `pipelex/mthds_parsing/__init__.py`, `pipelex/providers/__init__.py`
- - Verify: `make agent-check`
-- [ ] **T9 (P3, human: ~3d / CC: ~1 session)** — follow-up — Decouple `error_type` from the Python class name
-- [x] **T10 (P3, human: ~4h / CC: ~25min)** — follow-up — Guard against vacuously-green string-predicate tests — ✅ **done in M1c**, both halves: `RUNTIME_LAYER_PACKAGES` entries and `INTERPRETER_PACKAGES` tokens must each resolve on disk, mutation-checked red
-
----
-
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
-| Codex Review | `/codex review` | Independent 2nd opinion | 1 | ISSUES FOUND → absorbed | 15 findings, all folded |
-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR | 8 issues, 1 critical gap (closed) |
-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | — |
-| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |
-
-- **CODEX:** ran in-repo at high reasoning effort; verdict *"not implementation-ready"*, 15 findings. Eight verified against the tree, all held. All folded in. Two reversed prior rulings: **F1 drops the registry** for a neutral `cogt/img_gen/` mapping module (no dispatch key exists), and **M1 stacks on M3** (the topology was self-contradictory). The sharpest catch: the plan claimed the transitive rule catches an omitted `RUNTIME_LAYER_PACKAGES` entry — it is the opposite, an undeclared package is excluded from the rule's domain (`hub_layering_guard.py:677`).
-- **CROSS-MODEL:** 23 findings total, no overlap — the two passes were complementary rather than confirming. The eng review found *classification and blast-radius* errors (outbound-vs-inbound layer test, wire strings, missing consumer repos); Codex found *build-order and gate-efficacy* errors (lint failures, unguarded windows, a safety net that does not exist). Both agreed independently that F1's registry framing was wrong; only Codex found why.
-- **VERDICT:** ENG CLEARED — ready to implement. Scope accepted as-is (three tracks + F1, three stacked PRs); 23 findings folded; 1 critical test gap closed by the regression rule.
-
-NO UNRESOLVED DECISIONS
diff --git a/wip/refactoring/modularity-refactors.md b/wip/refactoring/modularity-refactors.md
deleted file mode 100644
index 0d6022ef2..000000000
--- a/wip/refactoring/modularity-refactors.md
+++ /dev/null
@@ -1,292 +0,0 @@
-# Three modularity refactors after the hub split
-
-> ⚠ **SUPERSEDED IN PART — read [`modularity-refactors-tracker.md`](modularity-refactors-tracker.md) first.** An engineering review on 2026-07-27 (plus an independent Codex pass) reversed and re-ruled several decisions below. The tracker is now authoritative for *what to do*; this document remains the record of the *original* reasoning. Specifically:
->
-> - **D-M1-2 is REVERSED.** `pipe_blueprint.py` is **interpreter-layer and moves**, together with `validation.py`, `template_guard_lint.py` and `handle_pipe_errors.py`. The measurement below counts **outbound** imports, which tells you whether a module is a *leaf*, not which layer owns it. The deciding test is **inbound**: zero declared runtime-layer modules import any of those four. Sections "The rulings that shape the hoist" (below), move 5, and the Decisions row for D-M1-2 are all stale.
-> - **The rule of thumb is NOT rewritten.** *"If it names a `Pipe`, it belongs to the interpreter layer"* was correct all along; move 5's proposed replacement only existed to accommodate the `pipe_blueprint` misclassification.
-> - **F1 uses no registry.** `inference_backend_registry` is `(family, sdk) → MakeWorkerFn`, and `make_args_for_model` receives no sdk — dispatch is by `AspectRatioTaxonomy`. The fix is a neutral mapping module under `cogt/img_gen/`.
-> - **M2 is not release-gated** (zero external consumers of `pipelex.plugins.<vendor>`), and its "vendor modules importing anything but the mechanism = 0" exit metric is false by construction — cross-vendor edges are deliberately preserved.
-> - **M1 stacks on M3**; the "each track branches from the #1064 base" note in [Sequencing](#sequencing) is superseded.
-
-**Status: DRAFT v2, not started.** Written on `refactor/Modularity-3`, which is based on `refactor/Hub-2` (PR #1064) — deliberately: all three tracks build on the F1 remedy (`pipelex/interpreter_plugins/`, the transitive guard rule), so #1064 merges first and these PRs land on top of it. Every number below is measured on that tree with the snippets recorded in [Measurement](#measurement); nothing here is estimated. v2 folds in the review pass: the naming and layer questions that were open in v1 are now recorded rulings in [Decisions](#decisions), and the operational costs v1 missed (subject-grant re-pathing, error-page regeneration, test-tree mirroring) are in [Ground rules for the moves](#ground-rules-for-the-moves).
-
-Three tracks that continue the boundary work the hub split started. They are ordered by dependency, not by value: **M3 is a prerequisite slice of M1**, and **M2 is independent of both**.
-
-| track | what | why now |
-| --- | --- | --- |
-| [M3](#m3--split-the-boot-manifest-by-layer) | split `CoreRegistryModels` by layer, seed the pipe-machinery package | removes core's fattest interpreter edge (92 modules) in one small, self-contained PR |
-| [M1](#m1--make-cores-layer-split-physical) | hoist core's interpreter-layer modules out of `core/` | makes the boundary visible in the tree instead of in a guard tuple; collapses `RUNTIME_LAYER_PACKAGES` |
-| [M2](#m2--separate-the-plugin-mechanism-from-the-vendor-adapters) | split `pipelex/plugins/` into mechanism + providers | one package name currently hides a clean one-way dependency behind an apparent cycle |
-
-**All three break external imports.** The repo already owes a release-gated cross-repo sweep for the hub split, the Phase 3 type moves, and the `interpreter_plugins` relocation (see [`wip/hub/hub-split-tracker.md`](../hub/hub-split-tracker.md) → Cross-repo sweep). Every rename below lands in the same consumer repos. **Do these before that sweep executes**, so consumers absorb one breaking wave instead of four. That is the single strongest scheduling argument in this document.
-
----
-
-## M3 — split the boot manifest by layer
-
-### What is true today
-
-`core/registry_models.py` is **not core**. It has exactly one consumer in the entire tree:
-
-```python
-# pipelex/pipelex.py:500
-self.class_registry.register_classes(CoreRegistryModels.get_all_models())
-```
-
-It is a boot-time composition manifest that happens to live in `core/`. And it holds **two unrelated registries in one class**:
-
-- `PIPE_OPERATORS`, `PIPE_OPERATORS_FACTORY`, `PIPE_CONTROLLERS`, `PIPE_CONTROLLERS_FACTORY`, `PIPE_SIGNATURES`, `PIPE_SIGNATURES_FACTORY` — every one of these imports `pipe_operators` / `pipe_controllers` / `pipe_signature` directly. This half is what makes the module load **92 interpreter modules**, the fattest single module in `core/`.
-- `STUFF`, `EXPERIMENTAL`, `FIELD_EXTRACTION` — pure `core.stuffs`, zero interpreter modules.
-
-`RegistryModels.get_all_models()` reflects over every list `ClassVar` via `dir(cls)`, so splitting one class into two is mechanical and boot registers both.
-
-### Moves
-
-1. **Split `CoreRegistryModels` by layer, with the names decided up front.**
- - `core/registry_models.py` keeps the value-model half (`STUFF`, `EXPERIMENTAL`, `FIELD_EXTRACTION`) under the name `CoreRegistryModels` — still accurate, since core's runtime half is exactly the value model. Measures 0 interpreter modules after the split.
- - The pipe half becomes `PipeRegistryModels` in **`pipelex/pipe_machinery/registry_models.py`** — M3 creates the `pipe_machinery/` package with just this module, and M1 fills it ([D-M1-1](#decisions)). No placeholder, nothing moves twice.
- - `pipelex.py` registers both. Two adjacent `register_classes` lines that read as obviously-different registrations; no behavior change.
-
-2. **Leave `PipeType` / `PipeCategory` where they are** (`core/pipes/pipe_blueprint.py`). They are string tags naming no class and the module measures 0 — it is runtime-layer by measurement and stays in `core/` permanently ([D-M1-2](#decisions)).
-
-3. **Document the registration surface.** After the move, "adding a pipe kind" is: the kind's package, the type tag, the blueprint union, `PipeRegistryModels`, the spec map (`builder/pipe/pipe_spec_map.py` + `pipe_spec_union.py`). Write that list into `docs/contribute/` so it stops being tribal knowledge — with a note that the spec-layer parallel in `builder/pipe/` is deliberate (see `pipelex/builder/CLAUDE.md`, spec vs blueprint), not duplication to be collapsed.
-
-### Cut from v1: the `PipeBlueprintUnion` extraction
-
-v1 proposed extracting `PipeBlueprintUnion` out of `core/bundles/pipelex_bundle_blueprint.py` as part of M3. Cut, for two reasons v1 only half-admitted: the extraction moves import *statements* but not the closure (`pipelex_bundle_blueprint` still measures 28 interpreter modules either way), and M1 hoists `core/bundles/` out of `core/` anyway — so an extracted union module would **move twice**. Once the module leaves `core/`, its twelve blueprint imports are no longer inverted and the extraction buys nothing. The union stays where it is and rides the M1 hoist; discoverability of the manifests is handled by the registration-surface doc (move 3), not by file adjacency.
-
-### Exit criteria — measured
-
-`core/` reaches up into the pipe-kind packages in **43 import statements**, concentrated in two files:
-
-| source module | `pipe_operators` | `pipe_controllers` | `pipe_signature` | total | moved by |
-| --- | --- | --- | --- | --- | --- |
-| `core.registry_models` | 14 | 8 | 2 | **24** | M3 |
-| `core.bundles.pipelex_bundle_blueprint` | 7 | 4 | 1 | **12** | M1 |
-| `core.interpreter.bundle_elaborator` | 2 | 2 | — | 4 | M1 |
-| `core.pipes.rendering.output_renderer` | — | 2 | — | 2 | M1 |
-| `core.pipes.pipe_abstract` | — | — | 1 | 1 | M1 |
-
-| | before | target after M3 | target after M1 |
-| --- | --- | --- | --- |
-| inverted `core → pipe_*` statements | 43 | 19 | 0 |
-| interpreter modules loaded by `pipelex.core.registry_models` | 92 | 0 | 0 |
-| pipe-kind manifests filed inside `core/` | 2 | 1 | 0 |
-
-**CHECKPOINT M3** — gates: `make agent-check` + full `make agent-test` + `make drift-check`, plus the grant re-path from the [ground rules](#ground-rules-for-the-moves). Re-take the [core classification](#measurement) and confirm `core.registry_models` reports 0. This is a natural handoff point: M3 lands as its own PR, and M1 starts from a tree where core's fattest interpreter edge is already gone and the pipe-machinery package exists.
-
----
-
-## M1 — make core's layer split physical
-
-### What is true today
-
-`docs/contribute/hub-layering.md` already says it: *"`pipelex/core/` is not one layer, and trying to declare it one was the mistake this section records."* But the split exists only inside the guard's configuration:
-
-```python
-RUNTIME_LAYER_PACKAGES = (..., "pipelex.core.concepts", "pipelex.core.domains",
- "pipelex.core.memory", "pipelex.core.pipes.inputs",
- "pipelex.core.pipes.stuff_spec", "pipelex.core.stuffs")
-```
-
-Six sub-paths enumerated by hand — plus `core.pipes.pipe_output`, which *is* runtime-layer but cannot be listed because the declaration is package-granular, so the doc has to explain that the closure test covers it instead. The boundary lives in a tuple and a paragraph, not in the tree.
-
-### The finding
-
-The residue is far smaller than the six-entry declaration suggests. Importing each `core` module in a subprocess and counting interpreter modules loaded: **86 of 95 measure zero**. The nine that do not:
-
-| module | interpreter modules loaded | pulls in `interpreter_hub` |
-| --- | --- | --- |
-| `core.registry_models` | 92 | yes |
-| `core.pipes.pipe_factory` | 48 | yes |
-| `core.pipes.rendering.input_renderer` | 48 | yes |
-| `core.pipes.rendering.output_renderer` | 48 | yes |
-| `core.pipes.pipe_abstract` | 30 | no |
-| `core.bundles.pipe_sorter` | 28 | no |
-| `core.bundles.pipelex_bundle_blueprint` | 28 | no |
-| `core.interpreter.bundle_elaborator` | 28 | no |
-| `core.interpreter.interpreter` | 28 | no |
-
-M3 removes the first one outright. **Eight modules** stand between `core/` and being a single declared runtime-layer package, and they are the whole of M1's hoist.
-
-### The rulings that shape the hoist
-
-Two places where the doc's rule of thumb ("if it names a `Pipe`, it belongs to the interpreter layer") and the measurement disagreed are now settled — **the measurement wins**, because the closure property is what the guard actually enforces ([D-M1-2](#decisions)):
-
-- **`core/pipes/pipe_blueprint.py` is runtime-layer and stays in `core/`.** It imports only `core.concepts` and `core.pipes` siblings and measures 0; what it declares is `PipeType` / `PipeCategory` / the signature-normalization helpers — vocabulary and parse-time validation, not machinery. The doc's claim that every Pipe-naming module "imports `pipe_operators` / `pipe_controllers` directly" is factually wrong for this module; the rewrite (move 5) fixes the rule, not the module.
-- **The four measured-zero leaf modules move with their packages.** `core.bundles.exceptions`, `core.interpreter.exceptions`, `core.interpreter.helpers`, `core.interpreter.validation_error_categorizer` measure 0, but cohesion wins: their importers are `cli/`, `libraries/`, `pipeline/`, `builder/` — none runtime-layer-declared (the `core/pipes/handle_pipe_errors.py` mention is a docstring, not an import) — so hoisting them breaches nothing, and an interpreter-layer module is free to measure 0.
-
-### Moves
-
-1. **Hoist the eight interpreter-layer modules (plus the four leaf modules) out of `core/`, into the two packages the groups already form:**
- - **`pipelex/mthds_parsing/`** — bundle parsing, MTHDS text → `PipelexBundleBlueprint` ([D-M1-3](#decisions)): `interpreter.py`, `bundle_elaborator.py`, `pipe_sorter.py`, `pipelex_bundle_blueprint.py`, `helpers.py`, `validation_error_categorizer.py`, and the two exceptions modules merged into one `mthds_parsing/exceptions.py` (topical split only if a circular import forces it, per the error-class location convention). `core/bundles/` and `core/interpreter/` cease to exist.
- - **`pipelex/pipe_machinery/`** — the pipe base machinery, joining `registry_models.py` from M3: `pipe_abstract.py`, `pipe_factory.py`, `rendering/`.
-
- The machinery package is deliberately **not** named `pipelex/pipes/`: `core/pipes/` remains (inputs, stuff_spec, pipe_output, validation — the runtime half), and two `pipes` packages in adjacent layers would be actively confusing.
-
-2. **Rename the parser class along with its package.** `core/interpreter/` shares its word with the interpreter *layer* and means something narrower — and the collision extends to the class: `PipelexInterpreter` becomes **`MthdsParser`** in `mthds_parsing/interpreter.py` → `mthds_parsing/parser.py`. Parsing the language is an MTHDS-owned concept, so the name is correctly branded. (Renaming `PipelexBundleBlueprint` itself is out of scope — it is wire-visible and widely consumed; if its branding is ever revisited, that is its own track.)
-
-3. **Collapse the guard declaration** to `"pipelex.core"` and delete the `pipe_output` carve-out paragraph from `docs/contribute/hub-layering.md`.
-
-4. **Extend the measurement classification set.** The interpreter-package set in the [measurement snippet](#measurement) (and any permanent check derived from it) gains `mthds_parsing` and `pipe_machinery` — otherwise the re-taken classification would silently under-count.
-
-5. **Rewrite the doc's rule of thumb** to match what the guard enforces: **"if it imports a pipe kind or constructs pipes, it is interpreter-layer; declaring the vocabulary (type tags, blueprint base shapes, signature normalization) is runtime."** The old "names a `Pipe`" phrasing was a good teaching rule but it misclassifies `pipe_blueprint`, and the doc and the guard should not silently diverge.
-
-### Exit criteria — measured
-
-| | before | target |
-| --- | --- | --- |
-| `RUNTIME_LAYER_PACKAGES` entries naming `pipelex.core.*` | 6 | 1 (`pipelex.core`) |
-| `core` modules loading > 0 interpreter modules | 9 | 0 |
-| doc carve-outs for `core.pipes.pipe_output` | 1 | 0 |
-
-**CHECKPOINT M1** — gates as above, plus: re-run the [core classification](#measurement) with the extended set and confirm every remaining `pipelex.core.*` module reports 0; confirm `make check-hub-layering` still passes with the collapsed declaration; confirm the transitive rule still reports 0 breaching runtime-layer modules; `make generate-error-pages` and confirm error-page/`type_uri` stability for the moved exception classes ([ground rules](#ground-rules-for-the-moves)).
-
-### Cross-repo blast radius
-
-Small, and known. Grepping the sibling repos for the nine modules:
-
-| repo | file | symbol |
-| --- | --- | --- |
-| `pipelex-api` | `api/routes/pipelex/build/runner.py` | `PipelexBundleBlueprint` |
-| `pipelex-api` | `api/routes/pipelex/crate_ops.py` | `PipeAbstract` |
-| `pipelex-api` | `tests/unit/test_validate_errors.py` | `PipelexBundleBlueprintValidationErrorData` |
-
-No external consumer imports `PipelexInterpreter`, so the class rename adds nothing to the sweep. Clean: `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows`, `pipelex-worker`, `pipelex-starter-python`, `pipelex-relay`, `sandbox`. `pipelex-temporal` is private and not checked here — verify during the sweep. None of the classes registered in the kajson class registry move (pipe classes stay in `pipe_operators/` etc.), so serialized payloads are untouched.
-
----
-
-## M2 — separate the plugin mechanism from the vendor adapters
-
-### What is true today
-
-`pipelex/plugins/` is 11.4k lines across 127 files, and it is two things:
-
-- **the mechanism** — 17 top-level modules, 1,436 lines: `contract.py`, `registrar.py` (387), `discovery.py` (161), `exceptions.py` (287), seven `*_registry.py`, `model_handle.py`, `sdk_client_registry.py`, `sdk_client_manager.py`, `backend_extras_factory.py`, `builtins.py`
-- **the built-in vendor adapters** — 17 directories, ~9,900 lines: `openai/` 17 files, `gateway/` 14, `bedrock/` 11, `google/` 9, `mistral/` 9, `anthropic/` 8, `portkey/` 7, plus fal, docling, linkup, huggingface, azure_rest, blackboxai, openrouter, pypdfium2, secrets, storage
-
-### The problem
-
-**One package name hides a one-way dependency behind an apparent cycle.** The two heaviest edges in the whole repo are `plugins → cogt` (380 statements) and `cogt → plugins` (15). That reads as a cycle. It is not:
-
-- every vendor directory imports **only** mechanism modules — `contract`, `registrar`, `inference_backend_registry`, `model_handle`, `sdk_client_registry`, `backend_extras_factory` — which is adapters importing the ports they implement, upward and correct
-- the `cogt → plugins` half is `llm_worker_factory` / `img_gen_worker_factory` / `extract_worker_factory` / `search_worker_factory` reaching `inference_backend_registry` and `model_handle` — the engine importing the registry, downward and correct
-
-**No mechanism module imports a vendor, with exactly one exception: `builtins.py`**, which is the composition root. That is the same shape the F1 remedy already established for `interpreter_plugins/builtins.py`, so the precedent and the pattern are both in place. Separating mechanism from adapters makes this structure visible in the tree: adapters → mechanism, engine → mechanism, mechanism → nothing.
-
-A secondary point, stated honestly: v1 led with "the name misleads" — `pipelex/plugins/openai/` inviting the conclusion that OpenAI support is external. That argument is real but overstated: each vendor directory ships a `*Plugin` class implementing the `PipelexPlugin` contract, so they genuinely *are* plugins — first-party built-in ones, a category the docs already use comfortably. The conflation of mechanism with adapters is the load-bearing reason to split; the naming clarity is a bonus.
-
-### The seven `cogt → <specific vendor>` edges — split ruling
-
-Seven statements reach from `cogt` *into a specific vendor package*:
-
-```
-cogt/config_cogt.py -> plugins.{anthropic,google,mistral,openai}.*_config
-cogt/img_gen/img_gen_args_factory.py -> plugins.{google,openai}.*_img_gen_factory
-cogt/model_backends/backend_factory.py -> plugins.openai.vertexai_factory
-```
-
-These are two different animals, and they get two different rulings ([D-M2-2](#decisions)):
-
-- **The four config imports are accepted and documented.** The main config model is statically typed end-to-end (`configs.py` ⇄ `pipelex.toml` structural sync); making vendor config sections plugin-contributed would trade that static typing for a dynamic registry — over-engineering given this repo's config discipline. Record them as a known, deliberate exception in `hub-layering.md`'s Known inversions.
-- **The three factory imports are a defect, fixed as a separate small follow-up.** `img_gen_args_factory` naming `GoogleImgGenFactory` / `OpenAIImgGenFactory`, and `backend_factory`'s inline `vertexai_factory` import, are exactly what `inference_backend_registry` exists to dispatch. Fix them behind the registry — but *not* inside the 127-file move, where a behavior change would be invisible in the diff.
-
-### Moves
-
-1. **Keep `pipelex/plugins/` for the mechanism only** — contract, registrar, discovery, exceptions, the registries, the SDK client machinery. That package then genuinely is "how an extension plugs in", matching the docs.
-
-2. **Move the 17 vendor directories to `pipelex/providers/`** ([D-M2-1](#decisions)). `providers/` beats v1's preferred `backends/` on two concrete grounds: `backends/` would collide with the existing `pipelex/cogt/model_backends/` (two "backends" packages in adjacent layers), and the code's own vocabulary for the non-inference adapters is already "provider" — `secrets_provider_registry`, `storage_provider_registry` — so `providers/secrets/` and `providers/storage/` fit without the nesting workaround `backends/` would force. "Inference provider" is also the natural industry term, and the directories are keyed by vendor, not capability.
-
-3. **`builtins.py` follows the vendors** (`pipelex/providers/builtins.py`) and keeps exporting `RUNTIME_BUILTIN_PLUGINS` / `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES`. `interpreter_plugins/builtins.py` re-points its downward import. Both remain parameters of `build_registrar`, unchanged.
-
-4. **Add `pipelex.providers` to `RUNTIME_LAYER_PACKAGES`.** The vendors are runtime-layer today by declaration and by measurement; the split must not silently drop them from the guard. This is the one step where a mistake is invisible — the transitive rule is what catches it.
-
-5. **Cross-vendor edges survive unchanged** (`blackboxai` / `openrouter` / `portkey` → `openai`; `gateway` → `fal` / `google` / `openai` / `portkey`) because they stay inside the new package.
-
-### Exit criteria — measured
-
-| | before | target |
-| --- | --- | --- |
-| mechanism modules importing a vendor | 1 (`builtins.py`, by design) | 0 in `plugins/`, 1 in `providers/` |
-| vendor modules importing anything but the mechanism | 0 | 0 (unchanged) |
-| `cogt → <specific vendor>` statements | 7 | 7 (4 documented in Known inversions; 3 queued as the registry follow-up) |
-| `RUNTIME_LAYER_PACKAGES` covers every vendor module | yes | yes |
-
-**CHECKPOINT M2** — gates as above, plus a re-run of the transitive layering rule confirming 0 breaching runtime-layer modules, the closure test still reporting 0 interpreter modules for every runtime entry point, and `make generate-error-pages` if any vendor directory carries an exceptions module.
-
-### Cross-repo blast radius
-
-Anything importing `pipelex.plugins.<vendor>.*` breaks. In-tree that is 7 statements in `cogt` and 67 test files. External: `pipelex-api`, `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows` all import `pipelex.plugins.*` or `pipelex.core.*` — size the vendor-specific subset during the sweep. `pipelex-temporal` (private) is unchecked here.
-
-The *plugin entry-point contract* is unaffected: an external plugin imports `pipelex.plugins.contract` / `pipelex.plugins.registrar`, both of which stay put. That is the surface we promised third parties, and it does not move.
-
----
-
-## Decisions
-
-The questions v1 left open, now ruled. Each ruling is recorded where it is applied; this table is the index.
-
-| id | ruling | why |
-| --- | --- | --- |
-| **D-M1-1** | The pipe manifest lives in `pipelex/pipe_machinery/registry_models.py` as `PipeRegistryModels`; M3 creates the package, M1 fills it | next to `PipeAbstractType` / `PipeFactoryProtocol` that type its lists; no placeholder, nothing moves twice |
-| **D-M1-2** | The measurement wins over the "names a `Pipe`" heuristic: `pipe_blueprint.py` is runtime and stays in `core/`; the four measured-zero leaf modules move with their packages | the closure property is what the guard enforces; leaf-module importers verified non-runtime, so cohesion is free |
-| **D-M1-3** | `core/interpreter/` + `core/bundles/` → `pipelex/mthds_parsing/`; `PipelexInterpreter` → `MthdsParser` | says what it does, correctly MTHDS-branded, and evicts the colliding word from both the path and the class |
-| **D-M2-1** | Vendors move to `pipelex/providers/`, flat (no capability nesting) | avoids the `cogt/model_backends` collision `backends/` would create; matches the existing `*_provider_registry` vocabulary; directories are keyed by vendor |
-| **D-M2-2** | The four `cogt` config imports: accepted, documented in Known inversions. The three factory imports: defect, fixed behind the registry as a separate follow-up after M2 | static config typing is worth keeping; the factory fix is a behavior change and must not hide inside a 127-file rename |
-
-## Ground rules for the moves
-
-Cross-cutting operational costs that apply to every track — v1 missed all three, and the first one would have made the first `make agent-check` after any move fail confusingly.
-
-- **Re-path subject grants in the same commit as each move.** `subject_grants.toml` keys grants by `<path>::<qualname>`, and staleness is symmetric: a grant whose def moved **hard-fails** `check-keyword-only`. Every track that moves files rewrites the affected path prefixes in the registry in the same commit as the `git mv`, then verifies with `make cko`. Do not rely on the auto-fixer here — `fko` would silently keyword-only the "ungranted" subjects instead.
-- **Regenerate error pages when an exceptions module moves.** The per-class pages under `docs/errors/` are what each error's `type_uri` dereferences to. After any move that relocates an error class, run `make generate-error-pages` (alias `gep`) and confirm the pages — and any module-path-derived component of the URIs — are stable or intentionally changed.
-- **Mirror the test tree and clean derived state.** `tests/unit/` mirrors source paths; each move drags its test files along in the same commit. Run `make cleanderived` after the moves so pytest collection and the linters don't chase ghosts.
-
-## Sequencing
-
-```
-PR #1064 (refactor/Hub-2) merges
- ↓
-M3 → M1 (M3 removes core's fattest interpreter edge and seeds pipe_machinery/; M1 hoists the rest)
-M2 (independent — can run in parallel or in either order)
- ↓
-follow-up: the three cogt factory imports behind the registry (D-M2-2)
- ↓
-release-gated cross-repo sweep (one wave: hub split + Phase 3 moves + interpreter_plugins + M1 + M2 + M3)
-```
-
-Each track is its own PR with its own checkpoint, branched from the #1064-inclusive base. None of them should be merged into the sweep's own branch — the sweep consumes their results.
-
-## Measurement
-
-Core module classification, run from the repo root on a synced venv. Reports, per `pipelex.core.*` module, how many interpreter modules it loads and whether it drags in `interpreter_hub`. `I` must name every interpreter top-level package — it is one of three copies of that set (the others are `INTERPRETER_PACKAGES` in the closure test and the `INTERPRETER` set in `docs/contribute/hub-layering.md`'s verification snippet), and a package missing from any one of them makes that check pass vacuously. `"pipe_machinery"` was added by M3, `"mthds_parsing"` by M1a:
-
-```bash
-.venv/bin/python - <<'PY'
-import os, subprocess, sys
-
-ROOT = os.getcwd()
-SNIP = '''
-import sys, importlib
-importlib.import_module(%r)
-I = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder", "interpreter_plugins", "pipe_signature", "pipe_machinery", "mthds_parsing", "pipeline", "pipe_run"}
-bad = sorted(n for n in sys.modules if n.startswith("pipelex.") and len(n.split(".")) > 1 and n.split(".")[1] in I)
-print(len(bad), int("pipelex.interpreter_hub" in sys.modules))
-'''
-mods = []
-for dirpath, dirnames, files in os.walk(os.path.join(ROOT, "pipelex", "core")):
- dirnames[:] = [d for d in dirnames if d != "__pycache__"]
- for f in files:
- if not f.endswith(".py"):
- continue
- rel = os.path.relpath(os.path.join(dirpath, f), ROOT)[:-3].replace(os.sep, ".")
- mods.append(rel[:-9] if rel.endswith(".__init__") else rel)
-for m in sorted(mods):
- r = subprocess.run([sys.executable, "-c", SNIP % m], capture_output=True, text=True, cwd=ROOT)
- n, hub = r.stdout.split()
- if int(n) or int(hub):
- print(f"INTERP interp_mods={n:<4} hub={hub} {m}")
-PY
-```
-
-Cross-package import-statement counts (the `core → pipe_operators` style numbers) come from an `ast` walk resolving relative imports against the importing module's package, counting one per `Import` / `ImportFrom` whose target's second path segment differs from the source's. The hub-layering guard already carries a correct implementation of that graph — prefer extending `hub_layering_guard.py` over re-deriving it if any of this becomes a permanent check.
diff --git a/wip/refactoring/modularity-review-follow-ups.md b/wip/refactoring/modularity-review-follow-ups.md
deleted file mode 100644
index c9cc7fddc..000000000
--- a/wip/refactoring/modularity-review-follow-ups.md
+++ /dev/null
@@ -1,288 +0,0 @@
-# Review follow-ups — assessed and ready to implement
-
-The three items the modularity track's review rounds recorded but did not fix. Each was **re-verified against the tree on 2026-07-28 at `7ddb77f87`** before being written down here; every claim below is measured, and the commands that produced it are inline so a new session can re-take them rather than trust them.
-
-**Where implemented:** branch `refactor/Modularity-4`, on top of the merged PR #1067. All three are independent of each other and of the release-gated cross-repo sweep — except **FU-1**, which had to land *before* the sweep ships the `MthdsParserError` rename to its consumers.
-
-**Stable IDs:** cite these as **FU-1**, **FU-2**, **FU-3**. They supersede the unnumbered bullets in the tracker's "Follow-ups from the review" section, which points here.
-
-| id | one line | verdict | size | status |
-| --- | --- | --- | --- | --- |
-| [FU-1](#fu-1--nothing-flags-an-error-class-rename-and-it-is-a-wire-break) | Nothing flags an error-class rename, and it is a wire break | still true — **do this first** | small | ✅ **DONE** |
-| [FU-2](#fu-2--the-img-gen-neutrality-guard-is-weaker-than-its-comment-and-its-recorded-remedy-is-wrong) | The img-gen neutrality guard overclaims; its recorded remedy rests on a false measurement | still true, **remedy corrected here** | two small edits | ✅ **DONE** |
-| [FU-3](#fu-3--the-bookkeeping-files-a-bulk-rewrite-breaks-are-still-ungated) | The bookkeeping files a bulk rewrite breaks are still ungated | gate absent, artifacts currently clean | small, do half | ✅ **DONE** |
-
----
-
-## FU-1 — Nothing flags an error-class rename, and it is a wire break
-
-> ✅ **DONE** — see [what shipped](#what-shipped) at the end of this section.
-
-### Verified still true
-
-`pipelex/base_exceptions.py:595` builds the report identity straight off the class:
-
-```python
-report = ErrorReport(
- error_type=type(self).__name__,
- ...
-)
-```
-
-`error_type` **is** the Python class name, with no indirection. Consumers branch on that string, so a rename does not break their build — they silently fall through to a generic error branch. All four consumer sites confirmed live and still switching on the **retired** name:
-
-| repo | site | shape |
-| --- | --- | --- |
-| `mthds-starter-js` | `src/lib/errors.ts:176` | `case "PipelexInterpreterError":` |
-| `pipelex-starter-js` | `src/lib/errors.ts:257` | `case "PipelexInterpreterError":` |
-| `vscode-pipelex` | `editors/vscode/src/pipelex/__tests__/cliValidationBackend.test.ts:99` | `error_type: 'PipelexInterpreterError'` |
-| `playroom` | `src/app/api/graph/route.ts:119` | `message.includes("PipelexInterpreterError")` |
-
-The `redirect_maps` workaround is at `mkdocs.yml:60`, with a comment naming this exact rename. It fixes the docs URI; it does nothing for the four sites above.
-
-### What the original item did not say, and it changes the cost
-
-**`title` and `type_uri` are already decoupled.** Both read a `_declared_*` class attribute via `cls.__dict__` (inheritance deliberately bypassed) — `base_exceptions.py:532` and `:547`, added during M1's review round to fix the `"Mthds parser"` brand defect. Measured today: error classes discoverable through `iter_pipelex_error_subclasses()` = **294**; carrying a `_declared_title` = **31**; carrying a `_declared_type_uri` = **0**.
-
-So of the three identity fields on every `ErrorReport`, the two that are *presentation* have an override hatch, and the one that is the **machine contract** does not. That asymmetry is backwards, and it is also why the fix is cheap.
-
-### Recommendation — do the cheap half now, defer the design change
-
-**Do: a golden snapshot of `(error_type, title, type_uri)` for every `PipelexError` subclass.**
-
-The complaint is *"nothing in the repo flags it"*. A snapshot closes exactly that, needs no change to the error model, and needs no matching spec/conformance edit. Every future rename then lands as a reviewable diff on a committed file instead of a silent fallthrough in four TypeScript repos.
-
-Everything needed already exists:
-
-- **The enumerator:** `iter_pipelex_error_subclasses()` in `pipelex/errors/error_pages_generator.py:130`. It force-loads deferred-import error modules first and filters synthetic/fixture subclasses, so it is the population the docs and the wire agree on. Do **not** hand-roll a `__subclasses__()` walk — `tests/unit/pipelex/errors/test_error_class_location_convention.py:141` documents why (a naked walk is green for the wrong reason).
-- **The precedent and the home:** `tests/unit/pipelex/errors/`, alongside the location-convention test that already consumes the same helper.
-- **The one-class version to generalize:** `test_mthds_parser_error_identity_is_pinned` (added in M1's review round for `MthdsParserError`).
-
-Shape it as a committed golden file plus a regeneration command, in the style the repo already uses for generated artifacts — not as an inline literal in the test body. A 294-row inline list is the *inventory* shape this track spent four review rounds deleting; a golden file diff is a review artifact, which is the point.
-
-⚠ **Anti-vacuity:** assert the enumerated set is non-empty, in a **non-parametrized** test. If you parametrize over the class list, pytest reports `SKIPPED [1] got empty parameter set` and exits 0 for an empty list — an assertion at the top of a parametrized body is unreachable by construction. This is the F1 defect; see `tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py` for the worked fix.
-
-**Defer: the `_declared_error_type` refactor.** Mirroring the existing `_declared_title` / `_declared_type_uri` pattern for `error_type` is ~10 lines against code that already exists. But it buys less than it looks like here: the workspace forbids backward compatibility, so it cannot be used to keep `"PipelexInterpreterError"` alive for the four consumers — they must be updated in the sweep either way. Its value is purely forward, making the *next* rename free. Worth doing when a rename is actually wanted; it touches the error model and the agent-CLI JSON envelope, so it needs a matching `docs/specs/` + `conformance/` change (`error_type` appears in `docs/specs/pipelex-mthds-protocol.md`, `pipelex-hosted-envelope.md`, `mthds-agent-cli.md`, `hook-lint-pipeline.md`).
-
-### Ordering
-
-Land the snapshot **before** the release-gated cross-repo sweep. The sweep is what actually ships `MthdsParserError` to those four consumers, and the snapshot is what makes the next such rename visible at the moment it is made rather than at the moment something breaks in a different repo.
-
-### What shipped
-
-Re-verification held on both counts before starting: `error_type=type(self).__name__` is still at `base_exceptions.py:595`, and all four consumer sites still switch on `"PipelexInterpreterError"` (plus two test files in the starter repos that the original survey did not list — `mthds-starter-js/src/lib/errors.test.ts:145` and `pipelex-starter-js/src/lib/errors.test.ts:170`). The cheap half was done as recommended; the `_declared_error_type` refactor stays deferred.
-
-| file | role |
-| --- | --- |
-| `pipelex/errors/error_identity_snapshot.py` | pure renderer — `iter_error_identity_rows()` + `render_error_identity_snapshot()`, population from `iter_pipelex_error_subclasses()` |
-| `pipelex/cli/dev_cli/commands/generate_error_identity_cmd.py` | `pipelex-dev generate-error-identity`, owns the repo-relative output path |
-| `tests/data/errors/error_identity.txt` | the committed golden — a preamble, then one `error_type \| title \| type_uri` row per class |
-| `tests/unit/pipelex/errors/test_error_identity_snapshot.py` | the gate |
-| `Makefile` | `make generate-error-identity`, alias `make gei` |
-
-Decisions taken, and why:
-
-- **Pytest is the gate; there is no `check-error-identity` command.** The doc asked for "a committed golden file plus a regeneration command"; a second freshness command wired into `make check` would duplicate what the test already does. The regeneration command exists, the *checking* lives in one place.
-- **The renderer takes no Pipelex bootstrap.** `title()` / `type_uri()` read class attributes and a module-level URL constant, and discovery imports error modules by filename — so unlike `generate-error-pages` this runs anywhere, including an environment with no configured backend.
-- **The anti-vacuity guard is honoured.** `test_enumerated_identity_set_is_not_empty` is non-parametrized and additionally asserts `PipelexError` itself is present, so the guard is count-free and cannot be skipped into a green run.
-- **A third test pins format integrity** — no identity field may contain the `" | "` column separator, which is what keeps the rendering unambiguous.
-
-Negative-tested: rewriting the `MthdsParserError` row to `PipelexInterpreterError` fails the gate with the diff shown inline and the "this is a WIRE BREAK" framing, which is exactly the review artifact the item asked for.
-
-Docs updated in the same change: [Error Model](../../docs/under-the-hood/error-model.md) gains an "identity triple" subsection explaining why `error_type` has no declaration hatch and what the snapshot is for; the kit agent-rules sources (`commands.md`, `codex_commands.md` — `CLAUDE.md` / `AGENTS.md` are *generated* from these, via `make rules`) list the new dev CLI command; `docs/contribute/drift-contracts.md` adds the artifact to the Derived tier and to the never-review-generated-output corollary; CHANGELOG under `[Unreleased] / Added`.
-
-**Still open, deliberately:** the four (six, counting the starter test files) consumer sites are untouched — they are the release-gated cross-repo sweep's job, and the workspace forbids backward compatibility, so there is nothing to ship them early. The snapshot is what makes the *next* rename visible; this one still needs the sweep.
-
-Gates: `make agent-check`, `make drift-check`, and the errors / CLI / kit test slice all green.
-
----
-
-## FU-2 — The img-gen neutrality guard is weaker than its comment, and its recorded remedy is wrong
-
-> ✅ **DONE** — see [what shipped](#what-shipped-1) at the end of this section.
-
-### Verified still true
-
-Both holes are real, in `tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py`:
-
-- **(a) Transitive vendor SDKs are unguarded.** `_import_roots` AST-parses only each mapping module's *own* file, and `_CLOSURE_SCRIPT` counts only names starting with `pipelex.providers`. A vendor SDK reached through some other `pipelex.cogt` module passes both checks.
-- **(b) The glob under-claims its own coverage.** `_MAPPING_DIR.glob("img_gen_*_mapping.py")` is non-recursive and suffix-keyed, while its comment reads *"so a third taxonomy family is covered the day it lands"*. That holds only for a family landing in that exact directory under that exact name.
-
-### ⚠ The recorded remedy rests on a claim that is false
-
-The tracker's version of this item says:
-
-> Measured clean today — **zero** vendor-SDK imports anywhere in `pipelex/` outside `providers/` — and *that* is the stronger invariant, unguarded and worth a repo-wide test of its own rather than a denylist bolted onto this one.
-
-**That measurement does not hold.** Re-taken 2026-07-28 with an AST walk over `pipelex/` excluding `pipelex/providers/`:
-
-| module | SDK | form |
-| --- | --- | --- |
-| `pipelex/tools/pdf/pypdfium2_renderer.py:8-10` | `pypdfium2`, `pypdfium2.raw` | **module-level** |
-| `pipelex/tools/storage/s3_storage_provider.py` | `botocore.config`, `botocore.exceptions` | deferred |
-| `pipelex/tools/storage/gcp_storage_provider.py` | `google.cloud`, `google.api_core.exceptions` | deferred |
-| `pipelex/tracing/dynamodb_event_log.py` | `boto3`, `boto3.dynamodb.conditions`, `botocore.exceptions` | deferred |
-| `pipelex/reporting/reporting_manager.py:28-29` | `botocore.exceptions` | deferred |
-
-These are legitimate — they are *infrastructure* SDKs, not inference-provider SDKs, and they are exactly the split M2's own review recorded: `providers/storage/` is a registration shim while the implementations live under `pipelex/tools/`. But **a repo-wide "no vendor SDK outside `providers/`" test would be red on day one.** Do not write it.
-
-Reproduce with:
-
-```bash
-.venv/bin/python - <<'PY'
-import ast, os, sys
-VENDOR={"openai","anthropic","google","mistralai","boto3","botocore","fal_client","docling",
- "linkup","huggingface_hub","transformers","azure","portkey_ai","pypdfium2","vertexai"}
-for dp,dn,fs in os.walk("pipelex"):
- dn[:]=[d for d in dn if d!="__pycache__"]
- if dp.startswith("pipelex/providers"): continue
- for f in sorted(fs):
- if not f.endswith(".py"): continue
- p=os.path.join(dp,f)
- for n in ast.walk(ast.parse(open(p,encoding="utf-8").read())):
- if isinstance(n,ast.Import): rs=[(a.name.split(".")[0],a.name) for a in n.names]
- elif isinstance(n,ast.ImportFrom) and n.level==0 and n.module: rs=[(n.module.split(".")[0],n.module)]
- else: continue
- for r,full in rs:
- if r in VENDOR: print(f"{p}:{n.lineno} {full}")
-PY
-```
-
-### The invariant that *is* true and worth pinning
-
-Measured the same day: **`pipelex/cogt/**` imports zero vendor SDKs.** Its only third-party import roots are framework and infrastructure deps — `pydantic`, `httpx`, `instructor`, `opentelemetry`, `polyfactory`, `tenacity`, `rich`, `PIL`, `typing_extensions`, `datamodel_code_generator`. And `cogt → pipelex.providers` is exactly the documented set:
-
-```
-pipelex/cogt/config_cogt.py:7-10 → providers.{anthropic,google,mistral,openai}.*_config (4, documented — D-M2-2)
-pipelex/cogt/model_backends/backend_factory.py:53 → providers.openai.vertexai_factory (1, deferred, known)
-```
-
-### Recommendation — two small edits, no machinery
-
-1. **Soften the glob comment (b)** to what it proves: the glob covers a new family only if it lands in `pipelex/cogt/img_gen/` under the `img_gen_*_mapping.py` name. One line. Do not bind the convention with a test — this track's whole argument was placement over indirection, and F1 is not the place to grow machinery.
-
-2. **Replace the proposed repo-wide test (a) with a golden set of the `cogt → pipelex.providers` statements.** Pin the five above; any new edge fails. It is true today, it is the invariant `docs/contribute/hub-layering.md` → "Known inversions" already documents in prose, and it catches the realistic regression (someone adds a sixth `cogt → vendor` import) — which is precisely the class of defect F1 existed to remove and which **no other gate in the repo can see**, since `pipelex.cogt` and `pipelex.providers` are both runtime-layer and the hub guard is blind to an edge between them by construction.
-
-3. **Correct the false claim** wherever it is recorded, so nobody builds the wrong test later on the strength of it.
-
-The transitive hole (a) is then still technically open — a vendor SDK reached through a third `cogt` module would pass — but it is unreachable while `cogt/` imports no vendor SDK at all, which item 2 pins directly. That is a better trade than a denylist.
-
-### What shipped
-
-Both measurements re-taken before starting, and both held: the vendor-SDK scan still returns the same five infrastructure-SDK modules outside `providers/` (so the recorded remedy is still false), and `cogt`'s third-party roots are still exactly the ten framework/infrastructure packages with the same five `cogt → pipelex.providers` statements.
-
-| file | change |
-| --- | --- |
-| `tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py` | new — the two golden sets |
-| `tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py` | glob comment softened to what it proves; header notes where the transitive hole is closed |
-| `docs/contribute/hub-layering.md` | "Known inversions" gains the bullet binding the prose list to the test, and the refutation of the repo-wide generalization |
-| `CHANGELOG.md` | `[Unreleased] / Added` |
-
-Decisions taken, and why:
-
-- **Two golden sets, not one.** Item 2 asked for the `cogt → pipelex.providers` edges, but that set alone does not close its own closing argument: a bare `import openai` inside a `cogt` module is not a providers edge, so it would pass. The vendor-free claim is pinned as its own assertion — as an **allowlist of third-party import roots**, not a vendor denylist. Same golden-set shape as the edges, no list of vendor names to keep current, and a new framework dependency surfaces for review as one line rather than slipping through a denylist's gaps.
-- **Edges are addressed by `source -> target [form]`, never by line number.** Line numbers are pure churn. The **form** (`module-level` / `deferred` / `type-checking`) is carried on purpose: promoting the deferred `vertexai_factory` import to module level is a real change — it is what would put the target in every closure touching `backend_factory` — and a set keyed on the statement alone would not see it.
-- **Relative imports are resolved, not skipped.** The sibling neutrality test's helper skips `level > 0`, which is safe there (one directory) but would be a hole here: `from ...providers.openai import x` inside `pipelex/cogt/llm/` resolves to a real edge. Negative-tested with a probe at that exact shape.
-- **The glob convention stays unbound by a test.** Item 1 said one line; softening the comment is the whole fix. A naming rule enforced by machinery is the shape this track spent four review rounds deleting, and the unglobbed-mapping worry is answered by the vendor-free assertion instead — an uncovered mapping module still cannot carry an SDK.
-
-Negative-tested by planting a probe module under `pipelex/cogt/` carrying `import openai`, a module-level provider import, a `TYPE_CHECKING` one and a deferred one: both tests fail, all three forms are classified correctly, and the messages name added/removed rows. A second probe under `pipelex/cogt/llm/` confirmed the relative-import resolution.
-
-**On item 3 (correct the false claim).** The tracker section that carried it no longer exists — the claim survives only in the quote block above, where it is already refuted in place. So the correction was put somewhere durable instead: `docs/contribute/hub-layering.md` now states, in the section whose stated job is keeping the document honest, that the repo-wide generalization is false and why. That is where someone would reason their way to the wrong test; `wip/` is archived at track end.
-
-Gates: `make agent-check`, `make drift-check`, `make agent-test` all green.
-
----
-
-## FU-3 — The bookkeeping files a bulk rewrite breaks are still ungated
-
-> ✅ **DONE** — see [what shipped](#what-shipped-2) at the end of this section.
-
-### Verified: the gate is absent, the artifacts are clean
-
-No sort check and no durations check exist anywhere in `Makefile`, `scripts/` or `tests/` — confirmed by grep across all three. Neither `make check` nor `make agent-check` covers either file.
-
-But both artifacts are healthy right now, so there is no fire:
-
-| artifact | measured 2026-07-28 | verdict |
-| --- | --- | --- |
-| `subject_grants.toml` | grants present, **0 out-of-order pairs** | the `bc22ba934` re-sort holds |
-| `.test_durations` | entries vs live tests collected with `-m ""`; **2 orphan node ids**, **0 dead file paths** | clean |
-
-The two orphans are the `pipe_img_gen` parametrizations keyed on the generated model-set fixture — profile-dependent, already identified as such during F1's third review round, not stale. Live tests carrying no duration entry are expected (tests added since the last `--store-durations` run); pytest-split treats an unknown id as average duration.
-
-So the issue as stated is precisely: **nothing would tell us if it drifted again.** Three instances on the modularity branch, each found by hand well after the fact.
-
-### Recommendation — do the sort check; reshape the durations check before writing it
-
-**Do: the `subject_grants.toml` sort assertion.** It is the one of the three that broke silently and stayed broken across three commits, and it is genuinely trivial — `pipelex/cli/dev_cli/commands/keyword_only_guard.py` already parses the file (`SUBJECT_GRANTS_FILE`, `load_subject_grants()` at `:261`). Add the key-order assertion inside the existing guard so it rides `make check-keyword-only` → `make agent-check` → CI. No new Make target. The invariant is already written down as one in `docs/contribute/keyword-only-arguments.md:37` (*"machine-written and sorted by key"*) — this just enforces what the docs claim.
-
-Note `load_subject_grants()` returns a `dict`, which does not preserve evidence of file order; read the raw text for the key sequence.
-
-**Reshape: gate `.test_durations` on the file path, not the node id.**
-
-A bulk path rewrite breaks **file paths**. Parametrization churn breaks **node ids** and is benign. Asserting `{k.split("::")[0] for k in durations}` all exist on disk is:
-
-- unambiguous — no tolerance policy, no explaining away legitimately-stale parametrizations,
-- **green today** (0 dead paths out of 907 distinct files),
-- cheap — pure filesystem check, no pytest collection run at all.
-
-Whereas a strict node-id check needs a full unfiltered collection *and* a policy for both current false positives.
-
-⚠ **Two traps for whoever writes it**, both of which cost real time already:
-
-- If you do collect node ids for any reason, run with **`-m ""`**. The marker filter in `addopts` hides a large slice of the suite (mostly `tests/e2e/`), so a naive `--collect-only` reports every e2e entry as an orphan.
-- Parse a collect dump with `.splitlines()`, **never `.split()`**. Parametrized ids contain spaces (`[CV Batch-tests/data/graphs/cv_batch.json]`), so whitespace-splitting shreds them into tokens and manufactures hundreds of phantom orphans. I hit this while measuring for this doc — same family as M2's `[a-z_]*` character class, and worse than a rewrite bug, because the verification is what licenses "done".
-
-**Skip the third instance.** The matched triple (guard tuple / closure predicate / `hub-layering.md` snippet) is already mechanically bound by tests as of M1c; only the design doc's fourth copy is unasserted, and that lives in `wip/`, which is archived at track end.
-
-### What shipped
-
-Both measurements re-taken before starting, and both held: no sort or durations check exists in `Makefile` / `scripts/` / `tests/` (the only `.test_durations` mentions are the regeneration target's own comment and two CI workflow comments), and both artifacts are still clean — 1757 grants with **0 out-of-order pairs**, 9242 duration entries across 907 distinct files with **0 dead paths**. Both halves were done, the durations one in the reshaped form the item prescribed.
-
-| file | role |
-| --- | --- |
-| `pipelex/cli/dev_cli/commands/keyword_only_guard.py` | `ViolationKind.UNSORTED_GRANT` + `find_unsorted_grants()` — the registry-order rule |
-| `pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py` | folds the registry-order violations into the full-scan gate |
-| `tests/unit/pipelex/cli/dev/test_subject_grant_registry.py` | `TestSubjectGrantRegistryOrder` |
-| `tests/unit/repo/test_test_durations_paths.py` | the `.test_durations` file-path gate |
-| `docs/contribute/keyword-only-arguments.md`, `Makefile`, `CHANGELOG.md` | docs |
-
-Decisions taken, and why:
-
-- **The order rule reads the raw text, and cross-checks the scan against the parser.** The item warned that `load_subject_grants()` returns a `dict`, which is not evidence of file order. It is worth being precise about *why*, because the shortcut is tempting: CPython dicts do preserve insertion order and `tomllib` does insert in document order, so reading order off the parsed dict would in fact work today — it would just be resting on undocumented behaviour of a parser for a format that declares table order insignificant. So the scan is a line-anchored regex over table headers. That opens its own hole (a multi-line rationale can carry a line that looks like a header), closed by asserting the scanned key set equals the parsed key set and raising `SubjectGrantRegistryError` when it does not. An entry the scan cannot see must fail loudly, not silently drop out of the rule's domain — the FU-1 anti-vacuity concern in a different costume.
-- **Registry order is a full-scan rule, wired at the command layer, not in `collect_all_violations`.** Two reasons. It is a whole-file property, so the per-file `PostToolUse` hook cannot see it — exactly the boundary `dead-grant` already sits on. And `collect_all_violations` is filesystem-pure with respect to the registry (its callers pass `grants` in, and its tests run from a `tmp_path` with no `subject_grants.toml` at all); making it read the registry off disk would have broken four existing tests for no gain.
-- **No re-sorting fixer.** `--fix` rewrites signatures; the registry has exactly one writer, the `subject-grant` command, and the guard module is stdlib-only by design (the writer needs tomlkit). The remedy is stated instead: re-record any grant, which rewrites the whole file sorted.
-- **The durations gate is on the file path only, and not parametrized.** Per the item. The two known orphan node ids are profile-dependent parametrizations, and a node-id gate would need a full unfiltered collection plus a tolerance policy for them; the path gate needs neither, and it is the one that catches a bulk rewrite. Anti-vacuity is a non-parametrized "the file is committed and not empty" test, plus a shape assertion that every key really is `<path.py>::<test>` — without which "every extracted path exists" could pass over keys that are not paths at all.
-- **Both traps in the item were avoided by not collecting node ids at all** — no `-m ""` run, no collect dump to parse, so neither the marker-filter nor the `.split()` trap is reachable. That is a third argument for the path gate the item did not make: the cheap check is also the one with no way to mis-measure.
-
-Negative-tested, all four: swapping two adjacent registry entries fails with the offending key, the registry line number, and the entry it sorts before; a multi-line rationale carrying a phantom `["…"]` header fails with the scan/parser count mismatch; a `.test_durations` entry under a moved-away path fails naming the dead path; a non-node-id key fails the shape assertion. Both real artifacts restored clean afterwards (`git diff --stat` empty).
-
-Docs updated in the same change: `docs/contribute/keyword-only-arguments.md` in five places (the kinds table, the order paragraph under "Staleness is symmetric", the hook bullet, the auto-fix paragraph — which listed only `grant-param-mismatch` as never-rewritten and silently omitted `dead-grant` — and a pointer after the top-of-page rule list, since that list is scoped to *signatures* and registry order is not a signature property); the `store-test-durations` comment in the `Makefile` names its new gate; CHANGELOG under `[Unreleased] / Added`. The `keyword-only-convention` drift contract was reviewed and acked, with its dogfood-log entry.
-
-**Noticed, not fixed:** `make check-test-badge` is red on this branch — badge 9146 vs 9241 collected. It was already off by 88 before this change (7 tests added here), the badge is refreshed at release time by the release skill, and its CI job only runs on PRs into `main`. Bumping it mid-branch would just make it stale differently before the release.
-
----
-
-## Re-verify before starting
-
-Numbers above are dated, not eternal. Re-take them first — the *shape* (zero vs non-zero, present vs absent) is the criterion, not the absolute count.
-
-```bash
-# FU-1 — is error_type still the bare class name? are the four consumers still on the old string?
-git grep -n "error_type=type(self).__name__" -- pipelex/base_exceptions.py
-cd .. && /usr/bin/grep -rn "PipelexInterpreterError" \
- mthds-starter-js/src pipelex-starter-js/src vscode-pipelex/editors playroom/src 2>/dev/null
-
-# FU-2 — the vendor-SDK scan above, plus the cogt edges
-git grep -n "pipelex\.providers" -- pipelex/cogt/
-
-# FU-3 — do the gates exist? are the artifacts still clean?
-git grep -n "test_durations\|sorted" -- Makefile | head
-.venv/bin/python -c "
-import json,pathlib
-d=json.load(open('.test_durations'))
-dead=[f for f in {k.split('::')[0] for k in d} if not pathlib.Path(f).exists()]
-print('dead duration file paths:',len(dead))"
-```
-
-⚠ Use `git grep` or `/usr/bin/grep` for any completeness sweep — this shell's `grep` is a ugrep wrapper that honours `.gitignore`, so from the workspace root it silently skips every sibling repo and returns a false clean.
diff --git a/wip/subject-grants/demoted-public-surfaces.md b/wip/subject-grants/demoted-public-surfaces.md
index d13c371b3..52dc6a7c1 100644
--- a/wip/subject-grants/demoted-public-surfaces.md
+++ b/wip/subject-grants/demoted-public-surfaces.md
@@ -1,11 +1,11 @@
# Demoted public surfaces — release-wave cross-repo sweep handoff
-The subject-grant review demoted every positional first parameter that failed the grant rubric to keyword-only (see `docs/contribute/keyword-only-arguments.md`). No backward compatibility: any external consumer calling these surfaces positionally — or subclassing them with positional signatures — breaks when the release ships. This is the inventory for the release-gated cross-repo sweep; the consumers to check are `pipelex-api`, `pipelex-worker`, the private `pipelex-temporal` plugin, `pipelex-cookbook`, `cocode`, `pipelex-mistralai-workflows`, and any starter/template code.
+The subject-grant review demoted every positional first parameter that failed the grant rubric to keyword-only (see `docs/contribute/keyword-only-arguments.md`). No backward compatibility: any external consumer calling these surfaces positionally — or subclassing them with positional signatures — breaks when the release ships. This is the inventory for the release-gated cross-repo sweep; the consumers to check are `pipelex-api`, `pipelex-cookbook`, `cocode`, our orchestration plugins, our hosted services, and any starter/template code.
## Runtime / execution surfaces
- `pipelex.core.pipes.pipe_abstract.PipeAbstract` run family (`run_pipe`, `live_run_pipe`, `dry_run_pipe`, `validate_before_run`, `validate_after_run`, `needed_inputs`) — `job_metadata` / `visited_pipes` now keyword-only; external code subclassing or invoking pipes positionally breaks.
-- `pipelex.runtime_bridge.bootstrap.ensure_pipelex_booted` (`config_overrides`) — runtime_bridge is consumed by pipelex-api / pipelex-worker; positional callers break.
+- `pipelex.runtime_bridge.bootstrap.ensure_pipelex_booted` (`config_overrides`) — runtime_bridge is consumed by `pipelex-api` and by our hosted services; positional callers break.
- `pipelex.pipeline.pipeline_run_setup.pipeline_run_setup` (`execution_config`) and `pipelex.pipeline.pipeline_manager_abstract.add_new_pipeline` (`pipe_code`).
- `pipelex.libraries.library_manager_abstract.LibraryManagerAbstract` load family (`load_libraries`, `load_from_blueprints`, `load_from_crate`, …) — `library_id` now keyword-only.
- `pipelex.libraries.concept.concept_library_abstract.ConceptLibraryAbstract.is_compatible` / `ConceptLibrary.is_compatible` (`tested_concept`).