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.
Plugins declare their layer through their entry-point group (#1090)
Louis Choqueld382ca0fc660
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex ea68af3b3..de634b02c 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:37b06818f4a4c24d93fd33f5e3bf6e4c344e794e0eeb11333c22f8f32de87f87"+digest = "sha256:ad647a1d23ee55400c773b372ea72ab805d0b9851f4c1944cf2f17ac219c164a"reviewed_by = "Louis Choquel"-reviewed_at = "2026-07-29T17:05:46Z"-rationale = "Trigger is one call site inside the --save-csv block of cli/commands/run/_run_core.py: the CSV row-model lookup moved from Concept.get_structure_class() to ConceptLibrary.make_empty().get_structure_class(concept=...), plus one import line and a comment. No option, default, choice list, exit code, output shape or error class changed — the guard is still except (CsvError, ConceptValueError, OSError) and ConceptStructureClassNotFoundError is a ConceptValueError, so an unresolvable class is still framed as 'Failed to --save-csv to <path>: ...' with exit 1, exactly as before. Grepped both targets for 'structure class', 'structure_class', 'ConceptValueError' and 'concept library': zero hits, structurally so, since docs/tools/cli/ documents the option surface and observable behavior rather than the resolution internals. Verified live: 'pipelex run pipe --help' still renders --save-csv with the same description docs/tools/cli/run.md lines 36/89/136 carry verbatim, and the absence-path paragraph at line 214 (--save-csv fails for any non-flat main output) is untouched by this change. The agent-CLI contract doc has no --save-csv surface at all. Nothing stale."+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."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -104,7 +104,7 @@ rationale = "Trigger is one call site inside the --save-csv block of cli/command"pipelex/cli/commands/init/ui/types.py" = "blob:1361f29ca95bacc90bca90ea6c0e39f44b6734ab""pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/login/command.py" = "blob:ace1db9879626cc1722adaac12761aadaa6b24ed"-"pipelex/cli/commands/plugins_cmd.py" = "blob:6019e102c644ff6adeee6a5b3f1423efc4af39f1"+"pipelex/cli/commands/plugins_cmd.py" = "blob:2980268813f1acf67f0f2cc914ccaff6cae6889b""pipelex/cli/commands/resolve_cmd.py" = "blob:2233ab12b7cd5ef0bce697d9599d13a09e242dde""pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.tomlindex 23d11e989..44d247599 100644--- a/.drift/acks/hub-layering-convention.toml+++ b/.drift/acks/hub-layering-convention.toml@@ -1,10 +1,10 @@contract = "hub-layering-convention"-digest = "sha256:3e809663f592cb1454c7f5b1d7c0d480b63a18c6eed7d710970e7866da27c205"-reviewed_by = "Claude (Opus 5)"-reviewed_at = "2026-08-09T15:30:30Z"-rationale = "Trigger is the rename of the kernel façade class to PipelexKernel, which changed exactly one word in runtime_hub.py: the class named in resolve_run_mode_for_boot's docstring. Reviewed docs/contribute/hub-layering.md and it is already current — the rename commit updated the page atomically, so the paragraph under 'Which hub does a new symbol belong to?' already reads PipelexKernel.make; only the ack digest was stale. Ran both prescribed mechanical checks rather than re-reading the tables, per the standing note in the dogfood log: all 15 packages in RUNTIME_LAYER_PACKAGES are named under Enforcement (the enumeration that rotted seven rounds running is clean — it now includes pipelex.kernel and pipelex.runtime_boot), and all 34 + 32 public module-level hub symbols appear in the partition tables. Also verified the page's concrete references still resolve: resolve_run_mode_for_boot sits beside is_dry_run_forced under 'run mode', and tests/unit/pipelex/kernel/test_kernel_boot_contract.py exists at the path the Enforcement section cites. No doc change needed. The review also turned up six references to the class's old name outside this contract's targets, in wip/parity/README.md and wip/parity/parity-gaps-plan.md, which arrived via the dev merge; those were renamed in the same change, so the old name is now gone from the working tree entirely."+digest = "sha256:3e934627754b382f5fc30bb5ebc920c258d7f8056283b4d7b1cdcd748710fb21"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-08-10T12:22:31Z"+rationale = "Trigger is a one-word rename leftover in hub_layering_guard.py's module-entry comment: it called pipelex.runtime_boot 'the runtime layer's composition root' while the same sentence went on to say what 'boot the kernel layer' costs — two names for one boundary in one sentence, in the file that defines the boundary. It survived the A0 sweep because the phrase spans a line break, so a line-oriented grep for 'runtime layer' could not see it. Reviewed docs/contribute/hub-layering.md end to end against the guard. The page carries no stale layer vocabulary (verified: zero hits for 'runtime layer' / 'runtime-layer'), and its declared-package list still matches KERNEL_LAYER_PACKAGES. One substantive edit, and it was a genuine contradiction rather than vocabulary: the paragraph on external plugins stated they are 'discovered through the pipelex.plugins entry-point group — a group identifier, not a module path, and unchanged', which is now false twice over (that group is retired and fails startup, and plugins declare their layer by choosing between two successors). The A3 doc sweep had deliberately left pipelex.plugins alone on this page because it is also the kernel-layer package name, and that carve-out over-applied to the one sentence that was explicitly about the group. Rewrote it to name both successor groups and added a parenthetical warning the reader that every OTHER mention of pipelex.plugins on the page is the package sense, since the collision is exactly the trap the carve-out was protecting against."[trigger_files]-"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:151bee2b65ca3717b09f754d2e30aad830894f43"-"pipelex/interpreter_hub.py" = "blob:b7ac885d348d32f1aa4b1e660da5b03533fb305b"-"pipelex/runtime_hub.py" = "blob:b5eab6810174435eb1e40aa1b1cd29a103af58be"+"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:2dbadcbab7d44364a7b5f1d16268b23b26700a00"+"pipelex/interpreter_hub.py" = "blob:5db8f932bfb7161c86c4a3ea68e2a918b40b0b67"+"pipelex/runtime_hub.py" = "blob:7f538d2acb10f263d7e1b6907b42d37199cbc654"diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex 925e36e42..5f10e9897 100644--- a/.drift/acks/pipelex-kernel-docs.toml+++ b/.drift/acks/pipelex-kernel-docs.toml@@ -1,11 +1,11 @@contract = "pipelex-kernel-docs"-digest = "sha256:e52331097d39ad087ae7b63711abf7409c99f9ccc7e68d5da2ef7175eaed12ca"-reviewed_by = "Claude (Opus 5)"-reviewed_at = "2026-08-09T15:59:15Z"-rationale = "Two failures, one cause. The contract had no ack and a stray ack file sat under its pre-rename id: the class rename swept drift.toml and the ack file's own 'contract' field but not the FILE's name, and the tool keys acks by filename. Renamed the file with git mv rather than hand-editing it, which restored the recorded 2026-08-03 review and reduced the failure to the honest one — triggers changed since that ack. Those changes are rename-only: kernel/__init__.py, pipelex_kernel.py and the boot-contract test each carry the class and module rename and nothing else, and the review target was already swept in the same commit. Reviewed docs/under-the-hood/pipelex-kernel.md against the page's own standing rule (every kernel entry point owes the boot-contract subprocess an arm) by enumerating the package rather than reading the table: all 29 public module-level functions across 18 modules are accounted for, and the boot-contract subprocess imports every operator entry point (run_*, build_*, assemble_*) plus the facade, with the remaining names being internal helpers those ops call transitively. One real gap found and fixed: the table under 'What a programmatic caller imports' had a row for every module except prompt_references, while assemble_llm_prompt and assemble_img_gen_prompt both require the caller to construct ImageReference / DocumentReference values — so the page omitted a module its own entry points oblige a caller to import. Added the row. Pre-existing rather than trigger-induced; fixed because the table states a completeness claim."+digest = "sha256:5caf168f4ee9351e5e24dd1f8e2a836f3038607b1202330e4b2d4c09e39b4273"+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."[trigger_files]-"pipelex/kernel/__init__.py" = "blob:e513f4ddae722980c268c0d908f55b7752332cec"+"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce""pipelex/kernel/compose_ops.py" = "blob:28e80623d5e454a1b8f0612a27a28a6ddc73c5de""pipelex/kernel/compose_results.py" = "blob:a837ae9680c7d4d0eb4dee37d4657c410e5b5cea""pipelex/kernel/exceptions.py" = "blob:45e9ad60c2699f7b57cad0a46c13f0b07b4cfbc9"@@ -17,11 +17,11 @@ rationale = "Two failures, one cause. The contract had no ack and a stray ack fi"pipelex/kernel/img_gen_prompt.py" = "blob:90c33eae95298aa76d036f256ffc7d6523249166""pipelex/kernel/img_gen_results.py" = "blob:46b4ca11c70d906ae6d58ce66461f9b3414f1bfa""pipelex/kernel/llm_ops.py" = "blob:36a2e2f3a002e0c50ef4f645937b66573e46aa51"-"pipelex/kernel/llm_prompt_content.py" = "blob:d1d44863aec6e3c4a1451bb25b9586e6d24ef06c"+"pipelex/kernel/llm_prompt_content.py" = "blob:26dfce734de582320c0ea7b9a09b01f2d1ca8627""pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d""pipelex/kernel/memory_ops.py" = "blob:c4d7fee0a5ac2c1292ad39d2c188b2a02b47d15b"-"pipelex/kernel/pipelex_kernel.py" = "blob:abcdf8ca64f29666c3c51fba61287ef80865e5d1"-"pipelex/kernel/prompt_references.py" = "blob:9af4077adcb49abacef98d0100ab9cab14d24880"+"pipelex/kernel/pipelex_kernel.py" = "blob:ad13e02168590a1173d7db1e210b3cecd7059651"+"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:bd9f512eca935f9fae1288fb7a6aa41342f9289e"+"tests/unit/pipelex/kernel/test_kernel_boot_contract.py" = "blob:78947be625cb143c2a5d76a9761ed637d91a9469"diff --git a/.test_durations b/.test_durationsindex c0e0b79a5..2078255aa 100644--- a/.test_durations+++ b/.test_durations@@ -1825,21 +1825,21 @@"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_dead_hub_import_is_a_violation_in_every_layer": 0.0010331250232411548,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_dead_hub_is_not_exempt_inside_type_checking": 0.000853000019560568,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_dead_hub_string_literal_is_a_violation_in_tests_too": 0.0005966250173514709,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_declared_runtime_layer_names_only_real_packages": 0.001149834002717398,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_declared_kernel_layer_names_only_real_packages": 0.001149834002717398,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_escape_hatch_suppresses_a_violation": 0.0009440830035600811,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_every_kind_names_a_remedy": 0.07925262599019334,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_interpreter_layer_may_import_interpreter_hub": 0.0007802080071996897,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_multi_name_import_reports_one_violation": 0.0007087500125635415,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_negated_type_checking_is_not_exempt": 0.0007722500013187528,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_no_interpreter_package_is_declared_runtime_layer": 0.0008499589748680592,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_no_interpreter_package_is_declared_kernel_layer": 0.0008499589748680592,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_plain_import_and_from_package_forms_are_caught": 0.0011733740102499723,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_prose_mentioning_the_hub_is_not_a_reference": 0.0006024999893270433,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_relative_import_of_interpreter_hub_is_caught": 0.001119916996685788,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_runtime_else_branch_of_type_checking_is_not_exempt": 0.0007403330237139016,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_runtime_hub_is_not_matched_by_the_dead_hub_rule": 0.0007267500041052699,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_runtime_layer_importing_interpreter_hub_is_a_violation": 0.0007701249996898696,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_runtime_layer_may_import_runtime_hub": 0.0011514150100992993,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_runtime_layer_membership": 0.7392214570136275,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_kernel_layer_importing_interpreter_hub_is_a_violation": 0.0007701249996898696,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_kernel_layer_may_import_runtime_hub": 0.0011514150100992993,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_kernel_layer_membership": 0.7392214570136275,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_string_literal_attribute_path_is_caught": 0.0008994170057121664,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_string_literal_import_module_form_is_caught": 0.0009095410059671849,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_tests_may_reference_the_interpreter_hub": 0.001141207991167903,@@ -1848,7 +1848,7 @@"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_plugin_split_left_both_halves_declared": 0.0007403749914374202,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_type_checking_import_is_exempt_from_the_layer_rule": 0.0010392910044174641,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_type_checking_on_an_unrelated_receiver_is_not_exempt": 0.0004936249897582456,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py::TestHubLayeringGuardFilesystem::test_a_runtime_layer_package_init_is_inside_its_own_layer": 0.0024265819956781343,+ "tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py::TestHubLayeringGuardFilesystem::test_a_kernel_layer_package_init_is_inside_its_own_layer": 0.0024265819956781343,"tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py::TestHubLayeringGuardFilesystem::test_full_scan_reports_exactly_the_real_offenders": 0.8037165419955272,"tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py::TestHubLayeringGuardFilesystem::test_module_qname_for[pipelex/__init__.py-pipelex]": 0.0004001659981440753,"tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py::TestHubLayeringGuardFilesystem::test_module_qname_for[pipelex/cogt/sample/__init__.py-pipelex.cogt.sample]": 0.0007942089869175106,@@ -1869,7 +1869,7 @@"tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_an_edge_that_does_not_load_is_not_an_edge[function_body-def make():\\n from pipelex.runtime_bridge.orchestrator import DirectOrchestrator\\n\\n return DirectOrchestrator\\n]": 0.005607208993751556,"tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_an_edge_that_does_not_load_is_not_an_edge[type_checking-from typing import TYPE_CHECKING\\n\\nif TYPE_CHECKING:\\n from pipelex.runtime_bridge.orchestrator import DirectOrchestrator\\n]": 0.005612207998638041,"tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_an_imported_symbol_resolves_to_the_module_that_holds_it": 0.005081166003947146,- "tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_reports_exactly_the_runtime_layer_modules_that_reach_the_hub": 0.7274293739901623,+ "tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_reports_exactly_the_kernel_layer_modules_that_reach_the_hub": 0.7274293739901623,"tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_the_reported_chain_is_the_shortest_one": 0.003954960004193708,"tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py::TestHubLayeringTransitiveRule::test_the_reported_line_is_the_first_hop": 0.00250508300086949,"tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py::TestKeywordOnlyGuardFix::test_annotations_and_default_preserved": 0.0011140830029034987,@@ -7789,8 +7789,8 @@"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_every_pipe_kind_declares_the_factory_that_gets_looked_up_for_it": 0.7317538329807576,"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_every_registered_model_is_live_in_the_booted_class_registry": 0.11581520800245926,"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_no_two_registered_models_share_a_class_name": 0.00035233299422543496,- "tests/unit/pipelex/test_runtime_boot_closure.py::TestBootedRuntimeLayer::test_booting_the_runtime_layer_loads_no_interpreter_module_and_installs_no_interpreter_hub": 1.2291789169976255,- "tests/unit/pipelex/test_runtime_boot_closure.py::TestBootedRuntimeLayer::test_the_sweep_still_detects_a_package_the_runtime_boot_really_loads": 1.8240968320023967,+ "tests/unit/pipelex/test_runtime_boot_closure.py::TestBootedKernelLayer::test_booting_the_kernel_layer_loads_no_interpreter_module_and_installs_no_interpreter_hub": 1.2291789169976255,+ "tests/unit/pipelex/test_runtime_boot_closure.py::TestBootedKernelLayer::test_the_sweep_still_detects_a_package_the_runtime_boot_really_loads": 1.8240968320023967,"tests/unit/pipelex/test_runtime_boot_config_dir.py::TestConfigDirReachesTheConfigLoader::test_an_explicit_config_dir_is_what_gets_loaded": 2.1690609590004897,"tests/unit/pipelex/test_runtime_boot_exclusivity.py::TestRuntimeBootAndPipelexAreOneProcessGlobal::test_a_full_boot_refuses_on_top_of_a_runtime_boot_and_succeeds_once_it_is_torn_down": 3.2020130829914706,"tests/unit/pipelex/test_runtime_boot_exclusivity.py::TestRuntimeBootAndPipelexAreOneProcessGlobal::test_a_runtime_boot_is_visible_through_the_subclass_resolved_accessors": 0.13579641700198408,@@ -7801,20 +7801,20 @@"tests/unit/pipelex/test_runtime_boot_failed_boot_release.py::TestFailedBootReleasesTheTelemetrySingleton::test_an_injected_telemetry_manager_that_raises_does_not_abort_the_other_releases": 1.4761100839969004,"tests/unit/pipelex/test_runtime_boot_teardown_resilience.py::TestAFailingTeardownLeavesTheProcessRebootable::test_a_raising_pipeline_manager_teardown_still_runs_the_runtime_teardown": 1.57575704199553,"tests/unit/pipelex/test_runtime_boot_teardown_resilience.py::TestAFailingTeardownLeavesTheProcessRebootable::test_a_raising_telemetry_teardown_still_releases_the_boot_singleton": 2.245808332998422,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.cogt.content_generation.content_generator-0]": 1.487770791980438,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.concepts.structure_generation.generator-0]": 0.30047537400969304,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.memory.input_shaper-0]": 0.529244707984617,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.memory.working_memory_factory-0]": 0.9714919999969425,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.pipes.inputs.input_stuff_specs_factory-0]": 0.4276924580044579,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.pipes.stuff_spec.stuff_spec_factory-0]": 0.36423125000146683,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.stuffs.stuff_factory-0]": 0.5412622920121066,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.interpreter_hub-1]": 0.6388662910176208,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.providers.anthropic.anthropic_list-0]": 0.5581448339944473,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.providers.builtins-0]": 0.5581283750070725,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.runtime_boot-0]": 0.9579149590135785,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.runtime_hub-0]": 0.6238735410006484,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_every_configured_interpreter_package_is_real": 0.0005804169923067093,- "tests/unit/pipelex/test_runtime_layer_import_closure.py::TestHubImportClosure::test_the_interpreter_package_set_matches_the_documented_one": 0.10820541600696743,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.cogt.content_generation.content_generator-0]": 1.487770791980438,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.concepts.structure_generation.generator-0]": 0.30047537400969304,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.memory.input_shaper-0]": 0.529244707984617,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.memory.working_memory_factory-0]": 0.9714919999969425,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.pipes.inputs.input_stuff_specs_factory-0]": 0.4276924580044579,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.pipes.stuff_spec.stuff_spec_factory-0]": 0.36423125000146683,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.core.stuffs.stuff_factory-0]": 0.5412622920121066,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.interpreter_hub-1]": 0.6388662910176208,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.providers.anthropic.anthropic_list-0]": 0.5581448339944473,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.providers.builtins-0]": 0.5581283750070725,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.runtime_boot-0]": 0.9579149590135785,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_closure_verdict_for_entry_point[pipelex.runtime_hub-0]": 0.6238735410006484,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_every_configured_interpreter_package_is_real": 0.0005804169923067093,+ "tests/unit/pipelex/test_kernel_layer_import_closure.py::TestHubImportClosure::test_the_interpreter_package_set_matches_the_documented_one": 0.10820541600696743,"tests/unit/pipelex/test_suggested_fix.py::TestSuggestedFixModels::test_enum_fields_serialize_to_plain_strings": 0.0008971680072136223,"tests/unit/pipelex/test_suggested_fix.py::TestSuggestedFixModels::test_non_fixable_item_stays_byte_identical": 0.0003232909948565066,"tests/unit/pipelex/test_suggested_fix.py::TestSuggestedFixModels::test_round_trip_preserves_all_fields": 0.9428620000107912,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a98a198e7..e567d2ced 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,13 +4,16 @@### 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 runtime-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`)**: 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.### Changed+- **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 runtime-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.+- **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.diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.mdindex 1baeaad09..fe5502fc2 100644--- a/docs/contribute/hub-layering.md+++ b/docs/contribute/hub-layering.md@@ -9,10 +9,12 @@ Pipelex resolves its cross-cutting dependencies through a *hub*: a singleton conThe two layers are the textbook language-implementation split:-- **The runtime layer** is the machinery present at execution time whatever is loaded — config, console, secrets, storage, telemetry, the model deck and inference workers, the content generator, reporting, and the value data model. Its hub is `runtime_hub`.+- **The kernel layer** is the machinery present at execution time whatever is loaded — config, console, secrets, storage, telemetry, the model deck and inference workers, the content generator, reporting, and the value data model. Its hub is `runtime_hub`.- **The interpreter layer** reads a method and executes it — the libraries, the pipes, the router, the pipeline manager. Its hub is `interpreter_hub`.-Do not read `runtime_hub` as related to the `pipelex.runtime_bridge` package: they share a word, but the hub is the runtime layer's service container while `runtime_bridge` is a transport.+Do not read `runtime_hub` as related to the `pipelex.runtime_bridge` package: they share a word, but the hub is the kernel layer's service container while `runtime_bridge` is a transport.++The layer used to be called the *runtime* layer, and two module names still carry that former name: `runtime_hub` (the kernel layer's hub) and `runtime_boot` (its composition root). They are pinned across repo boundaries, so they are renamed when the kernel layer moves into its own package rather than piecemeal. `runtime_bridge` means "runtime" in the orchestration-venue sense and keeps the word for good.## The one rule@@ -20,7 +22,7 @@ Do not read `runtime_hub` as related to the `pipelex.runtime_bridge` package: thThat single arrow is the whole architecture. Everything below is a consequence of it.-Only the *forbidden* direction is load-bearing. The permitted one is currently unused: the one runtime-layer thing `interpreter_hub` needs is the class-registry scoping slot, which lives below *both* hubs (see [The class-registry exception](#the-class-registry-exception)). So today, importing either hub loads the other in neither direction — which is stronger than the rule requires, not a violation of it.+Only the *forbidden* direction is load-bearing. The permitted one is currently unused: the one kernel-layer thing `interpreter_hub` needs is the class-registry scoping slot, which lives below *both* hubs (see [The class-registry exception](#the-class-registry-exception)). So today, importing either hub loads the other in neither direction — which is stronger than the rule requires, not a violation of it.There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as an alias for either layer, so a stale import fails loudly at import time instead of silently resolving to the wrong layer.@@ -73,15 +75,15 @@ Ask **what its lifecycle is**, not what package it happens to be typed by:Placement is decided by *kind*, not by who currently imports it. Several accessors have no in-tree importer (`get_bundle_validator_registry`, `get_orchestrator_registry`, `get_default_library_dirs`, …) — they are live plugin contract and are reached through the container. Do not relocate or delete one because a grep looks empty.-`get_pipe_func_executor_registry` is the one placement worth flagging: it is a plugin registry by kind (which would put it in the runtime layer) but its protocol lives in `pipe_operators/func/` (which puts it in the interpreter layer). It is **interpreter-layer**. See [Known inversions](#known-inversions) for the underlying wart.+`get_pipe_func_executor_registry` is the one placement worth flagging: it is a plugin registry by kind (which would put it in the kernel layer) but its protocol lives in `pipe_operators/func/` (which puts it in the interpreter layer). It is **interpreter-layer**. See [Known inversions](#known-inversions) for the underlying wart.-Not everything a hub module exports is an accessor. `resolve_run_mode_for_boot` *applies* the keyless-boot forced-DRY flag rather than reading it, and it lives beside `is_dry_run_forced`, the accessor it consumes. The lifecycle question above still decides placement — the flag is set once at boot and identical for every method the process runs, so the rule that interprets it is runtime-layer by kind. What makes the *module* the right home rather than either caller is that there are now two: the pipe tier's `PipeRunParamsFactory.make_run_params` and the kernel tier's `PipelexKernel.make` both mint run params, and a boot-scoped invariant copied into each is one that drifts. When a rule over hub state acquires a second caller, move the rule to the hub — do not let the second caller reimplement it.+Not everything a hub module exports is an accessor. `resolve_run_mode_for_boot` *applies* the keyless-boot forced-DRY flag rather than reading it, and it lives beside `is_dry_run_forced`, the accessor it consumes. The lifecycle question above still decides placement — the flag is set once at boot and identical for every method the process runs, so the rule that interprets it is kernel-layer by kind. What makes the *module* the right home rather than either caller is that there are now two: the pipe tier's `PipeRunParamsFactory.make_run_params` and the kernel tier's `PipelexKernel.make` both mint run params, and a boot-scoped invariant copied into each is one that drifts. When a rule over hub state acquires a second caller, move the rule to the hub — do not let the second caller reimplement it.## Why the boundary exists`runtime_hub` must not name anything from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `interpreter_plugins`, `pipe_machinery`, `pipe_signature`, `mthds_parsing`, `pipeline` or `pipe_run` at module level. That list is now stated in whole top-level packages, which is the point of the modularity moves: it used to have to trail "…or the Pipe-touching modules of `core.pipes`", because some of what it forbids lived under a runtime-named package. Those module-level imports exist only to type the getters, but they are what made a single hub drag the entire method interpreter into every consumer that just wanted `get_console()`.-The property that matters is measurable: **importing the Pipelex runtime loads zero modules from any of the packages named above.** That is both the assertion the closure test pins and the outward-facing claim — the inference engine does not know the MTHDS language exists, so you can embed it without loading a line of the parser, the pipe machinery, or a single pipe kind. Verify it from the repo root on a synced venv:+The property that matters is measurable: **importing the Pipelex kernel layer loads zero modules from any of the packages named above.** That is both the assertion the closure test pins and the outward-facing claim — the inference engine does not know the MTHDS language exists, so you can embed it without loading a line of the parser, the pipe machinery, or a single pipe kind. Verify it from the repo root on a synced venv:```bash.venv/bin/python - <<'PY'@@ -107,16 +109,16 @@ PY## Where core splits-`pipelex/core/` used to be two layers under one name, and the runtime-layer declaration had to work around it. It does not any more — `pipelex.core` is a single declared entry — but the split is worth recording, because *how* it was resolved is the general lesson.+`pipelex/core/` used to be two layers under one name, and the kernel-layer declaration had to work around it. It does not any more — `pipelex.core` is a single declared entry — but the split is worth recording, because *how* it was resolved is the general lesson.For a long time `core/` held two different kinds of thing:- **The data model — runtime.** `core.concepts`, `core.domains`, `core.stuffs`, `core.memory`, the input/output *specs* under `core.pipes.inputs` and `core.pipes.stuff_spec`, and `core.pipes.pipe_output`. These describe what a method's values *are*. Nothing in them needs a loaded method, and each measures **zero** modules from the packages the predicate names. `pipe_output` reads as Pipe machinery but is not: it names no `Pipe` — it holds the working memory, graph spec and usage a run *produced* — and it sits inside `runtime_hub`'s own closure (the chain under [The class-registry exception](#the-class-registry-exception) passes straight through it).-- **The Pipe machinery — interpreter.** `pipe_abstract`, `pipe_blueprint`, `pipe_factory`, `validation`, `template_guard_lint` and the two renderers. Every one of them names a `Pipe`, and a pipe is the interpreter's own object — they import `pipe_operators` / `pipe_controllers` / `libraries` **directly**, not through a hub. No amount of dependency injection makes those runtime.+- **The Pipe machinery — interpreter.** `pipe_abstract`, `pipe_blueprint`, `pipe_factory`, `validation`, `template_guard_lint` and the two renderers. Every one of them names a `Pipe`, and a pipe is the interpreter's own object — they import `pipe_operators` / `pipe_controllers` / `libraries` **directly**, not through a hub. No amount of dependency injection makes those kernel-layer.**The resolution was to move the second kind out, not to describe it more precisely.** All of it now lives in two top-level packages of its own: `pipelex.pipe_machinery` holds the Pipe machinery proper plus the pipe-kind registration manifest (`registry_models.PipeRegistryModels` — the fattest edge of the lot, a list of every pipe class and every pipe factory, so importing it loaded the whole interpreter), and `pipelex.mthds_parsing` holds the MTHDS parser and the bundle blueprint it produces, whose `pipelex_bundle_blueprint` is a discriminated union over every pipe blueprint. See [Registration surface](registration-surface.md) for what adding a pipe kind touches.-One model stayed behind on purpose, and it is the interesting case. `PipelexBundleBlueprintValidationErrorData` is raised by the parser but imported by `pipeline/` and `libraries/`, which carry it into every runtime-layer import closure. Filing it with the parser would have made the boundary unenforceable for `mthds_parsing` — the closure predicate would have needed a permanent exclusion for it. It lives in `core.exceptions` instead, beside the two sibling structured error-data models it shares `PipeValidationErrorType` with. **Moving the leaf is what buys the clean predicate**; excluding it would only have recorded the problem.+One model stayed behind on purpose, and it is the interesting case. `PipelexBundleBlueprintValidationErrorData` is raised by the parser but imported by `pipeline/` and `libraries/`, which carry it into every kernel-layer import closure. Filing it with the parser would have made the boundary unenforceable for `mthds_parsing` — the closure predicate would have needed a permanent exclusion for it. It lives in `core.exceptions` instead, beside the two sibling structured error-data models it shares `PipeValidationErrorType` with. **Moving the leaf is what buys the clean predicate**; excluding it would only have recorded the problem.So the declaration names `pipelex.core` wholesale, which is a claim the measurement now supports: every `pipelex.core.*` module loads zero modules from the interpreter packages the predicate names, and none reaches `interpreter_hub`. It once listed core's data-model packages one by one, and that enumeration was the shape of the problem — a package-granular declaration is only honest when the packages match the layers.@@ -135,52 +137,52 @@ Two shapes fall out of that, and they are the ones to copy:- **Compatibility is two tiers, composed by the thing that owns resolution.** `Concept.are_compatible_by_declaration` is pure over the model's fields (plus an injected `concept_resolver`): dynamic short-circuits, ref equality, declared-class-name equality, `refines` chains. `ConceptLibrary.is_compatible` asks that first and only resolves classes when it is inconclusive. A name that should have resolved and didn't now raises `ConceptStructureClassNotFoundError` instead of answering `False` — "unknown" and "incompatible" are different answers, and conflating them was a latent wrong-verdict bug.- **Rendering takes the resolved class, not the name.** `Concept.render_concept_representation` receives a `structure_class`; `StuffSpec.render_stuff_spec` takes the `concept_provider`, resolves once, and passes the class down. Interpreter-layer callers (`output_renderer`, `input_renderer`, `pipe_io_contracts`, `builder/runner_code`) supply `get_concept_library()`.-The **write side** stays ambient on purpose: `concept_factory` and `structure_generation/generator.py` generate structure classes and register them at library-load time, which is genuinely the registry's business. That those two are the only modules under `pipelex/core/concepts/` touching the registry is pinned as a golden set by `tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py` — nothing else can see it, since both the accessor and its users are runtime-layer.+The **write side** stays ambient on purpose: `concept_factory` and `structure_generation/generator.py` generate structure classes and register them at library-load time, which is genuinely the registry's business. That those two are the only modules under `pipelex/core/concepts/` touching the registry is pinned as a golden set by `tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py` — nothing else can see it, since both the accessor and its users are kernel-layer.It is **read-side only**. Managing a library — adding, removing, listing, setup/teardown — stays in the interpreter layer: `ConceptLibraryAbstract` *extends* it, keeping its management half in `libraries/`. Splitting read from write is what lets a core module state its dependency honestly ("I need something that can resolve concepts") without inheriting a library lifecycle it has no business touching.-**There is deliberately no pipe counterpart.** Nothing in core's runtime half resolves a pipe. The two places that follow a pipe reference found *inside* a pipe graph — a condition's mapped pipes, a sequence's last step — live in `pipe_machinery/rendering/`, which is interpreter-layer and calls `interpreter_hub.get_required_pipe` directly; a provider parameter there would buy no closure property. `get_required_pipe` therefore stays on `PipeLibraryAbstract`. Split a read half out when a runtime-layer caller actually needs one, not for symmetry with concepts.+**There is deliberately no pipe counterpart.** Nothing in core's kernel half resolves a pipe. The two places that follow a pipe reference found *inside* a pipe graph — a condition's mapped pipes, a sequence's last step — live in `pipe_machinery/rendering/`, which is interpreter-layer and calls `interpreter_hub.get_required_pipe` directly; a provider parameter there would buy no closure property. `get_required_pipe` therefore stays on `PipeLibraryAbstract`. Split a read half out when a kernel-layer caller actually needs one, not for symmetry with concepts.The injection point is the interpreter layer. `pipe_factory`, `input_renderer` and `output_renderer` — already interpreter-bound, so nothing is lost — resolve the concept library themselves and pass it down; `pipeline/execution_seams.py` does the same for `WorkingMemoryFactory`. That is the one-way arrow the whole design rests on, applied inside `core/`: **the half that knows about a loaded method resolves the collaborator and hands it downward.**When you add a core data-model function that needs a concept — or a concept's structure class — add a `concept_provider` parameter. Do not add a hub import, and do not reach for `get_class_registry()`: the guard will reject the first, and the second is the coupling this section exists to describe.-One module outside `core/` cannot import either hub at module level, and the constraint is a **static-analysis** cycle rather than a runtime one — worth knowing before you restate it. `pipe_machinery/pipe_abstract.py` reads `class_registry_access` directly to decorate graph-registry entries with a JSON Schema. It is *not* in `runtime_hub`'s runtime closure (`plugins.orchestrator_registry` and `pipe_run.pipe_job` reach it through `TYPE_CHECKING`-only edges, and a clean-interpreter probe shows all three absent) — but pyright's `reportImportCycles` counts those edges, so either hub import is a hard type-check failure, reported at `interpreter_hub.py` where no line-level ignore can reach it. Deferring the import does not dodge it. The below-both-hubs accessor is what that case is for; its docstring records the measurement.+One module outside `core/` cannot import either hub at module level, and the constraint is a **static-analysis** cycle rather than a runtime one — worth knowing before you restate it. `pipe_machinery/pipe_abstract.py` reads `class_registry_access` directly to decorate graph-registry entries with a JSON Schema. It is *not* in `runtime_hub`'s kernel closure (`plugins.orchestrator_registry` and `pipe_run.pipe_job` reach it through `TYPE_CHECKING`-only edges, and a clean-interpreter probe shows all three absent) — but pyright's `reportImportCycles` counts those edges, so either hub import is a hard type-check failure, reported at `interpreter_hub.py` where no line-level ignore can reach it. Deferring the import does not dodge it. The below-both-hubs accessor is what that case is for; its docstring records the measurement.## Where the built-in plugins split-Two different splits run through the built-in plugins, and they are easy to conflate. The first is **mechanism vs adapters**, and it does *not* cross a layer boundary: `pipelex/plugins/` is the plugin mechanism — the `PipelexPlugin` contract, the `PluginRegistrar`, and the capability registries the registrar accumulates into — while `pipelex/providers/` holds the built-in adapters that register through it, one directory per provider. Both packages are declared runtime-layer. What the split makes visible is the one-way dependency between them: adapters depend on the mechanism, and the mechanism knows nothing of its adapters. It also stops `pipelex/plugins/` from reading as "the vendors", which is what made the second split hard to see. Note the scope of that claim — it is about these two packages, not about the whole tree: `cogt` does name four providers directly, which [Known inversions](#known-inversions) records and justifies.+Two different splits run through the built-in plugins, and they are easy to conflate. The first is **mechanism vs adapters**, and it does *not* cross a layer boundary: `pipelex/plugins/` is the plugin mechanism — the `PipelexPlugin` contract, the `PluginRegistrar`, and the capability registries the registrar accumulates into — while `pipelex/providers/` holds the built-in adapters that register through it, one directory per provider. Both packages are declared kernel-layer. What the split makes visible is the one-way dependency between them: adapters depend on the mechanism, and the mechanism knows nothing of its adapters. It also stops `pipelex/plugins/` from reading as "the vendors", which is what made the second split hard to see. Note the scope of that claim — it is about these two packages, not about the whole tree: `cogt` does name four providers directly, which [Known inversions](#known-inversions) records and justifies.Most of those directories are vendor adapters, but not all of them, which is why the package is `providers/` and not `vendors/`: `providers/secrets/` registers the built-in `env` backend, which has no vendor at all, and `providers/storage/` registers local, in-memory, S3 and GCP behind one directory. In both cases only the registration shim lives here — the implementations are under `pipelex/tools/`.-The second split *is* the layer boundary, and the same rule of thumb divides it. Most built-ins adapt a runtime-layer port — an inference backend, a model lister, a storage or secrets provider — and those are the packages under `pipelex/providers/`. Two adapt interpreter-layer ports, because their job is to *construct* interpreter-layer objects: `DirectOrchestratorPlugin` registers a `DirectOrchestrator` and a `DirectBundleValidator`, and `PipeFuncPlugin` registers a concrete `DirectPipeFuncExecutor`. Those two live in **`pipelex/interpreter_plugins/`**.+The second split *is* the layer boundary, and the same rule of thumb divides it. Most built-ins adapt a kernel-layer port — an inference backend, a model lister, a storage or secrets provider — and those are the packages under `pipelex/providers/`. Two adapt interpreter-layer ports, because their job is to *construct* interpreter-layer objects: `DirectOrchestratorPlugin` registers a `DirectOrchestrator` and a `DirectBundleValidator`, and `PipeFuncPlugin` registers a concrete `DirectPipeFuncExecutor`. Those two live in **`pipelex/interpreter_plugins/`**.-External plugins are unaffected by the mechanism/adapter split: they import `pipelex.plugins.contract` and `pipelex.plugins.registrar`, both of which stayed put, and they are discovered through the `pipelex.plugins` entry-point group — a group identifier, not a module path, and unchanged.+External plugins are unaffected by the mechanism/adapter split: they import `pipelex.plugins.contract` and `pipelex.plugins.registrar`, both of which stayed put. They are, however, affected by the *layer* split — they are discovered through the two `pipelex.plugins.kernel` / `pipelex.plugins.interpreter` entry-point groups, which are group identifiers rather than module paths, and a plugin declares its layer by choosing one. (Careful: `pipelex.plugins` is also the name of the kernel-layer *package* holding the mechanism, and that is the sense every other mention of it on this page carries — the declared-package list, the transitive-breach worked example, the closure-test entry points. A package name and an entry-point group are unrelated things that happen to share a spelling. The single pre-split group of that name is retired and now fails startup.)-The registrar's slots are *ports* and they stay runtime-layer — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live under `plugins/*_registry.py`. Only the *adapters* are interpreter-layer. That is ordinary ports-and-adapters, and it is what the layer rule's own remedy text prescribes: have the interpreter layer install it downward at boot. Where each derived registry is *installed* still follows the hub partition rather than the port's home: `RuntimeBoot.setup` puts the orchestrator, bundle-validator, backend, lister, storage and secrets registries on the `RuntimeHub`, and `Pipelex.setup` puts the `PipeFuncExecutorRegistry` on the `InterpreterHub` — the one placement flagged [above](#which-hub-does-a-new-symbol-belong-to). Since [the boot split](#where-the-boot-splits) the two installs sit in the two halves that match their hubs, so the partition is now visible in the code rather than only in this sentence.+The registrar's slots are *ports* and they stay kernel-layer — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live under `plugins/*_registry.py`. Only the *adapters* are interpreter-layer. That is ordinary ports-and-adapters, and it is what the layer rule's own remedy text prescribes: have the interpreter layer install it downward at boot. Where each derived registry is *installed* still follows the hub partition rather than the port's home: `RuntimeBoot.setup` puts the orchestrator, bundle-validator, backend, lister, storage and secrets registries on the `RuntimeHub`, and `Pipelex.setup` puts the `PipeFuncExecutorRegistry` on the `InterpreterHub` — the one placement flagged [above](#which-hub-does-a-new-symbol-belong-to). Since [the boot split](#where-the-boot-splits) the two installs sit in the two halves that match their hubs, so the partition is now visible in the code rather than only in this sentence.-Composition happens where welding is legal. `pipelex/providers/builtins.py` exports `RUNTIME_BUILTIN_PLUGINS`; `pipelex/interpreter_plugins/builtins.py` imports that half — downward, which the interpreter layer may do — and exports the composed `BUILTIN_PLUGINS` and `CORE_UNCONDITIONAL_PLUGIN_NAMES`. Both are **parameters** of `build_registrar`, never module globals it imports, so `plugins/discovery.py` stays runtime-layer: `pipelex.py` (the interpreter boot) and the `pipelex plugins list` diagnostic pass the composed lists in, while `runtime_boot.py` defaults to the runtime half alone. Exactly one place still answers "what are the built-in plugins" — it just lives in the layer permitted to say it.+Composition happens where welding is legal. `pipelex/providers/builtins.py` exports `KERNEL_BUILTIN_PLUGINS`; `pipelex/interpreter_plugins/builtins.py` imports that half — downward, which the interpreter layer may do — and exports the composed `BUILTIN_PLUGINS` and `CORE_UNCONDITIONAL_PLUGIN_NAMES`. Both are **parameters** of `build_registrar`, never module globals it imports, so `plugins/discovery.py` stays kernel-layer: `pipelex.py` (the interpreter boot) and the `pipelex plugins list` diagnostic pass the composed lists in, while `runtime_boot.py` defaults to the kernel half alone. Exactly one place still answers "what are the built-in plugins" — it just lives in the layer permitted to say it.-This is the seam external plugins already use. Our Temporal plugin contributes an orchestrator and our Daytona plugin a PipeFunc executor; both are interpreter-touching, both live outside this repo, and both arrive through the `pipelex.plugins` entry point without welding anything. The in-tree built-ins used to be the only ones that welded — [Known inversions](#known-inversions) records what that cost.+This is the seam external plugins already use. Our Temporal plugin contributes an orchestrator and our Daytona plugin a PipeFunc executor; both are interpreter-touching, both live outside this repo, and both arrive through the `pipelex.plugins.interpreter` entry-point group without welding anything. The in-tree built-ins used to be the only ones that welded — [Known inversions](#known-inversions) records what that cost.-One consequence is worth stating as a contract, and it is written into `PipelexPlugin`'s docstring: **a plugin belongs to exactly one layer.** A capability needing adapters in both is two plugins. Nothing enforces it mechanically; a straddling plugin would simply put the interpreter back into every runtime closure, and the guard's transitive rule would say so.+One consequence is worth stating as a contract, and it is written into `PipelexPlugin`'s docstring: **a plugin belongs to exactly one layer.** A capability needing adapters in both is two plugins. Nothing enforces it mechanically; a straddling plugin would simply put the interpreter back into every kernel closure, and the guard's transitive rule would say so.## Where the boot splits-The composition root is split the same way, and it is the same move: a runtime half in a declared runtime-layer home, and an interpreter half that imports it downward and adds what only a method-running process needs.+The composition root is split the same way, and it is the same move: a kernel half in a declared kernel-layer home, and an interpreter half that imports it downward and adds what only a method-running process needs.`pipelex/runtime_boot.py` holds `RuntimeBoot`. It stands up config, logging, the secrets provider, telemetry, the Kajson class registry with `CoreRegistryModels`, the template sets, the SDK client manager, the model deck, the plugin-derived runtime registries, storage, the content generator, the inference manager, the reporting delegate and the observers — and it loads **zero interpreter modules** doing it. `pipelex/pipelex.py` holds `Pipelex`, which subclasses it and appends 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`.Two top-level modules, not a `boot/` package: they mirror `runtime_hub.py` / `interpreter_hub.py`, which is the tree's strongest naming precedent for a layered pair. `Pipelex` does not move and is not renamed — it is the public entry point every consumer and sibling repo imports, and the layer boundary never required moving it.-**This is what finally gives `RUNTIME_BUILTIN_PLUGINS` a caller.** The plugin split created that constant with no importer in the tree; `RuntimeBoot.setup` defaults to it, so a runtime-only boot discovers exactly the runtime half and the two interpreter-touching built-ins are simply absent. The consequence is worth stating plainly, because it is the reason nothing needed redesigning to make this work: `OrchestratorRegistry`, `BundleValidatorRegistry` and the PipeFunc executor modes are all interpreter-contributed, and therefore **empty on a runtime-only boot** — which is harmless only because nothing in the runtime half *resolves* out of them at boot. They are constructed, set on the hub, and looked up at run time by the interpreter. The two registries the runtime half does resolve out of, secrets and storage, are runtime-contributed and core-unconditional.+**This is what finally gives `KERNEL_BUILTIN_PLUGINS` a caller.** The plugin split created that constant with no importer in the tree; `RuntimeBoot.setup` defaults to it, so a kernel-only boot discovers exactly the kernel half and the two interpreter-touching built-ins are simply absent. The consequence is worth stating plainly, because it is the reason nothing needed redesigning to make this work: `OrchestratorRegistry`, `BundleValidatorRegistry` and the PipeFunc executor modes are all interpreter-contributed, and therefore **empty on a kernel-only boot** — which is harmless only because nothing in the kernel half *resolves* out of them at boot. They are constructed, set on the hub, and looked up at run time by the interpreter. The two registries the kernel half does resolve out of, secrets and storage, are kernel-contributed and core-unconditional.Inheritance rather than composition, deliberately: it preserves every attribute address (`self.models_manager`, `self.class_registry`, `self.telemetry_manager` and the rest read the same from both halves, so no consumer inside or outside this repo changes), and it reads as what it is — the interpreter boot *is* the runtime boot plus the interpreter constructions. Two consequences are load-bearing:- **The singleton resolves by subclass.** `RuntimeBoot` carries `MetaSingleton` too, and the class-level accessors go through `MetaSingleton.get_subclass_instance`, so `RuntimeBoot.is_fully_booted()` answers `True` while a `Pipelex` owns the process globals. Each `make()` asks the *base* class whether a boot exists, which is what makes the two mutually exclusive in both directions — `set_runtime_hub`, `KajsonManager` and `log.configure` are all once-per-process, so booting one on top of the other would serve a half-populated class registry.- **Teardown ordering is explicit, not a template hook.** The plugin-contributed teardown callbacks must run *before* `pipeline_manager.teardown()`, so a worker's in-flight resources release first. `RuntimeBoot` exposes `_teardown_plugin_callbacks()` and `_teardown_runtime()` as separate phases and `Pipelex.teardown` sequences them with its own step in between, because that order is the whole reason the split exists in this shape.-Enforcement mirrors the packages': `pipelex.runtime_boot` is declared in `RUNTIME_LAYER_PACKAGES` (a *module* entry, beside `pipelex.runtime_hub`) and listed in the closure test's `RUNTIME_LAYER_ENTRY_POINTS`. `pipelex.pipelex` is deliberately **undeclared** — it is interpreter-side by construction, like `pipelex.cli`, so declaring it would fail the rule by design rather than enforce anything. `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` asserts both directions, because "surely the boot should be runtime-layer" is a plausible future edit.+Enforcement mirrors the packages': `pipelex.runtime_boot` is declared in `KERNEL_LAYER_PACKAGES` (a *module* entry, beside `pipelex.runtime_hub`) and listed in the closure test's `KERNEL_LAYER_ENTRY_POINTS`. `pipelex.pipelex` is deliberately **undeclared** — it is interpreter-side by construction, like `pipelex.cli`, so declaring it would fail the rule by design rather than enforce anything. `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` asserts both directions, because "surely the boot should be kernel-layer" is a plausible future edit.## Placement, not coupling@@ -199,13 +201,13 @@ What stays in `cogt/templating/` — `TemplateBlueprint`, the sigil preprocessor**`resolved_fields` moved down into `core/concepts/`.** The neutral resolved-field layer — one structure field becoming a `ResolvedType` tree — lived under `pipelex/codegen/` while `core/concepts/structure_generation/generator.py` imported it, which put `pipelex.codegen` into the closure of every core module that reached structure generation. It names nothing outside `pipelex.core`, so this was misfiling again: it now lives at `pipelex/core/concepts/resolved_fields.py`, and the codegen emitters import it upward.-**The two renderers regrouped, then left `core/` altogether — they are now `pipe_machinery/rendering/`.** `input_renderer` sat in `core/pipes/inputs/` beside genuinely runtime-layer modules while `output_renderer` sat alone in `core/pipes/output/`. Both render a `PipeAbstract` for a human or an agent, so both belong to the interpreter layer, and leaving `input_renderer` where it was would have forced the runtime-layer declaration to be a list of *modules* rather than packages. Regrouping them into one `rendering/` package was the first half of the fix and bought a real improvement — the boundary fell on package lines instead of module lines. It was only half, though: the declaration still had to name six `pipelex.core.*` sub-packages, because the boundary now fell on package lines *inside* `core/`. Moving the whole group out to `pipe_machinery/` is what collapsed those six entries to one. The general form: regrouping tells you where the boundary is, moving is what makes the boundary a package name.+**The two renderers regrouped, then left `core/` altogether — they are now `pipe_machinery/rendering/`.** `input_renderer` sat in `core/pipes/inputs/` beside genuinely kernel-layer modules while `output_renderer` sat alone in `core/pipes/output/`. Both render a `PipeAbstract` for a human or an agent, so both belong to the interpreter layer, and leaving `input_renderer` where it was would have forced the kernel-layer declaration to be a list of *modules* rather than packages. Regrouping them into one `rendering/` package was the first half of the fix and bought a real improvement — the boundary fell on package lines instead of module lines. It was only half, though: the declaration still had to name six `pipelex.core.*` sub-packages, because the boundary now fell on package lines *inside* `core/`. Moving the whole group out to `pipe_machinery/` is what collapsed those six entries to one. The general form: regrouping tells you where the boundary is, moving is what makes the boundary a package name.-The lesson generalizes: when a runtime-layer package imports an interpreter-layer one, check whether the *type* is misplaced before designing an indirection. None of these needed a resolver slot or a protocol — only a `git mv` and an import rewrite. And when a package straddles the boundary, moving the odd module out is usually cheaper than teaching the guard about exceptions — which is exactly how the built-in plugins were split, [below](#where-the-built-in-plugins-split).+The lesson generalizes: when a kernel-layer package imports an interpreter-layer one, check whether the *type* is misplaced before designing an indirection. None of these needed a resolver slot or a protocol — only a `git mv` and an import rewrite. And when a package straddles the boundary, moving the odd module out is usually cheaper than teaching the guard about exceptions — which is exactly how the built-in plugins were split, [below](#where-the-built-in-plugins-split).## The class-registry exception-`get_class_registry` is the one runtime-layer accessor that is *not* implemented in `runtime_hub`. Its implementation lives in `pipelex/system/registries/class_registry_access.py`, and `pipelex.runtime_hub.get_class_registry` delegates to it.+`get_class_registry` is the one kernel-layer accessor that is *not* implemented in `runtime_hub`. Its implementation lives in `pipelex/system/registries/class_registry_access.py`, and `pipelex.runtime_hub.get_class_registry` delegates to it.The reason is a genuine cycle. `core.concepts.concept` needs the active class registry, and it sits **inside** `runtime_hub`'s own import closure:@@ -216,11 +218,11 @@ runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factoryso `concept.py` cannot import `runtime_hub` at module level. Hosting the accessor in a module that imports nothing from `pipelex` is what lets `core/concepts/` use a plain top-level import — replacing three identical `importlib.import_module("pipelex.hub")` shims that were invisible to every import lint and to pyright's module graph.-**Use `pipelex.runtime_hub.get_class_registry` everywhere.** The exception is a module that must stay import-light *with respect to* `runtime_hub` — that one imports the leaf directly. `core/concepts/` is the case, for two different reasons: `concept.py` sits **inside** `runtime_hub`'s own closure, so the public accessor is literally unreachable there; `concept_factory.py` and `structure_generation/generator.py` sit outside it, and routing them through `runtime_hub` would re-couple `core.concepts` — a declared runtime-layer package — to the whole cogt/plugin stack for one function. Do not "fix" those two to the public accessor: nothing checks this mechanically, and the closure test would not catch it either, since it measures interpreter modules rather than weight.+**Use `pipelex.runtime_hub.get_class_registry` everywhere.** The exception is a module that must stay import-light *with respect to* `runtime_hub` — that one imports the leaf directly. `core/concepts/` is the case, for two different reasons: `concept.py` sits **inside** `runtime_hub`'s own closure, so the public accessor is literally unreachable there; `concept_factory.py` and `structure_generation/generator.py` sit outside it, and routing them through `runtime_hub` would re-couple `core.concepts` — a declared kernel-layer package — to the whole cogt/plugin stack for one function. Do not "fix" those two to the public accessor: nothing checks this mechanically, and the closure test would not catch it either, since it measures interpreter modules rather than weight.### Library scoping crosses downward, at install time-A run may pin a per-library `ClassRegistry` rather than the process-global Kajson one. Knowing *which* library is current is method-layer knowledge, so the runtime layer holds only a slot: `class_registry_scoping`, defaulting to a resolver that returns `None`. `set_interpreter_hub` installs the real resolver, which means scoping is live exactly when a `InterpreterHub` exists — an invariant a caller cannot forget to wire. The runtime teardown phase (`RuntimeBoot._teardown_runtime`, reached from every `teardown`) calls `class_registry_scoping.reset()` so a torn-down library manager is never reachable through a still-pinned library id. It lives on the runtime half because releasing the slot belongs to whichever teardown runs — on a runtime-only boot nothing installed a resolver and the reset is a no-op.+A run may pin a per-library `ClassRegistry` rather than the process-global Kajson one. Knowing *which* library is current is method-layer knowledge, so the kernel layer holds only a slot: `class_registry_scoping`, defaulting to a resolver that returns `None`. `set_interpreter_hub` installs the real resolver, which means scoping is live exactly when a `InterpreterHub` exists — an invariant a caller cannot forget to wire. The runtime teardown phase (`RuntimeBoot._teardown_runtime`, reached from every `teardown`) calls `class_registry_scoping.reset()` so a torn-down library manager is never reachable through a still-pinned library id. It lives on the kernel half because releasing the slot belongs to whichever teardown runs — on a kernel-only boot nothing installed a resolver and the reset is a no-op.This is the same shape as `HubSlot.ISOLATED_EXECUTION_PROBE`: a defaulted callable a higher layer replaces at boot, never an unset attribute. A process that only ever builds a `RuntimeHub` therefore degrades to the process-global registry instead of raising. That used to describe only the doctor path and most unit tests; since [the boot split](#where-the-boot-splits) it is a first-class entry point — `RuntimeBoot.make()` installs no `InterpreterHub`, and a test pins that scoping stays at its unscoped default on that boot.@@ -236,13 +238,13 @@ make check-hub-layering # alias: make chlAn AST guard (`pipelex-dev check-hub-layering`, core in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`) that runs in `make agent-check`, in the `make check` aggregate, and in CI. It checks three rules over `pipelex/` and `tests/`:-1. **The layer rule.** A module in the declared runtime layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.graph`, `pipelex.kernel`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the runtime layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.+1. **The layer rule.** A module in the declared kernel layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.graph`, `pipelex.kernel`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the kernel layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.- `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the runtime layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kernel` is the same rule applied *ahead* of a breach instead of behind one: it was declared in the commit that created the package, because it holds the operator-execution semantics the interpreter's operator classes call into, and a single `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic caller — the property the package exists to provide. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**+ `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the kernel layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kernel` is the same rule applied *ahead* of a breach instead of behind one: it was declared in the commit that created the package, because it holds the operator-execution semantics the interpreter's operator classes call into, and a single `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic caller — the property the package exists to provide. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**2. **The dead-module rule.** *No* scanned module may reference `pipelex.hub`. It was deleted rather than aliased so a stale import fails loudly; this closes the one hole in that guarantee.-3. **The transitive rule.** No runtime-layer module may *reach* `pipelex.interpreter_hub` either, through any chain of module-level imports. Rules 1 and 2 are per-file and see one hop; this one resolves the whole module-level import graph of `pipelex/` and does reachability over it, reporting the shortest chain and the line of its first hop. It exists because the one-hop rules missed a live breach for a whole release: four modules of the declared runtime-layer `pipelex.plugins` package reached the interpreter hub through `runtime_bridge`, `pipeline` and `pipe_operators`, and both gates stayed green (see [Known inversions](#known-inversions)). A *direct* import is left to rule 1, which names the more specific remedy, rather than reported twice.+3. **The transitive rule.** No kernel-layer module may *reach* `pipelex.interpreter_hub` either, through any chain of module-level imports. Rules 1 and 2 are per-file and see one hop; this one resolves the whole module-level import graph of `pipelex/` and does reachability over it, reporting the shortest chain and the line of its first hop. It exists because the one-hop rules missed a live breach for a whole release: four modules of the declared kernel-layer `pipelex.plugins` package reached the interpreter hub through `runtime_bridge`, `pipeline` and `pipe_operators`, and both gates stayed green (see [Known inversions](#known-inversions)). A *direct* import is left to rule 1, which names the more specific remedy, rather than reported twice.- The rule scopes itself to what an import actually loads: module-level imports only, `TYPE_CHECKING` blocks, function bodies and `# hub-layering: ignore`d statements excluded — the same carve-outs rule 1 grants, applied to the graph. It also models what an import loads *on the way*: reaching `pkg.sub.mod` executes `pkg/__init__.py` and `pkg/sub/__init__.py` first, so those are edges too and a breach in a package init is reached by every importer of anything beneath it. And a module-level **string** naming the interpreter hub is an edge, since a dynamic import loads it just the same — rule 1 catches that string in a runtime-layer module, but an *intermediary* sits in no declared layer, so without this the graph would miss it. A finding cannot be silenced **where it is reported** — the marker suppresses one reviewed *import*, never a module's transitive reach, so a module the declaration claims is runtime-layer while the graph says otherwise gets moved or has its dependency inverted.+ The rule scopes itself to what an import actually loads: module-level imports only, `TYPE_CHECKING` blocks, function bodies and `# hub-layering: ignore`d statements excluded — the same carve-outs rule 1 grants, applied to the graph. It also models what an import loads *on the way*: reaching `pkg.sub.mod` executes `pkg/__init__.py` and `pkg/sub/__init__.py` first, so those are edges too and a breach in a package init is reached by every importer of anything beneath it. And a module-level **string** naming the interpreter hub is an edge, since a dynamic import loads it just the same — rule 1 catches that string in a kernel-layer module, but an *intermediary* sits in no declared layer, so without this the graph would miss it. A finding cannot be silenced **where it is reported** — the marker suppresses one reviewed *import*, never a module's transitive reach, so a module the declaration claims is kernel-layer while the graph says otherwise gets moved or has its dependency inverted.The rule also refuses to pass vacuously: if the scan finds no `pipelex.interpreter_hub` among the modules it parsed — a renamed hub, or a scan root the module names cannot be derived from — it raises instead of reporting zero. Reverse reachability from a module the graph does not contain is empty by construction, so without that check a rename would silently turn the whole rule off while the gate stayed green.@@ -259,20 +261,20 @@ Two deliberate carve-outs:### The property — the import-closure test-`tests/unit/pipelex/test_runtime_layer_import_closure.py` imports each runtime-layer entry point in a **subprocess** and asserts that no module from its `INTERPRETER_PACKAGES` set — and no `pipelex.interpreter_hub` — landed in `sys.modules`. This is the [measurement above](#why-the-boundary-exists), pinned. It exists separately from the lint because the two fail independently: a runtime-layer module reaching directly into `pipe_operators`, without touching a hub, breaks the property while the lint stays green.+`tests/unit/pipelex/test_kernel_layer_import_closure.py` imports each kernel-layer entry point in a **subprocess** and asserts that no module from its `INTERPRETER_PACKAGES` set — and no `pipelex.interpreter_hub` — landed in `sys.modules`. This is the [measurement above](#why-the-boundary-exists), pinned. It exists separately from the lint because the two fail independently: a kernel-layer module reaching directly into `pipe_operators`, without touching a hub, breaks the property while the lint stays green.-The entry points are the inference layer, `runtime_hub` itself, `providers.builtins`, and the heaviest module of each runtime-layer `core/` package. `providers.builtins` earns its place by history, under its former name `plugins.builtins`: it instantiates every built-in vendor adapter, and `pipelex.plugins` — then the largest declared runtime-layer package, vendors and mechanism together — had no entry point here when the transitive breach happened. The guard now follows the import graph, but that is *static* analysis and cannot see a dynamic import, so the package that bit us gets a runtime-truth check too. One entry point still covers both halves of what has since become two packages: importing the manifest pulls in every built-in adapter, and they reach the mechanism they register through.+The entry points are the inference layer, `runtime_hub` itself, `providers.builtins`, and the heaviest module of each kernel-layer `core/` package. `providers.builtins` earns its place by history, under its former name `plugins.builtins`: it instantiates every built-in vendor adapter, and `pipelex.plugins` — then the largest declared kernel-layer package, vendors and mechanism together — had no entry point here when the transitive breach happened. The guard now follows the import graph, but that is *static* analysis and cannot see a dynamic import, so the package that bit us gets a runtime-truth check too. One entry point still covers both halves of what has since become two packages: importing the manifest pulls in every built-in adapter, and they reach the mechanism they register through.-Its predicate is now a single membership test over whole top-level packages — no per-module list and no exclusions. It used to need both: core's Pipe-machinery modules had to be named one by one (most were caught only *transitively*, through the `pipe_operators` / `libraries` they pull in, and `pipe_blueprint` pulled in none of it, so a runtime-layer import of it would have passed a package-only predicate), and `core.bundles.exceptions` had to be excluded by exact match because its validation-error data landed in every runtime closure. Both disappeared when the modules moved: the machinery to `pipe_machinery`, the parser to `mthds_parsing`, and the one leaf model to `core.exceptions`. **A package-granular predicate is honest only once the packages match the layers** — that is the whole argument for the moves, stated as a check.+Its predicate is now a single membership test over whole top-level packages — no per-module list and no exclusions. It used to need both: core's Pipe-machinery modules had to be named one by one (most were caught only *transitively*, through the `pipe_operators` / `libraries` they pull in, and `pipe_blueprint` pulled in none of it, so a kernel-layer import of it would have passed a package-only predicate), and `core.bundles.exceptions` had to be excluded by exact match because its validation-error data landed in every kernel closure. Both disappeared when the modules moved: the machinery to `pipe_machinery`, the parser to `mthds_parsing`, and the one leaf model to `core.exceptions`. **A package-granular predicate is honest only once the packages match the layers** — that is the whole argument for the moves, stated as a check.-The predicate now names **every** interpreter package. `pipeline` and `pipe_run` were the last two absent, and the reason was placement, not a broken arrow: four leaf models of theirs landed in every runtime closure, so naming them would have failed every entry point over an address. The remedy was the one `mthds_parsing` used — move the leaves first, then widen the predicate — and where each leaf went is decided by what it *is*, not by which package used to hold it:+The predicate now names **every** interpreter package. `pipeline` and `pipe_run` were the last two absent, and the reason was placement, not a broken arrow: four leaf models of theirs landed in every kernel closure, so naming them would have failed every entry point over an address. The remedy was the one `mthds_parsing` used — move the leaves first, then widen the predicate — and where each leaf went is decided by what it *is*, not by which package used to hold it:| leaf | was | is now | why there || --- | --- | --- | --- || `SpecialPipelineId` | `pipeline.pipeline_models` | `system.job_metadata` | it is the vocabulary of `pipeline_run_id`, and that is `JobMetadata`'s field || `PipeRunMode` | `pipe_run.pipe_run_mode` | `system.pipe_run_mode` | a run-scope directive, not one of a method's values || `PipeRunParamKey` | inside `pipe_run.pipe_run_params` | `system.pipe_run_param_key` | same, and `core.concepts` needs it as its reserved-names list |-| `PipeRunError` | `pipe_run.exceptions` | `core.pipes.exceptions` | the runtime layer *subclasses* it — `PipeRunInputsError` and `OptionalValueAbsentError` derive from it in `core.pipes.inputs` |+| `PipeRunError` | `pipe_run.exceptions` | `core.pipes.exceptions` | the kernel layer *subclasses* it — `PipeRunInputsError` and `OptionalValueAbsentError` derive from it in `core.pipes.inputs` |Note the last row does not follow the first three into `system/`. Consistency of destination is not the criterion — what the symbol *is* decides. Three are run-scope directives and enums; the fourth is the base of a pipe-error family whose other members already live in `core/pipes/`, and filing it with them also lands it in the same error-reference section as the two subclasses that derive from it.@@ -286,34 +288,34 @@ Each subprocess is time-bounded, because an unbounded one turns a deadlock intoAlongside them, `tests/unit/pipelex/test_hub_lifecycle.py` pins that a boot installs both singletons, and that the production `Pipelex.teardown` — not a stand-in calling `class_registry_scoping.reset()` directly — really releases the scoping an `InterpreterHub` installed, and that the next boot re-installs it. `tests/unit/pipelex/test_runtime_boot_closure.py` pins the boot-time half of the property: it *runs* `RuntimeBoot.make()` in a subprocess and asserts zero interpreter modules loaded, no `InterpreterHub` installed, and scoping left unscoped. A subprocess is required rather than preferred — both hubs are sticky class-attribute singletons that teardown never clears, so an in-process check would answer with a stale hub and pass vacuously. Booting rather than importing is what catches a boot step resolving out of an interpreter-contributed registry that is empty on that boot.-`tests/unit/pipelex/kernel/test_kernel_boot_contract.py` takes the same escalation one step further and is the only gate that closes the function-local blind spot [the aggregate inversion](#known-inversions) exposed. It boots runtime-only, *calls* a Pipelex-kernel op on that boot, and sweeps `sys.modules` **after** the call rather than after the import. The order is the whole mechanism: a deferred import inside a kernel function lands in `sys.modules` during the call and nowhere else, so the static guard and the import-closure test both stay green on it — verified by injecting one, not assumed. For `pipelex.kernel` this is also the package's contract rather than a consequence of it, since the reason the kernel exists is that a programmatic caller can run operator semantics with no interpreter and no library loaded.+`tests/unit/pipelex/kernel/test_kernel_boot_contract.py` takes the same escalation one step further and is the only gate that closes the function-local blind spot [the aggregate inversion](#known-inversions) exposed. It boots kernel-only, *calls* a Pipelex-kernel op on that boot, and sweeps `sys.modules` **after** the call rather than after the import. The order is the whole mechanism: a deferred import inside a kernel function lands in `sys.modules` during the call and nowhere else, so the static guard and the import-closure test both stay green on it — verified by injecting one, not assumed. For `pipelex.kernel` this is also the package's contract rather than a consequence of it, since the reason the kernel exists is that a programmatic caller can run operator semantics with no interpreter and no library loaded.### This document — the `hub-layering-convention` drift contract-The guard and the closure test keep the *code* honest; neither can tell whether **this page** still describes it. That is a [drift contract](drift-contracts.md): `hub-layering-convention` names the guard and both hub modules as triggers and this document as the review target, so adding or moving a hub accessor — or changing the declared runtime layer — obliges a recorded review here before the change can land. It carries no verify command, because `check-hub-layering` already gates `make check` and CI.+The guard and the closure test keep the *code* honest; neither can tell whether **this page** still describes it. That is a [drift contract](drift-contracts.md): `hub-layering-convention` names the guard and both hub modules as triggers and this document as the review target, so adding or moving a hub accessor — or changing the declared kernel layer — obliges a recorded review here before the change can land. It carries no verify command, because `check-hub-layering` already gates `make check` and CI.Two checks make that review mechanical rather than a re-read, and are the ones to run:- Extract every public module-level symbol from `runtime_hub` and `interpreter_hub` and confirm each appears in the partition tables above. An undocumented accessor is the failure mode this contract exists to catch.-- Import `RUNTIME_LAYER_PACKAGES` from the guard and confirm every declared package is named under [The rule](#the-rule-make-check-hub-layering).+- Import `KERNEL_LAYER_PACKAGES` from the guard and confirm every declared package is named under [The rule](#the-rule-make-check-hub-layering).## Known inversionsNamed so this document stays honest.-**The one that was fixed, kept as the worked example.** Four modules of the declared runtime-layer `pipelex.plugins` package used to reach `interpreter_hub` — `direct/direct_plugin.py` and `pipe_func/pipe_func_plugin.py` as the leaves (their job is to *construct* interpreter-layer objects), `builtins.py` and `discovery.py` purely as aggregators over them. (That `builtins.py` is today `pipelex/providers/builtins.py`; it moved with the vendor adapters it aggregates when the mechanism and the adapters were split.) None imported the hub *directly*, so the guard did not flag them, and the closure test had no entry point for the package, so nothing else did either: from the moment the declaration landed it claimed a property the measurement contradicted, with both gates green. The remedy was placement, not indirection — the two leaves moved to `pipelex/interpreter_plugins/` and the composition moved to the layer allowed to weld (see [Where the built-in plugins split](#where-the-built-in-plugins-split)) — and the guard grew the [transitive rule](#the-rule-make-check-hub-layering) so the next one cannot hide the same way. Three lessons generalize: a package-granular declaration is a claim about the whole package, an aggregator inherits every breach it aggregates, and a rule that stops at one hop will eventually be walked around.+**The one that was fixed, kept as the worked example.** Four modules of the declared kernel-layer `pipelex.plugins` package used to reach `interpreter_hub` — `direct/direct_plugin.py` and `pipe_func/pipe_func_plugin.py` as the leaves (their job is to *construct* interpreter-layer objects), `builtins.py` and `discovery.py` purely as aggregators over them. (That `builtins.py` is today `pipelex/providers/builtins.py`; it moved with the vendor adapters it aggregates when the mechanism and the adapters were split.) None imported the hub *directly*, so the guard did not flag them, and the closure test had no entry point for the package, so nothing else did either: from the moment the declaration landed it claimed a property the measurement contradicted, with both gates green. The remedy was placement, not indirection — the two leaves moved to `pipelex/interpreter_plugins/` and the composition moved to the layer allowed to weld (see [Where the built-in plugins split](#where-the-built-in-plugins-split)) — and the guard grew the [transitive rule](#the-rule-make-check-hub-layering) so the next one cannot hide the same way. Three lessons generalize: a package-granular declaration is a claim about the whole package, an aggregator inherits every breach it aggregates, and a rule that stops at one hop will eventually be walked around.-**The one the worked example predicted, found by declaring the package.** `graph/graph_rendering.py` imported `pipeline.dry_run_pipeline` at module level, and importing it pulled in `interpreter_hub` plus ~76 interpreter modules. Every gate stayed green, for a reason worth stating plainly: rules 1 and 3 both filter their candidates through `is_runtime_layer`, and `pipelex.graph` was not declared — so the module had been outside the rules' domain the whole time. This is the `pipelex.plugins` breach again, one level up: not a package whose declaration overreached, but a package with **no** declaration at all. The remedy was placement, as before. The module split along "do I need a loaded method?", which is this boundary's own question: the pure renderer (`GraphFormat`, `render_graph_from_spec`) stayed in `pipelex.graph`, and the bundle-driven half that has to dry-run a method first (`generate_graph_for_bundle`, `generate_view_for_bundle`) became `pipelex.pipeline.bundle_graph_rendering`, next to the `dry_run_pipeline` it exists to wrap. The lesson is the one this page now states under [The rule](#the-rule-make-check-hub-layering): **an undeclared package is not neutral, it is unpoliced** — omitting an entry makes the guard quieter, never louder.+**The one the worked example predicted, found by declaring the package.** `graph/graph_rendering.py` imported `pipeline.dry_run_pipeline` at module level, and importing it pulled in `interpreter_hub` plus ~76 interpreter modules. Every gate stayed green, for a reason worth stating plainly: rules 1 and 3 both filter their candidates through `is_kernel_layer`, and `pipelex.graph` was not declared — so the module had been outside the rules' domain the whole time. This is the `pipelex.plugins` breach again, one level up: not a package whose declaration overreached, but a package with **no** declaration at all. The remedy was placement, as before. The module split along "do I need a loaded method?", which is this boundary's own question: the pure renderer (`GraphFormat`, `render_graph_from_spec`) stayed in `pipelex.graph`, and the bundle-driven half that has to dry-run a method first (`generate_graph_for_bundle`, `generate_view_for_bundle`) became `pipelex.pipeline.bundle_graph_rendering`, next to the `dry_run_pipeline` it exists to wrap. The lesson is the one this page now states under [The rule](#the-rule-make-check-hub-layering): **an undeclared package is not neutral, it is unpoliced** — omitting an entry makes the guard quieter, never louder.-**The one an aggregate module hid.** Five built-in vendor adapters — `providers/{anthropic,bedrock,google,mistral}/*_list.py` — imported `MissingDependencyError` from `pipelex.exceptions` rather than from its definition site in `pipelex.system.exceptions`. `pipelex/exceptions.py` is the *public all-errors aggregate*: it re-exports every interpreter package's exceptions, so importing anything from it loads `pipeline.exceptions` → `validation_errors` → `fixes.planner` and more. Each of those five declared runtime-layer modules therefore loaded 15 interpreter modules. Neither gate could see it: the guard's rules only chase `interpreter_hub`, and the aggregate never reaches it; the closure test's `providers.builtins` entry point does not cover these modules either, because the vendor plugins import them *inside a function*, which hides them from the static import graph and from the aggregator's own closure at once. The fix is the repo's existing rule — *direct full-path imports everywhere*, i.e. import from where the symbol is defined, never from a convenience aggregate — plus one new entry point (`providers.anthropic.anthropic_list`) so the runtime-truth check now covers the shape. The generalizable lesson: **a module that re-exports across layers is a layer boundary with the sign filed off**, and a deferred import will hide it from every static gate you have. Since then the rule is mechanical rather than prose: `tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py` AST-walks every package declared in `RUNTIME_LAYER_PACKAGES` and fails on any import of `pipelex.exceptions` — module-level or function-local, absolute or relative — as well as on any bare string naming it, since an `import_module` argument or a patch target loads the aggregate through a path no import node records. The next aggregate reference in the runtime layer is caught by CI instead of by review. The aggregate itself remains a legitimate public surface for callers *outside* the runtime layer; the ban is scoped to the layer whose closure it would silently widen.+**The one an aggregate module hid.** Five built-in vendor adapters — `providers/{anthropic,bedrock,google,mistral}/*_list.py` — imported `MissingDependencyError` from `pipelex.exceptions` rather than from its definition site in `pipelex.system.exceptions`. `pipelex/exceptions.py` is the *public all-errors aggregate*: it re-exports every interpreter package's exceptions, so importing anything from it loads `pipeline.exceptions` → `validation_errors` → `fixes.planner` and more. Each of those five declared kernel-layer modules therefore loaded 15 interpreter modules. Neither gate could see it: the guard's rules only chase `interpreter_hub`, and the aggregate never reaches it; the closure test's `providers.builtins` entry point does not cover these modules either, because the vendor plugins import them *inside a function*, which hides them from the static import graph and from the aggregator's own closure at once. The fix is the repo's existing rule — *direct full-path imports everywhere*, i.e. import from where the symbol is defined, never from a convenience aggregate — plus one new entry point (`providers.anthropic.anthropic_list`) so the runtime-truth check now covers the shape. The generalizable lesson: **a module that re-exports across layers is a layer boundary with the sign filed off**, and a deferred import will hide it from every static gate you have. Since then the rule is mechanical rather than prose: `tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.py` AST-walks every package declared in `KERNEL_LAYER_PACKAGES` and fails on any import of `pipelex.exceptions` — module-level or function-local, absolute or relative — as well as on any bare string naming it, since an `import_module` argument or a patch target loads the aggregate through a path no import node records. The next aggregate reference in the kernel layer is caught by CI instead of by review. The aggregate itself remains a legitimate public surface for callers *outside* the kernel layer; the ban is scoped to the layer whose closure it would silently widen.-- **`cogt` names four specific vendors, deliberately.** `cogt/config_cogt.py` imports `AnthropicConfig`, `GoogleConfig`, `MistralConfig` and `OpenAIConfig` from their `pipelex/providers/` packages. Both sides are runtime-layer, so this breaches no hub rule — it is a placement inversion: the vendor-neutral engine names four vendors. It is accepted rather than fixed, because the alternative is worse. The main config model is statically typed end-to-end (`system/configuration/configs.py` and the `pipelex.toml` files are structurally synced, and boot fails loud when they disagree), so making vendor config sections plugin-contributed would trade compile-time typing for a dynamic registry — a real loss to buy a cosmetic win. The edge is one-way and shallow: a config class, not a worker.+- **`cogt` names four specific vendors, deliberately.** `cogt/config_cogt.py` imports `AnthropicConfig`, `GoogleConfig`, `MistralConfig` and `OpenAIConfig` from their `pipelex/providers/` packages. Both sides are kernel-layer, so this breaches no hub rule — it is a placement inversion: the vendor-neutral engine names four vendors. It is accepted rather than fixed, because the alternative is worse. The main config model is statically typed end-to-end (`system/configuration/configs.py` and the `pipelex.toml` files are structurally synced, and boot fails loud when they disagree), so making vendor config sections plugin-contributed would trade compile-time typing for a dynamic registry — a real loss to buy a cosmetic win. The edge is one-way and shallow: a config class, not a worker.- **The img-gen one that stopped being an inversion.** `cogt/img_gen/img_gen_args_factory.py` used to import two vendor img-gen factories at module level, for taxonomy and geometry helpers. It was never a registry problem: dispatch is keyed on `AspectRatioTaxonomy`, a `cogt`-owned enum that names model families and no providers, and no family is served by a single adapter — the `openai` and `azure_openai` decks both ship GPT Image models, and the gateway worker resolves Gemini geometry through the same mapping the native Google worker uses — so there was no provider key to dispatch on, and a registrar slot would have bought a plugin-API bump for two import sites. Fixed by placement instead: the helpers are now `cogt/img_gen/img_gen_gemini_mapping.py` and `cogt/img_gen/img_gen_gpt_mapping.py`, and the Google worker and the gateway factory import *inward* to them. One `cogt → specific vendor` edge of this kind remains — `model_backends/backend_factory.py` reaching for `VertexAIFactory` — already deferred inside a function, and it self-resolves when VertexAI support is removed.-- **What pins the two bullets above.** The complete `cogt → pipelex.providers` list — the four config imports plus that one deferred factory import — is a golden set in `tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py`, together with the stronger fact that `pipelex/cogt/**` imports no vendor SDK at all. A sixth edge fails it, and nothing else in the repo would notice: both packages are runtime-layer, so the guard and the closure test are blind to an edge between them by construction. Golden sets rather than a rule, because these are *accepted* inversions — there is no predicate separating the sanctioned edges from a new one, and the point is to make the next one a diff a reviewer reads. Note the tempting generalization — *no vendor SDK anywhere in `pipelex/` outside `providers/`* — is **false**, and a test asserting it would be red on day one: `tools/pdf/pypdfium2_renderer.py`, `tools/storage/`, `tracing/` and `reporting/` import pypdfium2 and the AWS/GCP SDKs on purpose, because `providers/storage/` is a registration shim whose implementations live under `pipelex/tools/`. The scope that holds is `cogt`.+- **What pins the two bullets above.** The complete `cogt → pipelex.providers` list — the four config imports plus that one deferred factory import — is a golden set in `tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py`, together with the stronger fact that `pipelex/cogt/**` imports no vendor SDK at all. A sixth edge fails it, and nothing else in the repo would notice: both packages are kernel-layer, so the guard and the closure test are blind to an edge between them by construction. Golden sets rather than a rule, because these are *accepted* inversions — there is no predicate separating the sanctioned edges from a new one, and the point is to make the next one a diff a reviewer reads. Note the tempting generalization — *no vendor SDK anywhere in `pipelex/` outside `providers/`* — is **false**, and a test asserting it would be red on day one: `tools/pdf/pypdfium2_renderer.py`, `tools/storage/`, `tracing/` and `reporting/` import pypdfium2 and the AWS/GCP SDKs on purpose, because `providers/storage/` is a registration shim whose implementations live under `pipelex/tools/`. The scope that holds is `cogt`.- `plugins/pipe_func_executor_registry.py` is typed by a protocol from `pipe_operators/` and defers that import under `TYPE_CHECKING` precisely because `pipelex.config` imports it and the inference layer imports `pipelex.config` — a module-level import there would drag the interpreter back into every inference closure. Being type-only it loads nothing, so it breaches neither rule — the sanctioned deferral pattern. The placement inversion itself is unfixed.-- **The one that stopped being an inversion.** `core/`'s Pipe-touching half — `pipe_abstract`, `pipe_blueprint`, `pipe_factory`, the renderers — imported the interpreter directly while sitting under a package the runtime layer wanted to declare. That was never a wrong *import* (it is a fact about what a pipe is), it was a wrong *address*, and it forced the declaration to enumerate core's data-model packages instead of naming `pipelex.core`. Fixed by placement: the modules are now `pipelex.pipe_machinery` and `pipelex.mthds_parsing`, and the six `pipelex.core.*` entries collapsed to one. Several of them still import `interpreter_hub` on purpose, to inject downward — that is the sanctioned direction and always was.+- **The one that stopped being an inversion.** `core/`'s Pipe-touching half — `pipe_abstract`, `pipe_blueprint`, `pipe_factory`, the renderers — imported the interpreter directly while sitting under a package the kernel layer wanted to declare. That was never a wrong *import* (it is a fact about what a pipe is), it was a wrong *address*, and it forced the declaration to enumerate core's data-model packages instead of naming `pipelex.core`. Fixed by placement: the modules are now `pipelex.pipe_machinery` and `pipelex.mthds_parsing`, and the six `pipelex.core.*` entries collapsed to one. Several of them still import `interpreter_hub` on purpose, to inject downward — that is the sanctioned direction and always was.- Broader measured inversions, out of scope for the hub boundary: `cogt → core`, `system → cogt`, `plugins → runtime_bridge`, and `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. What remains of `tools → cogt` is `tools/pdf/pypdfium2_renderer.py` reaching for `cogt.extract` and `cogt.image` types; the templating half of that cluster is gone (see [Placement, not coupling](#placement-not-coupling)).## For consumers outside this repo-`pipelex.hub` is gone; there is no shim. Every external importer must choose a layer. The symbols that crossed the repo boundary are split as follows — runtime-layer ones now come from `pipelex.runtime_hub`, interpreter-layer ones from `pipelex.interpreter_hub`, per the tables above. `get_pipelex_hub` splits into `get_runtime_hub` and `get_interpreter_hub`, so each call site must pick the container it actually meant.+`pipelex.hub` is gone; there is no shim. Every external importer must choose a layer. The symbols that crossed the repo boundary are split as follows — kernel-layer ones now come from `pipelex.runtime_hub`, interpreter-layer ones from `pipelex.interpreter_hub`, per the tables above. `get_pipelex_hub` splits into `get_runtime_hub` and `get_interpreter_hub`, so each call site must pick the container it actually meant.diff --git a/docs/cookbook/using-inference-plugins.md b/docs/cookbook/using-inference-plugins.mdindex 779fae655..9cabd8874 100644--- a/docs/cookbook/using-inference-plugins.md+++ b/docs/cookbook/using-inference-plugins.md@@ -13,7 +13,7 @@ This example shows how Pipelex discovers **inference-backend plugins**: installa## What it demonstrates-- What a plugin **is**: a package exposing a `pipelex.plugins` entry point that resolves to a `PipelexPlugin` — an object with a `name`, a `targets_api` version, and a side-effect-free `register(registrar)` method+- What a plugin **is**: a package exposing a `pipelex.plugins.kernel` entry point that resolves to a `PipelexPlugin` — an object with a `name`, a `targets_api` version, and a side-effect-free `register(registrar)` method- Registration through the registrar: `register` contributes an inference backend for `(family="llm", sdk="hello")`, plus an optional model lister- Discovery by presence: installing the package is the whole integration — no enable-list, no config switch- The model-config side: how a model handle in a `.mthds` file resolves to the plugin's worker through `.pipelex/inference/`@@ -27,7 +27,7 @@ The plugin lives inside the example directory as its own installable package:examples/c_advanced/using_inference_plugins/├── hello_plugin.mthds # the method that uses the plugin-served model└── hello_inference_plugin/ # the plugin package- ├── pyproject.toml # declares the `pipelex.plugins` entry point+ ├── pyproject.toml # declares the `pipelex.plugins.kernel` entry point└── hello_inference_plugin/├── hello_plugin.py # HelloInferencePlugin: name, targets_api, register()├── hello_llm_worker.py # HelloLLMWorker(LLMWorkerAbstract): the actual "model"@@ -37,7 +37,7 @@ examples/c_advanced/using_inference_plugins/The entry point in `pyproject.toml` is the single line that wires everything:```toml-[project.entry-points."pipelex.plugins"]+[project.entry-points."pipelex.plugins.kernel"]hello_inference = "hello_inference_plugin.hello_plugin:HelloInferencePlugin"```diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.mdindex 5975eccba..26fbf48b3 100644--- a/docs/errors/inference-and-providers.md+++ b/docs/errors/inference-and-providers.md@@ -122,7 +122,10 @@ own page. Classes are grouped by subsystem.- [`HubSlotAlreadyClaimedError`](hub-slot-already-claimed-error.md) — Hub slot already claimed- [`InferenceBackendNotFoundError`](inference-backend-not-found-error.md) — Inference backend not found- [`PluginApiVersionMismatchError`](plugin-api-version-mismatch-error.md) — Plugin api version mismatch+- [`PluginDeclaredInMultipleGroupsError`](plugin-declared-in-multiple-groups-error.md) — Plugin declared in multiple groups- [`PluginError`](plugin-error.md) — Plugin error+- [`PluginLayerViolationError`](plugin-layer-violation-error.md) — Plugin layer violation+- [`RetiredPluginEntryPointGroupError`](retired-plugin-entry-point-group-error.md) — Retired plugin entry point group- [`UnknownBootOrchestratorError`](unknown-boot-orchestrator-error.md) — Unknown boot orchestrator- [`UnknownPipeFuncExecutionModeError`](unknown-pipe-func-execution-mode-error.md) — Unknown pipe func execution mode- [`UnknownSecretsMethodError`](unknown-secrets-method-error.md) — Unknown secrets methoddiff --git a/docs/errors/plugin-declared-in-multiple-groups-error.md b/docs/errors/plugin-declared-in-multiple-groups-error.mdnew file mode 100644index 000000000..be56d17a8--- /dev/null+++ b/docs/errors/plugin-declared-in-multiple-groups-error.md@@ -0,0 +1,21 @@+---+title: "Plugin declared in multiple groups"+description: "Reference for the `PluginDeclaredInMultipleGroupsError` Pipelex error class."+---++<!-- pipelex:generated -->++# Plugin declared in multiple groups++One installed plugin advertises the same name under more than one entry-point group.++| Field | Value |+|---|---|+| `error_type` | `PluginDeclaredInMultipleGroupsError` |+| `title` | Plugin declared in multiple groups |+| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-declared-in-multiple-groups-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/plugin-layer-violation-error.md b/docs/errors/plugin-layer-violation-error.mdnew file mode 100644index 000000000..2a289b664--- /dev/null+++ b/docs/errors/plugin-layer-violation-error.md@@ -0,0 +1,21 @@+---+title: "Plugin layer violation"+description: "Reference for the `PluginLayerViolationError` Pipelex error class."+---++<!-- pipelex:generated -->++# Plugin layer violation++A kernel-group plugin registered an interpreter-layer capability.++| Field | Value |+|---|---|+| `error_type` | `PluginLayerViolationError` |+| `title` | Plugin layer violation |+| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-layer-violation-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/retired-plugin-entry-point-group-error.md b/docs/errors/retired-plugin-entry-point-group-error.mdnew file mode 100644index 000000000..de7216cb5--- /dev/null+++ b/docs/errors/retired-plugin-entry-point-group-error.md@@ -0,0 +1,21 @@+---+title: "Retired plugin entry point group"+description: "Reference for the `RetiredPluginEntryPointGroupError` Pipelex error class."+---++<!-- pipelex:generated -->++# Retired plugin entry point group++An installed plugin still advertises itself under the retired single entry-point group.++| Field | Value |+|---|---|+| `error_type` | `RetiredPluginEntryPointGroupError` |+| `title` | Retired plugin entry point group |+| `type_uri` | `https://docs.pipelex.com/latest/errors/retired-plugin-entry-point-group-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/under-the-hood/architecture-overview.md b/docs/under-the-hood/architecture-overview.mdindex 07547f48e..ff3867581 100644--- a/docs/under-the-hood/architecture-overview.md+++ b/docs/under-the-hood/architecture-overview.md@@ -46,7 +46,7 @@ Operators perform concrete actions:- **PipeCompose** - Compose content from templates or construct structured objects- **PipeSearch** - Search the web for information-What an operator *does* — model-deck resolution, prompt assembly, generation, memory write-back — lives one layer down in [`pipelex/kernel/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/kernel), as plain functions that take everything method-specific as an explicit argument and read only the runtime services a boot stands up, such as the model deck and the content generator. The operator classes above hold what is specific to being a step in a method: blueprint resolution, input validation, error context, and execution-graph tracing. The split exists so the same semantics can be called without a loaded method, and so there is one implementation rather than two that drift. See [The Pipelex Kernel](./pipelex-kernel.md) for the layering contract, what a programmatic caller imports, and how it boots.+What an operator *does* — model-deck resolution, prompt assembly, generation, memory write-back — lives one layer down in [`pipelex/kernel/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/kernel), as plain functions that take everything method-specific as an explicit argument and read only the kernel-layer services a boot stands up, such as the model deck and the content generator. The operator classes above hold what is specific to being a step in a method: blueprint resolution, input validation, error context, and execution-graph tracing. The split exists so the same semantics can be called without a loaded method, and so there is one implementation rather than two that drift. See [The Pipelex Kernel](./pipelex-kernel.md) for the layering contract, what a programmatic caller imports, and how it boots.### Core Domain@@ -81,7 +81,7 @@ The COGT layer abstracts AI provider details from business logic:Two packages, one for the mechanism and one for the built-in adapters:-- [`pipelex/plugins/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/plugins) — the plugin **mechanism**: the `PipelexPlugin` contract, the registrar every plugin registers into, and the capability registries. This is what an out-of-tree plugin imports, and what the `pipelex.plugins` entry point resolves against.+- [`pipelex/plugins/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/plugins) — the plugin **mechanism**: the `PipelexPlugin` contract, the registrar every plugin registers into, and the capability registries. This is what an out-of-tree plugin imports, and what the `pipelex.plugins.kernel` / `pipelex.plugins.interpreter` entry points resolve against.- [`pipelex/providers/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/providers) — the built-in **provider adapters**, one directory per vendor, each handling that vendor's API specifics:- OpenAI@@ -109,11 +109,11 @@ One rule governs them:!!! note "The one arrow"`interpreter_hub` imports `runtime_hub`. **`runtime_hub` never imports `interpreter_hub`.**-The practical consequence is that the runtime layer cannot reach the interpreter layer. Importing the inference stack loads no `libraries`, `pipe_operators`, `pipe_controllers`, or `codegen` module at all — so anything that just wants a secret, the console, or the model deck (a health check, `pipelex --version`, a plugin's registration module) does not pay for the method interpreter, and a change to a pipe blueprint structurally cannot perturb the import graph of `cogt`.+The practical consequence is that the kernel layer cannot reach the interpreter layer. Importing the inference stack loads no `libraries`, `pipe_operators`, `pipe_controllers`, or `codegen` module at all — so anything that just wants a secret, the console, or the model deck (a health check, `pipelex --version`, a plugin's registration module) does not pay for the method interpreter, and a change to a pipe blueprint structurally cannot perturb the import graph of `cogt`.-That is not a convention held up by review: `make check-hub-layering` fails the build if a runtime-layer module imports — or merely names in a string — the interpreter hub, and an import-closure test pins the property itself in a subprocess.+That is not a convention held up by review: `make check-hub-layering` fails the build if a kernel-layer module imports — or merely names in a string — the interpreter hub, and an import-closure test pins the property itself in a subprocess.-`pipelex/core/` sits on both sides of the line, deliberately. Its data model — concepts, domains, stuffs, working memory, the input/output specs — belongs to the runtime layer: it describes what a method's values *are*, needs no loaded method, and takes the concept or pipe it needs as an injected argument. Everything in `core/` that names a **`Pipe`** belongs to the interpreter layer, because a pipe is the interpreter's own object.+`pipelex/core/` sits on both sides of the line, deliberately. Its data model — concepts, domains, stuffs, working memory, the input/output specs — belongs to the kernel layer: it describes what a method's values *are*, needs no loaded method, and takes the concept or pipe it needs as an injected argument. Everything in `core/` that names a **`Pipe`** belongs to the interpreter layer, because a pipe is the interpreter's own object.Contributors: the full specification — what lives on each hub, how to place a new symbol, and how the boundary is enforced — is in [Hub Layering](../contribute/hub-layering.md).diff --git a/docs/under-the-hood/inference-backend-plugins.md b/docs/under-the-hood/inference-backend-plugins.mdindex f4c668e5a..e64583899 100644--- a/docs/under-the-hood/inference-backend-plugins.md+++ b/docs/under-the-hood/inference-backend-plugins.md@@ -17,7 +17,8 @@ Core names no backend by import or by string. The built-in drivers (OpenAI, Gateboot (Pipelex.setup)└─ build_registrar(config, builtin_plugins=BUILTIN_PLUGINS, …) # pure, import-light├─ for each built-in plugin (both layers' halves, composed)- └─ for each installed "pipelex.plugins" entry point+ └─ for each installed entry point in the requested groups+ # "pipelex.plugins.kernel" alone on a kernel-only boot; both groups on a full one└─ plugin.register(registrar) # side-effect-free└─ registrar.add_inference_backend(family=…, sdk=…, make_worker=…)└─ InferenceBackendRegistry(registrar.inference_backends) # stored on the hub@@ -175,14 +176,18 @@ class AcmePlugin:### Shipping it as an out-of-tree plugin-Declare an entry point in the `pipelex.plugins` group; discovery finds it automatically once the distribution is installed (no central enable-list — *presence* is the source of truth):+Declare an entry point in the `pipelex.plugins.kernel` group; discovery finds it automatically once the distribution is installed (no central enable-list — *presence* is the source of truth):```toml# pyproject.toml of your plugin package-[project.entry-points."pipelex.plugins"]+[project.entry-points."pipelex.plugins.kernel"]acme = "my_pkg.acme_plugin:AcmePlugin"```+**The group declares your layer, and the choice is not cosmetic.** An inference backend is kernel-layer — it constructs a worker, never a `Pipe` — so it belongs in `pipelex.plugins.kernel`, and a kernel-only boot reads that group and finds it. Publish the same plugin under `pipelex.plugins.interpreter` and a kernel-only boot never even *imports* your module, so your backend is simply absent. The reverse mistake fails loudly instead: a `pipelex.plugins.kernel` plugin whose `register` reaches an interpreter-layer capability — `add_orchestrator`, `add_bundle_validator`, `add_pipe_func_executor`, or the three hub slots that hand back a `Pipe`-aware object (`claim_pipe_router`, `claim_pipe_run`, `claim_pipe_func_executor`) — raises `PluginLayerViolationError` naming the capability and the group to move to. The other three slots are kernel-tier and a kernel-group plugin may claim them freely: `claim_content_generator`, `claim_task_manager`, `claim_isolated_execution_probe`. The restriction is one-directional — an interpreter-group plugin may contribute kernel-tier capabilities too.++The single pre-split `pipelex.plugins` group is retired. It is not ignored: a plugin still published there fails startup with `RetiredPluginEntryPointGroupError`, because the alternative — being silently undiscovered — is the expensive failure to diagnose.+The entry point may resolve to a plugin instance or a zero-argument factory. A broken entry point is isolated and reported as `BrokenPluginError`, never a silent skip.### Disabling a discovered plugin@@ -199,7 +204,7 @@ For external entry points the denylist is matched against the **entry-point nameDisabling a core-unconditional plugin (`openai`) is a configuration error, not a no-op — it raises `CoreUnconditionalPluginDisabledError`. There is intentionally **no** allowlist: a plugin's presence (built-in or installed entry point) is what enables it.-Use `pipelex plugins list` to see every discovered plugin, what each contributed, and its denylist state.+Use `pipelex plugins list` to see every discovered plugin, the entry-point group it was found under, what each contributed, and its denylist state. The **Group** column is the first thing to read when a plugin is missing: a built-in shows `—`, and an external plugin that resolved to the wrong layer shows it there.---@@ -230,6 +235,8 @@ The SPI is a documented, versioned **module/symbol list** gated by `PLUGIN_API_V| Condition | Error ||-----------|-------|| `targets_api` ≠ `PLUGIN_API_VERSION` | `PluginApiVersionMismatchError` |+| published under the retired `pipelex.plugins` group | `RetiredPluginEntryPointGroupError` (names the plugins and the group each should move to) |+| a `pipelex.plugins.kernel` plugin registers an interpreter-layer capability | `PluginLayerViolationError` (names the capability and the group to move to) || duplicate `(family, sdk)` | `DuplicateInferenceBackendError` (names both plugins) || duplicate `sdk` model lister | `DuplicateModelListerError` (names both plugins) || `name` in `plugins.disabled` but core-unconditional | `CoreUnconditionalPluginDisabledError` |diff --git a/docs/under-the-hood/orchestrator-plugins.md b/docs/under-the-hood/orchestrator-plugins.mdindex 503e8e82e..dc126ca96 100644--- a/docs/under-the-hood/orchestrator-plugins.md+++ b/docs/under-the-hood/orchestrator-plugins.md@@ -26,7 +26,7 @@ An **orchestrator** is what knows how to run a pipe under one token. Core namesThe registry is built once at boot from whatever the discovered plugins contributed (`build_registrar` → `OrchestratorRegistry` on the hub). There is no `match orchestration_mode:` anywhere in the bridge — the token set is open, so validation is the registry lookup itself; adding a mode's behavior means registering an orchestrator for its token, nothing in core changes.-The *port* — `OrchestratorProtocol` and its registry — is runtime-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. That split only concerns in-tree built-ins; an out-of-tree plugin sits in no declared layer and is unaffected. See [Hub layering](../contribute/hub-layering.md#where-the-built-in-plugins-split).+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.@@ -205,7 +205,7 @@ What an out-of-tree orchestrator imports *is* a contract. The SPI is a documenteThe 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 Temporal plugin is **external** — it ships as the `pipelex-temporal` distribution and is discovered through a `pipelex.plugins` 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 runtime 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 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.---@@ -215,11 +215,13 @@ A third-party host-runtime plugin is a distribution that:1. defines a plugin class (`name`, `targets_api`, `register`) whose `register` calls `add_orchestrator(mode=..., orchestrator=...)` for the mode(s) it serves — import-light;2. compiles its orchestrator against the Orchestrator SPI above (and nothing outside it);-3. advertises itself under the `pipelex.plugins` entry-point group:+3. advertises itself under the `pipelex.plugins.interpreter` entry-point group — an orchestrator constructs `Pipe`-aware objects, so it is interpreter-layer, and the group is how a plugin declares that. Publishing an orchestrator under `pipelex.plugins.kernel` instead raises `PluginLayerViolationError` at register time. See [Inference Backend Plugins](inference-backend-plugins.md#shipping-it-as-an-out-of-tree-plugin) for what each group means; the pre-split `pipelex.plugins` group is retired and now fails startup:```toml-[project.entry-points."pipelex.plugins"]+[project.entry-points."pipelex.plugins.interpreter"]my_runtime = "my_package.my_plugin:MyRuntimePlugin"```+An interpreter-group plugin is *not* restricted to interpreter-layer capabilities — the cross-check runs one way only. Our own Temporal plugin contributes an orchestrator and an HTTP-error mapper (kernel-tier) from the same `register`, which is why the rule is asymmetric.+Installing the distribution makes the mode available; uninstalling removes it. No core change, no central registration list. A discovered plugin can be quarantined without uninstalling via the `plugins.disabled` denylist (see [Inference Backend Plugins](inference-backend-plugins.md) for the shared discovery/denylist machinery).diff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.mdindex 01e5190f4..cc4924895 100644--- a/docs/under-the-hood/pipelex-kernel.md+++ b/docs/under-the-hood/pipelex-kernel.md@@ -5,12 +5,12 @@ description: "Operator semantics as importable functions — what pipelex/kernel# The Pipelex Kernel-This page is for contributors working on Pipelex internals, and for anyone embedding the runtime directly rather than running `.mthds` methods. For how the operator classes above it fit into the whole, see [Architecture Overview](./architecture-overview.md).+This page is for contributors working on Pipelex internals, and for anyone embedding the kernel directly rather than running `.mthds` methods. For how the operator classes above it fit into the whole, see [Architecture Overview](./architecture-overview.md).What a `PipeLLM` step actually *does* — resolve a model off the deck, derive a prompting style, assemble the prompt, generate, write the result into memory — used to be reachable only through a fully booted interpreter with a method loaded. [`pipelex/kernel/`](https://github.com/Pipelex/pipelex/tree/main/pipelex/kernel) holds that semantics as plain functions, so it has **one implementation with two kinds of caller**:- the interpreter's operator classes (`PipeLLM`, `PipeExtract`, `PipeImgGen`, `PipeSearch`, `PipeCompose`, `PipeFunc`), which resolve blueprints, validate inputs, wrap errors and trace, then call the kernel;-- any **programmatic caller** embedding the runtime, which calls the same functions on a process with zero `.mthds` loaded.+- any **programmatic caller** embedding the kernel, which calls the same functions on a process with zero `.mthds` loaded.Single-sourcing is the whole point. Two callers with two copies of "what an LLM step means" drift, and nothing tells you when they have.@@ -18,7 +18,7 @@ Single-sourcing is the whole point. Two callers with two copies of "what an LLM## The boot contract-Every kernel call must be servable on `RuntimeBoot.make()` ([`pipelex/runtime_boot.py`](https://github.com/Pipelex/pipelex/blob/main/pipelex/runtime_boot.py)) — the **runtime-only** composition root, with no interpreter constructed and no library loaded.+Every kernel call must be servable on `RuntimeBoot.make()` ([`pipelex/runtime_boot.py`](https://github.com/Pipelex/pipelex/blob/main/pipelex/runtime_boot.py)) — the **kernel-only** composition root, with no interpreter constructed and no library loaded.```pythonfrom pipelex.runtime_boot import RuntimeBoot@@ -50,8 +50,8 @@ Four gates hold this, and each covers something the others miss — see [Hub Lay| Gate | What it proves ||---|---|| `pipelex-dev check-hub-layering` | No kernel *module* imports the interpreter hub |-| `tests/unit/pipelex/test_runtime_layer_import_closure.py` | A kernel entry point *imports* clean |-| `tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py` | No kernel module reaches the exceptions aggregate — imports and bare strings alike |+| `tests/unit/pipelex/test_kernel_layer_import_closure.py` | A kernel entry point *imports* clean |+| `tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.py` | No kernel module reaches the exceptions aggregate — imports and bare strings alike || `tests/unit/pipelex/kernel/test_kernel_boot_contract.py` | Every kernel entry point **runs** on a keyless boot, swept afterwards — except the three `resolve_*_setting` helpers, which read the model deck (a separate question from this one) |Only the last one can see a function-local interpreter import, and it is **per-function**: it catches one inside `run_search` only by calling `run_search`. Every new kernel entry point owes it an arm.@@ -148,7 +148,7 @@ finally:Passing a `trace_context` adopts its `graph_id` as the run's `pipeline_run_id`. The two are one identity: letting them diverge would scatter a single run's usage events across two ids, because the registered-context emit path stamps the event log's id while the runner fallback stamps the metadata's — and a read-back keyed on either would silently miss the other's.-`pipelex.tracing` holds both halves a caller needs (`make_event_log` for a configured backend, `UsageAggregator` for the read-back) and is runtime-layer, so none of this costs the boot contract. The records that come out are the same [`TokensUsage` wire records](./tokens-usage-wire-records.md) an `/execute` response carries — pinned by an integration test that runs the same step through both callers and compares them.+`pipelex.tracing` holds both halves a caller needs (`make_event_log` for a configured backend, `UsageAggregator` for the read-back) and is kernel-layer, so none of this costs the boot contract. The records that come out are the same [`TokensUsage` wire records](./tokens-usage-wire-records.md) an `/execute` response carries — pinned by an integration test that runs the same step through both callers and compares them.---diff --git a/docs/under-the-hood/secrets-provider-plugins.md b/docs/under-the-hood/secrets-provider-plugins.mdindex 0280793d0..1b997cf23 100644--- a/docs/under-the-hood/secrets-provider-plugins.md+++ b/docs/under-the-hood/secrets-provider-plugins.md@@ -29,7 +29,8 @@ This is deliberately **not** a hub slot (those are orchestrator-coupled, claimedboot (Pipelex.setup)└─ build_registrar(config, builtin_plugins=BUILTIN_PLUGINS, …) # pure, import-light├─ for each built-in plugin (SecretsPlugin is one)- └─ for each installed "pipelex.plugins" entry point+ └─ for each installed entry point in the requested groups+ # "pipelex.plugins.kernel" alone on a kernel-only boot; both groups on a full one└─ plugin.register(registrar) # side-effect-free└─ registrar.add_secrets_provider(method=…, factory=…)└─ SecretsProviderRegistry(registrar.secrets_providers) # stored on the hub@@ -86,7 +87,7 @@ The factory is a plain callable stored at registration and **invoked only at the## The built-in `SecretsPlugin`-`pipelex/providers/secrets/secrets_plugin.py` is the reference secrets plugin. It is **core-unconditional** — a secrets provider is required infra, so it joins the runtime layer's `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES` — composed into `CORE_UNCONDITIONAL_PLUGIN_NAMES` at the boot entrypoint — and cannot be disabled into a boot with no secrets provider:+`pipelex/providers/secrets/secrets_plugin.py` is the reference secrets plugin. It is **core-unconditional** — a secrets provider is required infra, so it joins the kernel layer's `KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES` — composed into `CORE_UNCONDITIONAL_PLUGIN_NAMES` at the boot entrypoint — and cannot be disabled into a boot with no secrets provider:```pythonclass SecretsPlugin:@@ -130,6 +131,7 @@ Whether that token names an *installed* provider is validated at **registry look| Condition | Error ||-----------|-------|| `secrets_config.method` names no registered provider | `UnknownSecretsMethodError` (lists the registered methods) |+| published under the retired `pipelex.plugins` group | `RetiredPluginEntryPointGroupError` (names the plugins and the group each should move to) || two plugins register the same `method` | `DuplicateSecretsProviderError` (names both plugins) || `name` (`"secrets"`) in `plugins.disabled` | `CoreUnconditionalPluginDisabledError` || entry point raises while loading/registering | `BrokenPluginError` |@@ -145,17 +147,17 @@ A third-party secrets plugin is a distribution that:1. implements a `SecretsProviderAbstract` subclass — `get_required_secret` / `get_optional_secret`, the versioned `*_specific_version` reads, and `set_secret_as_env_var` — deferring any SDK import into those methods (import-light);2. defines a plugin class (`name`, `targets_api`, `register`) whose `register` calls `add_secrets_provider(method="<token>", factory=...)` — and nothing else;-3. advertises itself under the `pipelex.plugins` entry-point group:+3. advertises itself under the `pipelex.plugins.kernel` entry-point group — a secrets provider is kernel-layer, and the group is how a plugin declares that (see [Inference Backend Plugins](inference-backend-plugins.md#shipping-it-as-an-out-of-tree-plugin) for what each group means and what happens if you pick the wrong one; the pre-split `pipelex.plugins` group is retired and now fails startup):```toml# pyproject.toml of your plugin package-[project.entry-points."pipelex.plugins"]+[project.entry-points."pipelex.plugins.kernel"]vault_secrets = "pipelex_secrets_vault.plugin:VaultSecretsPlugin"```Installing the distribution makes the method selectable (`secrets_config.method = "vault"`); uninstalling removes it. No core change, no central registration list — *presence* is the source of truth. A discovered plugin can be quarantined without uninstalling via the `plugins.disabled` denylist (matched against the entry-point name *before* load, so a broken install can still be disabled to recover startup — see [Inference Backend Plugins](inference-backend-plugins.md) for the shared discovery/denylist machinery).-Use `pipelex plugins list` to see every discovered plugin, what each contributed, and its denylist state.+Use `pipelex plugins list` to see every discovered plugin, the entry-point group it was found under, what each contributed, and its denylist state. The **Group** column is the first thing to read when a plugin is missing: a built-in shows `—`, and an external plugin that resolved to the wrong layer shows it there.---diff --git a/docs/under-the-hood/storage-provider-plugins.md b/docs/under-the-hood/storage-provider-plugins.mdindex 0d3cc7d1a..486be5aa0 100644--- a/docs/under-the-hood/storage-provider-plugins.md+++ b/docs/under-the-hood/storage-provider-plugins.md@@ -27,7 +27,8 @@ This is deliberately **not** a hub slot (those are orchestrator-coupled, claimedboot (Pipelex.setup)└─ build_registrar(config, builtin_plugins=BUILTIN_PLUGINS, …) # pure, import-light├─ for each built-in plugin (StoragePlugin is one)- └─ for each installed "pipelex.plugins" entry point+ └─ for each installed entry point in the requested groups+ # "pipelex.plugins.kernel" alone on a kernel-only boot; both groups on a full one└─ plugin.register(registrar) # side-effect-free└─ registrar.add_storage_provider(method=…, factory=…)└─ StorageProviderRegistry(registrar.storage_providers) # stored on the hub@@ -79,7 +80,7 @@ The factory is a plain callable stored at registration and **invoked only at the## The built-in `StoragePlugin`-`pipelex/providers/storage/storage_plugin.py` is the reference storage plugin. It is **core-unconditional** — storage is required infra, so it joins the runtime layer's `RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES` — composed into `CORE_UNCONDITIONAL_PLUGIN_NAMES` at the boot entrypoint — and cannot be disabled into a boot with no storage:+`pipelex/providers/storage/storage_plugin.py` is the reference storage plugin. It is **core-unconditional** — storage is required infra, so it joins the kernel layer's `KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES` — composed into `CORE_UNCONDITIONAL_PLUGIN_NAMES` at the boot entrypoint — and cannot be disabled into a boot with no storage:```pythonclass StoragePlugin:@@ -132,6 +133,7 @@ Whether that token names an *installed* provider is validated at **registry look| Condition | Error ||-----------|-------|| `storage_config.method` names no registered provider | `UnknownStorageMethodError` (lists the registered methods) |+| published under the retired `pipelex.plugins` group | `RetiredPluginEntryPointGroupError` (names the plugins and the group each should move to) || two plugins register the same `method` | `DuplicateStorageProviderError` (names both plugins) || `name` (`"storage"`) in `plugins.disabled` | `CoreUnconditionalPluginDisabledError` || entry point raises while loading/registering | `BrokenPluginError` |@@ -147,17 +149,17 @@ A third-party storage plugin is a distribution that:1. implements a `StorageProviderAbstract` subclass — the three hooks `_load_with_metadata`, `_store`, and `public_url` — deferring any SDK import into those methods (import-light);2. defines a plugin class (`name`, `targets_api`, `register`) whose `register` calls `add_storage_provider(method="<token>", factory=...)` — and nothing else;-3. advertises itself under the `pipelex.plugins` entry-point group:+3. advertises itself under the `pipelex.plugins.kernel` entry-point group — a storage provider is kernel-layer, and the group is how a plugin declares that (see [Inference Backend Plugins](inference-backend-plugins.md#shipping-it-as-an-out-of-tree-plugin) for what each group means and what happens if you pick the wrong one; the pre-split `pipelex.plugins` group is retired and now fails startup):```toml# pyproject.toml of your plugin package-[project.entry-points."pipelex.plugins"]+[project.entry-points."pipelex.plugins.kernel"]azure_storage = "pipelex_storage_azure.plugin:AzureStoragePlugin"```Installing the distribution makes the method selectable (`storage_config.method = "azure"`); uninstalling removes it. No core change, no central registration list — *presence* is the source of truth. A discovered plugin can be quarantined without uninstalling via the `plugins.disabled` denylist (matched against the entry-point name *before* load, so a broken install can still be disabled to recover startup — see [Inference Backend Plugins](inference-backend-plugins.md) for the shared discovery/denylist machinery).-Use `pipelex plugins list` to see every discovered plugin, what each contributed, and its denylist state.+Use `pipelex plugins list` to see every discovered plugin, the entry-point group it was found under, what each contributed, and its denylist state. The **Group** column is the first thing to read when a plugin is missing: a built-in shows `—`, and an external plugin that resolved to the wrong layer shows it there.---diff --git a/drift.toml b/drift.tomlindex 91213fefa..89e7be850 100644--- a/drift.toml+++ b/drift.toml@@ -57,7 +57,7 @@ verify_commands = [][contracts.hub-layering-convention]description = "The hub-layering doc is the boundary's specification and must track the guard and the two hubs."-# The guard owns the rule (declared runtime layer, violation kinds, carve-outs); the two hub+# The guard owns the rule (declared kernel layer, violation kinds, carve-outs); the two hub# modules own the symbol partition the doc tabulates accessor by accessor. A symbol added to or# moved between them silently falsifies those tables, which is the staleness this contract exists# to catch. No verify command: `check-hub-layering` already gates `make check` and CI, so re-runningdiff --git a/pipelex/cli/commands/plugins_cmd.py b/pipelex/cli/commands/plugins_cmd.pyindex 6019e102c..298026881 100644--- a/pipelex/cli/commands/plugins_cmd.py+++ b/pipelex/cli/commands/plugins_cmd.py@@ -2,7 +2,7 @@ import typerfrom rich import boxfrom rich.table import Table-from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES+from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES, ENTRY_POINT_GROUPSfrom pipelex.plugins.discovery import build_registrarfrom pipelex.runtime_hub import get_consolefrom pipelex.system.configuration.config_loader import config_manager@@ -25,11 +25,13 @@ def plugins_list_command() -> None:config=config,builtin_plugins=BUILTIN_PLUGINS,core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,+ entry_point_groups=ENTRY_POINT_GROUPS,)table = Table(title="Pipelex plugins", show_header=True, header_style="bold cyan", box=box.SQUARE_DOUBLE_HEAD)table.add_column("Name", style="green")table.add_column("Origin", style="blue")+ table.add_column("Group", style="magenta")table.add_column("Status", style="yellow")table.add_column("API", justify="right")table.add_column("Contributions")@@ -37,6 +39,8 @@ def plugins_list_command() -> None:for discovery in registrar.discoveries:contributions = "\n".join(discovery.contributions) if discovery.contributions else (discovery.detail or "—")targets_api = str(discovery.targets_api) if discovery.targets_api is not None else "—"- table.add_row(discovery.name, discovery.origin, discovery.status, targets_api, contributions)+ # Built-ins arrive under no entry-point group — they are filed by layer in-tree instead.+ group = discovery.group or "—"+ table.add_row(discovery.name, discovery.origin, group, discovery.status, targets_api, contributions)console.print(table)diff --git a/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py b/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.pyindex ca2bd5c69..58b12e761 100644--- a/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py+++ b/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py@@ -1,7 +1,7 @@"""Command enforcing the two-hub layering boundary across ``pipelex/`` source and ``tests/``.`interpreter_hub` may import `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`.** The guard-checks the forbidden direction — a declared runtime-layer module may not import or name+checks the forbidden direction — a declared kernel-layer module may not import or name``pipelex.interpreter_hub``, nor *reach* it through a chain of module-level imports — plus thedead-module rule: nothing anywhere may still reference the deleted ``pipelex.hub``. The canonicalhuman-readable specification lives in ``docs/contribute/hub-layering.md``.@@ -13,7 +13,7 @@ hard-blocks on ANY violation; the only sanctioned exceptions are a ``TYPE_CHECKIimport and the inline ``# hub-layering: ignore`` escape hatch.The guard checks the *rule*. The *property* it protects — importing the inference layer loads zero-interpreter modules — is pinned separately by ``tests/unit/pipelex/test_runtime_layer_import_closure.py``, because+interpreter modules — is pinned separately by ``tests/unit/pipelex/test_kernel_layer_import_closure.py``, becausea stray import somewhere else entirely could break the property without touching a hub import."""@@ -25,7 +25,7 @@ from rich.markup import escapefrom rich.panel import Panelfrom pipelex.cli.dev_cli.commands.hub_layering_guard import (- RUNTIME_LAYER_PACKAGES,+ KERNEL_LAYER_PACKAGES,SCAN_ROOTS,SOURCE_ROOT,HubLayeringViolation,@@ -83,12 +83,12 @@ def check_hub_layering_cmd(*, quiet: bool = False) -> None:def _print_success_panel() -> None:"""Verbose success output (no violations)."""console = get_console()- layers = ", ".join(RUNTIME_LAYER_PACKAGES)+ layers = ", ".join(KERNEL_LAYER_PACKAGES)console.print()console.print(Panel(- f"[green]✓[/green] No hub-layering violations — no runtime-layer module imports the interpreter hub, "- f"directly or transitively.\n\n[dim]Runtime layer: {escape(layers)}[/dim]",+ f"[green]✓[/green] No hub-layering violations — no kernel-layer module imports the interpreter hub, "+ f"directly or transitively.\n\n[dim]Kernel layer: {escape(layers)}[/dim]",title="[bold green]Hub-layering Check: PASSED[/bold green]",border_style="green",padding=(1, 2),@@ -104,7 +104,7 @@ def _print_failure_panel(*, violations: list[HubLayeringViolation]) -> None:console.print(Panel(f"[red]✗[/red] {len(violations)} hub-layering violation(s) found.\n\n"- "[dim]The runtime layer must stay importable without loading the method interpreter — "+ "[dim]The kernel layer must stay importable without loading the method interpreter — ""each violation kind below names its remedy.[/dim]",title="[bold red]Hub-layering Check: FAILED[/bold red]",border_style="red",diff --git a/pipelex/cli/dev_cli/commands/hub_layering_guard.py b/pipelex/cli/dev_cli/commands/hub_layering_guard.pyindex 151bee2b6..2dbadcbab 100644--- a/pipelex/cli/dev_cli/commands/hub_layering_guard.py+++ b/pipelex/cli/dev_cli/commands/hub_layering_guard.py@@ -1,25 +1,25 @@"""Pure-stdlib AST core for the two-hub layering boundary guard.Pipelex has two layers and one hub each. The **interpreter** layer reads a method and executes it; the-**runtime** layer is the machinery present at execution time whatever is loaded. `interpreter_hub` may+**kernel** layer is the machinery present at execution time whatever is loaded. `interpreter_hub` mayimport `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`**. That single arrow is the-whole architecture, and the property it buys is measurable: importing the Pipelex runtime loads zero+whole architecture, and the property it buys is measurable: importing the Pipelex kernel layer loads zerointerpreter modules. The canonical human-readable specification lives in``docs/contribute/hub-layering.md``.This module holds the AST collection logic that mechanically enforces three rules:-1. **The layer rule.** A module in the declared runtime layer (:data:`RUNTIME_LAYER_PACKAGES`) may not- import ``pipelex.interpreter_hub``. Since `runtime_hub`'s own closure is what the runtime layer is,+1. **The layer rule.** A module in the declared kernel layer (:data:`KERNEL_LAYER_PACKAGES`) may not+ import ``pipelex.interpreter_hub``. Since `runtime_hub`'s own closure is what the kernel layer is,an import anywhere in it puts the interpreter back into every inference consumer.2. **The dead-module rule.** *No* scanned module may reference ``pipelex.hub``. That module wasdeleted rather than kept as an alias for either half, precisely so a stale import fails loudly —this rule closes the one hole in that guarantee (see below).-3. **The transitive rule.** No runtime-layer module may *reach* ``pipelex.interpreter_hub`` through+3. **The transitive rule.** No kernel-layer module may *reach* ``pipelex.interpreter_hub`` throughany chain of module-level imports either. Rules 1 and 2 are per-file and see one hop; this oneresolves the whole module-level import graph of ``pipelex/`` and does reachability over it. Itexists because the one-hop rules missed a live breach: four modules under the declared- runtime-layer ``pipelex.plugins`` package loaded ``interpreter_hub`` (and ~67 interpreter modules)+ kernel-layer ``pipelex.plugins`` package loaded ``interpreter_hub`` (and ~67 interpreter modules)through ``runtime_bridge``, ``pipeline`` and ``pipe_operators`` while both gates stayed green. Theremedy relocated those plugins, and this rule is what stops the next one recurring. The graphmodels the ancestor ``__init__.py`` files an import executes on the way to its target, so a breach@@ -38,7 +38,7 @@ prose is not a reference and is not flagged. A path assembled at runtime from f-concatenation is out of reach of any AST scan; nothing in the tree does that today.Note that ``runtime_hub`` is unrelated to the ``pipelex.runtime_bridge`` package despite the shared-word: the hub is the runtime layer's service container, while ``runtime_bridge`` is a transport.+word: the hub is the kernel layer's service container, while ``runtime_bridge`` is a transport.Two deliberate carve-outs, applying to every rule that is about what *loads*:@@ -87,15 +87,15 @@ TESTS_ROOT = Path("tests")#: The roots the full-tree check scans.SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)-#: The declared runtime layer: packages that must stay importable without loading the method interpreter.+#: The declared kernel layer: packages that must stay importable without loading the method interpreter.#:#: Entries are matched exact-or-dotted-prefix, so a bare *module* is a legal entry alongside the packages.#: `pipelex.runtime_hub` is one: the module at the centre of the rule would otherwise be exempt from it,-#: since nothing in the tuple is a prefix of it. Its closure *is* what the runtime layer means, so an+#: since nothing in the tuple is a prefix of it. Its closure *is* what the kernel layer means, so an#: `interpreter_hub` import there is the one that would break the property outright.#:-#: `pipelex.runtime_boot` is the second module entry, and for the mirror-image reason: it is the runtime-#: layer's *composition root*, so its closure is what "boot the runtime layer" costs. Declaring it is+#: `pipelex.runtime_boot` is the second module entry, and for the mirror-image reason: it is the kernel+#: layer's *composition root*, so its closure is what "boot the kernel layer" costs. Declaring it is#: what puts it inside this rule's domain at all — an undeclared module is not neutral, it is unpoliced,#: and this one is the single most tempting place in the tree to reach for an interpreter type, since#: the class it defines is subclassed by the boot that does need them. Its interpreter half,@@ -119,22 +119,22 @@ SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)#: rather than contradicts.#:#: `pipelex.plugins` and `pipelex.providers` are two entries for what used to be one package, and-#: both are runtime-layer: `plugins` is the plugin *mechanism* (the contract, the registrar, the+#: both are kernel-layer: `plugins` is the plugin *mechanism* (the contract, the registrar, the#: capability registries), `providers` the built-in vendor *adapters* that register through it.#: Splitting them did not move the boundary — it made the one-way dependency legible — so leaving-#: `pipelex.providers` undeclared would silently un-declare the largest runtime-layer package.+#: `pipelex.providers` undeclared would silently un-declare the largest kernel-layer package.#:#: `pipelex.graph`, `pipelex.tracing`, `pipelex.observer` and `pipelex.errors` are the four packages#: that were measured clean and left undeclared anyway, and the omission cost something: **an#: undeclared package is not neutral, it is unpoliced.** Omitting an entry makes this guard#: **quieter**, not louder — the transitive rule below filters its candidates through-#: :func:`is_runtime_layer`, so an undeclared package is excluded from the rule's domain rather than+#: :func:`is_kernel_layer`, so an undeclared package is excluded from the rule's domain rather than#: reported by it. That is exactly how `graph.graph_rendering` came to reach `interpreter_hub`#: through `pipeline.dry_run_pipeline` with every gate green; the bundle-driven half of that module#: is now `pipelex.pipeline.bundle_graph_rendering`, and `graph` is declared. What each entry is:#: `graph` is the run-graph data model, tracer and renderers, `tracing` the trace-event assembler#: feeding them, `observer` the run-observation hooks, `errors` the error taxonomy — all machinery-#: present at execution time whatever is loaded, which is the runtime layer's own definition.+#: present at execution time whatever is loaded, which is the kernel layer's own definition.#: `pipelex.test_extras` is here for the same reason: it ships, `pipelex.py` imports it at boot, and it#: measures clean — leaving it out would repeat the omission this entry documents.#:@@ -150,7 +150,7 @@ SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)#: top-level package accounted for.#: That the declaration is a claim rather than a hope is why it is asserted by a test.#: See the "Where core splits" section of ``docs/contribute/hub-layering.md``.-RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (+KERNEL_LAYER_PACKAGES: tuple[str, ...] = ("pipelex.cogt","pipelex.core","pipelex.errors",@@ -164,12 +164,12 @@ RUNTIME_LAYER_PACKAGES: tuple[str, ...] = ("pipelex.test_extras","pipelex.tools","pipelex.tracing",- # the runtime layer's own hub and its composition root — modules, not packages; see the note above+ # the kernel layer's own hub and its composition root — modules, not packages; see the note above"pipelex.runtime_hub","pipelex.runtime_boot",)-#: The interpreter layer's hub, which no runtime-layer module may import — directly or transitively.+#: The interpreter layer's hub, which no kernel-layer module may import — directly or transitively.#: Marked like :data:`DELETED_HUB_MODULE` below, for the same reason and against a different rule:#: this line *declares* the path rather than importing it, so without the marker rule 3 would read the#: guard's own configuration as a dynamic import and give the module a phantom edge to the hub.@@ -217,18 +217,18 @@ class HubLayeringViolationKind(StrEnum):match self:case HubLayeringViolationKind.INTERPRETER_HUB_IMPORT:return (- "a runtime-layer module may not import `pipelex.interpreter_hub` — take the value as an argument, "+ "a kernel-layer module may not import `pipelex.interpreter_hub` — take the value as an argument, ""or have the interpreter layer install it downward at boot (the `class_registry_scoping` pattern)")case HubLayeringViolationKind.INTERPRETER_HUB_TRANSITIVE:return (- "a runtime-layer module may not *reach* `pipelex.interpreter_hub` through its module-level imports "+ "a kernel-layer module may not *reach* `pipelex.interpreter_hub` through its module-level imports ""either — take the collaborator as an argument, or move the module to the layer it actually belongs ""to (the `interpreter_plugins` relocation)")case HubLayeringViolationKind.INTERPRETER_HUB_REFERENCE:return (- "a runtime-layer module may not name `pipelex.interpreter_hub` in a string either — a dynamic "+ "a kernel-layer module may not name `pipelex.interpreter_hub` in a string either — a dynamic ""import or patch target is the same dependency, just invisible to the import graph")case HubLayeringViolationKind.DEAD_HUB_REFERENCE:@@ -263,18 +263,18 @@ def references_module(*, candidate: str, target: str) -> bool:return candidate == target or candidate.startswith((f"{target}.", f"{target}:"))-def is_runtime_layer(*, module_qname: str) -> bool:- """Whether a module sits in the declared runtime layer.+def is_kernel_layer(*, module_qname: str) -> bool:+ """Whether a module sits in the declared kernel layer.- Matching is exact-or-dotted-prefix, so despite its name :data:`RUNTIME_LAYER_PACKAGES` may hold a+ Matching is exact-or-dotted-prefix, so despite its name :data:`KERNEL_LAYER_PACKAGES` may hold abare module as well as a package — an entry covers itself and everything under it."""- return any(module_qname == package or module_qname.startswith(f"{package}.") for package in RUNTIME_LAYER_PACKAGES)+ return any(module_qname == package or module_qname.startswith(f"{package}.") for package in KERNEL_LAYER_PACKAGES)def targets_for(*, module_qname: str) -> frozenset[str]:- """The forbidden module paths for one module: the dead hub always, plus the interpreter hub in the runtime layer."""- if is_runtime_layer(module_qname=module_qname):+ """The forbidden module paths for one module: the dead hub always, plus the interpreter hub in the kernel layer."""+ if is_kernel_layer(module_qname=module_qname):return frozenset({DELETED_HUB_MODULE, INTERPRETER_HUB_MODULE})return frozenset({DELETED_HUB_MODULE})@@ -487,7 +487,7 @@ class _ImportGraphCollector(ast.NodeVisitor):exactly as rules 1 and 2 match only their forbidden targets: an arbitrary ``pipelex.*`` string isas likely a plugin name or a config value, but a string that *is* the hub path is an``import_module`` or patch target in all but name. Rule 1 already catches such a string in a- runtime-layer module; what this closes is the same string in an *intermediary*, which sits in no+ kernel-layer module; what this closes is the same string in an *intermediary*, which sits in nodeclared layer and so is rule 1's business for the dead hub only."""@@ -694,13 +694,13 @@ def shortest_import_path(*, graph: ImportGraph, start: str, target: str) -> listdef collect_transitive_violations(*, root: Path) -> list[HubLayeringViolation]:- """Every runtime-layer module that *reaches* the interpreter hub through its module-level imports.+ """Every kernel-layer module that *reaches* the interpreter hub through its module-level imports.A **direct** import is reported by the one-hop layer rule instead, with its own remedy, so a chainof one hop is skipped here rather than double-reported. A finding cannot be silenced where it isreported: the escape hatch marks a single *import* as reviewed (which removes that edge from thegraph, exactly as a ``TYPE_CHECKING`` deferral does), never a module's transitive reach. This rule- fires when the declaration claims a module is runtime-layer while the import graph says otherwise,+ fires when the declaration claims a module is kernel-layer while the import graph says otherwise,and the fix is to move the module or invert the dependency.Args:@@ -723,7 +723,7 @@ def collect_transitive_violations(*, root: Path) -> list[HubLayeringViolation]:reaching = modules_reaching(graph=graph, target=INTERPRETER_HUB_MODULE)violations: list[HubLayeringViolation] = []- for qname in sorted(module for module in reaching if is_runtime_layer(module_qname=module)):+ for qname in sorted(module for module in reaching if is_kernel_layer(module_qname=module)):chain = shortest_import_path(graph=graph, start=qname, target=INTERPRETER_HUB_MODULE)if len(chain) < 3:continuediff --git a/pipelex/core/exceptions.py b/pipelex/core/exceptions.pyindex b2f57aeb3..02fc828c6 100644--- a/pipelex/core/exceptions.py+++ b/pipelex/core/exceptions.py@@ -33,7 +33,7 @@ class PipelexBundleBlueprintValidationErrorData(BaseModel):blueprint validation (before pipe instantiation).Lives here rather than beside the parser that raises it: `pipeline/` and `libraries/`- carry it into every runtime-layer import closure, so an interpreter-layer home would+ carry it into every kernel-layer import closure, so an interpreter-layer home wouldmake the boundary the closure test guards unenforceable. It is the third of the threestructured error-data models in this module, all keyed on `PipeValidationErrorType`."""diff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.pyindex cc291d661..6ecb531d5 100644--- a/pipelex/core/pipes/exceptions.py+++ b/pipelex/core/pipes/exceptions.py@@ -62,9 +62,9 @@ class PipeRunError(PipelexError):"""A pipe failed while running, with the run mode and the pipe it failed in.Base of the run-failure family, and it sits here rather than with the pipe-run machinery because- the runtime layer subclasses it: `PipeRunInputsError` and `OptionalValueAbsentError` in+ the kernel layer subclasses it: `PipeRunInputsError` and `OptionalValueAbsentError` in`core.pipes.inputs.exceptions` derive from it, so filing the base with the machinery put a- module of `pipe_run` — and its whole import chain — inside every runtime import closure.+ module of `pipe_run` — and its whole import chain — inside every kernel import closure."""def __init__(self, message: str, run_mode: PipeRunMode, pipe_code: str):diff --git a/pipelex/graph/graph_rendering.py b/pipelex/graph/graph_rendering.pyindex a406bc394..a2d1d3d10 100644--- a/pipelex/graph/graph_rendering.py+++ b/pipelex/graph/graph_rendering.py@@ -1,6 +1,6 @@"""Rendering a run graph to disk, from a spec that already exists.-Runtime-layer: everything here takes a :class:`GraphSpec` and turns it into files. Producing that+Kernel-layer: everything here takes a :class:`GraphSpec` and turns it into files. Producing thatspec from a *bundle* needs a loaded method, so those helpers live one layer up, in``pipelex.pipeline.bundle_graph_rendering``."""diff --git a/pipelex/interpreter_hub.py b/pipelex/interpreter_hub.pyindex b7ac885d3..5db8f932b 100644--- a/pipelex/interpreter_hub.py+++ b/pipelex/interpreter_hub.py@@ -6,7 +6,7 @@ pipe router, the pipe runner, the pipeline manager, and the PipeFunc executor. Tthat reads the program and executes it — hence *interpreter*.**The one rule:** this module MAY import ``runtime_hub``; ``runtime_hub`` must never import this-one. As it happens the arrow is currently unused — the only runtime-layer thing this module needs+one. As it happens the arrow is currently unused — the only kernel-layer thing this module needsis the class-registry scoping slot, which lives below both hubs in``system.registries.class_registry_access``. See ``docs/contribute/hub-layering.md``."""@@ -201,7 +201,7 @@ def get_interpreter_hub() -> InterpreterHub:def set_interpreter_hub(interpreter_hub: InterpreterHub):- """Install ``interpreter_hub`` as the process singleton, and hand the runtime layer its scoping resolver.+ """Install ``interpreter_hub`` as the process singleton, and hand the kernel layer its scoping resolver.Installing the resolver here rather than at an explicit boot step means library scoping isactive exactly when an InterpreterHub exists — the invariant ``get_class_registry`` relies on, anddiff --git a/pipelex/interpreter_plugins/builtins.py b/pipelex/interpreter_plugins/builtins.pyindex a968d1443..93b2e3ef5 100644--- a/pipelex/interpreter_plugins/builtins.py+++ b/pipelex/interpreter_plugins/builtins.py@@ -1,25 +1,26 @@"""The composition root's view of the built-in plugins: both layers' halves, welded into one list.-``pipelex.providers`` — the built-in vendor adapters — is a declared runtime-layer package, so it may+``pipelex.providers`` — the built-in vendor adapters — is a declared kernel-layer package, so it maynot name anything that reaches ``interpreter_hub``, which the two plugins next door do byconstruction: their job is to construct interpreter-layer objects (a ``DirectOrchestrator``, a``DirectBundleValidator``, a ``DirectPipeFuncExecutor``). This package is the interpreter-side homefor them, and it is *allowed* to import downward, so composing the two halves here is legal where-doing it in the runtime adapters' own manifest was the weld that made "the adapters are a runtime+doing it in the kernel adapters' own manifest was the weld that made "the adapters are a kernellayer" false.There is still exactly one place that answers "what are the built-in plugins, both layers" — it justlives in the layer permitted to do the welding. The lists below are what ``Pipelex.setup`` (theinterpreter boot) and the ``pipelex plugins list`` diagnostic pass into ``build_registrar``. The third-caller is the runtime layer's own composition root, ``pipelex/runtime_boot.py``, which calls the same-function but defaults to ``RUNTIME_BUILTIN_PLUGINS`` alone — it may not name this module.+caller is the kernel layer's own composition root, ``pipelex/runtime_boot.py``, which calls the same+function but defaults to ``KERNEL_BUILTIN_PLUGINS`` alone — it may not name this module.See ``docs/contribute/hub-layering.md``."""from pipelex.interpreter_plugins.direct.direct_plugin import DirectOrchestratorPluginfrom pipelex.interpreter_plugins.pipe_func.pipe_func_plugin import PipeFuncPluginfrom pipelex.plugins.contract import PipelexPlugin-from pipelex.providers.builtins import RUNTIME_BUILTIN_PLUGINS, RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES+from pipelex.plugins.plugin_group import PluginGroup+from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS, KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES# The interpreter-layer half: plugins whose adapters name the method interpreter. Both are# core-unconditional — in-process execution is required infra.@@ -35,7 +36,12 @@ INTERPRETER_BUILTIN_PLUGINS: list[PipelexPlugin] = [INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES: frozenset[str] = frozenset({"direct", "pipe_func"})# The plugins Pipelex ships with — discovered at boot ahead of any external entry-point plugin.-BUILTIN_PLUGINS: list[PipelexPlugin] = [*INTERPRETER_BUILTIN_PLUGINS, *RUNTIME_BUILTIN_PLUGINS]+BUILTIN_PLUGINS: list[PipelexPlugin] = [*INTERPRETER_BUILTIN_PLUGINS, *KERNEL_BUILTIN_PLUGINS]# Every built-in plugin core requires unconditionally, both layers.-CORE_UNCONDITIONAL_PLUGIN_NAMES: frozenset[str] = INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES | RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES+CORE_UNCONDITIONAL_PLUGIN_NAMES: frozenset[str] = INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES | KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES++# The entry-point groups a method-running process reads: both, since it is the layer that may load+# either half. A kernel-only boot reads ``KERNEL_ENTRY_POINT_GROUPS`` instead — the omission is the+# guarantee, since a group that is never queried has no entry point to import.+ENTRY_POINT_GROUPS: tuple[PluginGroup, ...] = (PluginGroup.KERNEL, PluginGroup.INTERPRETER)diff --git a/pipelex/kernel/__init__.py b/pipelex/kernel/__init__.pyindex e513f4dda..c4f1b0fe2 100644--- a/pipelex/kernel/__init__.py+++ b/pipelex/kernel/__init__.py@@ -13,7 +13,7 @@ this repo something; see ``docs/contribute/hub-layering.md``.**Layering.** The caller-facing API is hub-free: an explicit :class:`~pipelex.kernel.pipelex_kernel.PipelexKernel`and explicit arguments, never an ambient lookup. Kernel *internals* may use ``pipelex.runtime_hub``— never ``pipelex.interpreter_hub``, directly or transitively. ``pipelex.kernel`` is declared in the-guard's ``RUNTIME_LAYER_PACKAGES`` and pinned by a test, because **an undeclared package is not+guard's ``KERNEL_LAYER_PACKAGES`` and pinned by a test, because **an undeclared package is notneutral, it is unpoliced**: both the layer rule and the transitive rule filter their candidatesthrough that declaration, so omitting the entry makes the guard quieter rather than louder.@@ -21,10 +21,10 @@ through that declaration, so omitting the entry makes the guard quieter rather tre-export aggregate, and never let this ``__init__.py`` become one. For most of the tree that is astyle rule (the repo's "direct full-path imports everywhere"); here it is a *layering* property — amodule that re-exports across layers is a layer boundary with the sign filed off, and importing one-symbol from it drags every interpreter package it re-exports into the runtime closure. Five vendor+symbol from it drags every interpreter package it re-exports into the kernel closure. Five vendoradapters once loaded interpreter modules apiece through exactly that hole with every gate green.The mechanical half is bought by the declaration above:-``tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py`` walks every declared package+``tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.py`` walks every declared packageand fails on imports and bare strings alike, module-level or function-local.**Every import stays at module top level.** A function-local import is invisible to the static@@ -63,7 +63,7 @@ argument.(``pipelex/runtime_boot.py``) with no interpreter constructed and no library loaded.``tests/unit/pipelex/kernel/test_kernel_boot_contract.py`` is what proves it: it boots keyless,**calls every entry point**, and sweeps ``sys.modules`` afterwards. Treat that as the gate rather-than as one of two — ``tests/unit/pipelex/test_runtime_layer_import_closure.py`` covers only what+than as one of two — ``tests/unit/pipelex/test_kernel_layer_import_closure.py`` covers only whatits ``pipelex.kernel.pipelex_kernel`` entry point imports, and the façade is LLM-only, so most ofthis package sits outside its closure. **Every new entry point here gets an arm in thatsubprocess.** The rule is not ceremony: the sweep is the only gate that can see a function-localdiff --git a/pipelex/kernel/llm_prompt_content.py b/pipelex/kernel/llm_prompt_content.pyindex d1d44863a..26dfce734 100644--- a/pipelex/kernel/llm_prompt_content.py+++ b/pipelex/kernel/llm_prompt_content.py@@ -1,6 +1,6 @@"""Prompt assembly: templates plus memory-borne images and documents, into one `LLMPrompt`.-This is the runtime-layer home of what `LLMPromptBlueprint.make_llm_prompt` used to do inline.+This is the kernel-layer home of what `LLMPromptBlueprint.make_llm_prompt` used to do inline.`LLMPromptBlueprint` stays where it is — it is a language artifact, what `.mthds` parses into, and itkeeps its parse-and-validate role — but it now maps down onto :func:`assemble_llm_prompt` rather thanholding the semantics, so the interpreter and a programmatic caller assemble prompts through thediff --git a/pipelex/kernel/pipelex_kernel.py b/pipelex/kernel/pipelex_kernel.pyindex abcdf8ca6..ad13e0216 100644--- a/pipelex/kernel/pipelex_kernel.py+++ b/pipelex/kernel/pipelex_kernel.py@@ -2,7 +2,7 @@The semantics live in the module-level ops functions beside this one; the interpreter's operatorclasses call those directly, because they already hold everything the façade would supply. This-class exists for the *other* caller — the programmatic one, embedding the runtime — and it holds+class exists for the *other* caller — the programmatic one, embedding the kernel — and it holdsexactly two things, both of them run-scoped identity:- ``job_metadata`` — the **run-level** metadata. It is not what a step runs under: each call mints@@ -25,7 +25,7 @@ every step's :class:`JobMetadata`, which is what the cogt leaf reads to decide wemit a usage event. Opening the event log, registering it (``get_report_delegate().set_event_log``),reading the events back and clearing the registration stay the caller's, and they are the whole ofwhat stands between a kernel run and the interpreter's cost reporting. ``pipelex/tracing/`` holds-both halves a caller needs (``make_event_log``, ``UsageAggregator``) and is runtime-layer, so none of+both halves a caller needs (``make_event_log``, ``UsageAggregator``) and is kernel-layer, so none ofthis costs the boot contract. See ``docs/under-the-hood/pipelex-kernel.md``."""diff --git a/pipelex/kernel/prompt_references.py b/pipelex/kernel/prompt_references.pyindex 9af4077ad..03ec9ef67 100644--- a/pipelex/kernel/prompt_references.py+++ b/pipelex/kernel/prompt_references.py@@ -2,7 +2,7 @@These describe a *resolution* — "the variable at this path holds an `ImageContent`, fetch it andregister it" — which is execution semantics, not language. They live here rather than under-`pipe_operators/` because the kernel is what resolves them, and a runtime-layer module may not+`pipe_operators/` because the kernel is what resolves them, and a kernel-layer module may notimport an interpreter-layer one; the blueprints that parse `.mthds` into them import upward, whichis the sanctioned direction. Same move `core/` made with `ConceptProviderAbstract`: the semanticsmigrate to the layer that owns them, and the language artifact keeps its parse-and-validate role.diff --git a/pipelex/libraries/pipe/pipe_library_abstract.py b/pipelex/libraries/pipe/pipe_library_abstract.pyindex 3c7cd1a22..3a844eaba 100644--- a/pipelex/libraries/pipe/pipe_library_abstract.py+++ b/pipelex/libraries/pipe/pipe_library_abstract.py@@ -11,7 +11,7 @@ class PipeLibraryAbstract(ABC):takes pipe resolution as a parameter. The two places that follow a pipe reference found *inside* apipe graph — a condition's mapped pipes and a sequence's last step, both in`pipe_machinery/rendering/` — are interpreter-layer and call `interpreter_hub.get_required_pipe`- directly. Split the read half out if and when a runtime-layer caller needs it.+ directly. Split the read half out if and when a kernel-layer caller needs it."""@abstractmethoddiff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex 3a13e5d51..902d43382 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -29,7 +29,7 @@ from pipelex.cogt.inference.inference_manager import InferenceManagerfrom pipelex.cogt.models.model_manager_abstract import ModelManagerAbstractfrom pipelex.config import get_config, get_pipe_func_execution_modefrom pipelex.interpreter_hub import InterpreterHub, set_interpreter_hub-from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES+from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES, ENTRY_POINT_GROUPSfrom pipelex.libraries.library_manager import LibraryManagerfrom pipelex.libraries.library_manager_abstract import LibraryManagerAbstractfrom pipelex.observer.observer_protocol import ObserverProtocol@@ -66,7 +66,7 @@ class Pipelex(RuntimeBoot):config_overrides: dict[str, Any] | None = None,) -> None:# Two hubs, two lifecycles: RuntimeHub is process-scoped infrastructure, InterpreterHub is the- # library-scoped method machinery. Runtime is constructed first because it is the lower layer,+ # library-scoped method machinery. The kernel half is constructed first because it is the lower layer,# so it reads first — not because installing the InterpreterHub needs it: that install only# stores the class-registry scoping resolver, which resolves lazily at call time.super().__init__(config_dir=config_dir, config_cls=config_cls, config_overrides=config_overrides)@@ -107,9 +107,10 @@ class Pipelex(RuntimeBoot):msg = f"The Pipelex setup method does not support any additional arguments: {kwargs}"raise PipelexSetupError(msg)- # The runtime layer first, with the *composed* plugin manifests: this process will run methods,+ # The kernel layer first, with the *composed* plugin manifests: this process will run methods,# so it needs the interpreter-touching built-ins (the `direct` orchestrator, the built-in- # PipeFunc executor modes) alongside the runtime half a bare RuntimeBoot discovers.+ # PipeFunc executor modes) alongside the kernel half a bare RuntimeBoot discovers — and, for+ # installed plugins, both entry-point groups rather than the kernel group alone.super().setup(integration_mode=integration_mode,needs_inference=needs_inference,@@ -117,6 +118,7 @@ class Pipelex(RuntimeBoot):needs_model_specs=needs_model_specs,builtin_plugins=BUILTIN_PLUGINS,core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,+ entry_point_groups=ENTRY_POINT_GROUPS,class_registry=class_registry,secrets_provider=secrets_provider,storage_provider=storage_provider,@@ -133,7 +135,7 @@ class Pipelex(RuntimeBoot):# Everything below needs a method to be loadable. Nothing the runtime setup above does# consumes any of it, which is what lets these be a tail rather than an interleaving; the two# values that cross the seam go the other way (``self._plugin_registrar`` and- # ``self.multi_observer``, both built by the runtime half and read here).+ # ``self.multi_observer``, both built by the kernel half and read here).plugin_registrar = self._plugin_registrarif plugin_registrar is None:diff --git a/pipelex/pipeline/bundle_graph_rendering.py b/pipelex/pipeline/bundle_graph_rendering.pyindex e0d838bbb..f549a2cfc 100644--- a/pipelex/pipeline/bundle_graph_rendering.py+++ b/pipelex/pipeline/bundle_graph_rendering.py@@ -1,7 +1,7 @@"""Producing a run graph for a *bundle*, by dry-running it.Interpreter-layer counterpart of ``pipelex.graph.graph_rendering``: these helpers take a bundle path,-load and dry-run the method to obtain a :class:`GraphSpec`, then hand it to the runtime-layer renderer.+load and dry-run the method to obtain a :class:`GraphSpec`, then hand it to the kernel-layer renderer.The split is along "do I need a loaded method?", which is the hub layering boundary's own question —see ``docs/contribute/hub-layering.md``."""diff --git a/pipelex/plugins/contract.py b/pipelex/plugins/contract.pyindex 0b31f3855..533b44527 100644--- a/pipelex/plugins/contract.py+++ b/pipelex/plugins/contract.py@@ -16,7 +16,11 @@ if TYPE_CHECKING:# process-global provider registries (``storage_config.method`` / ``secrets_config.method`` pick# the factory at boot). DX-1 batches both menu additions under this single bump so external plugins# re-declare ``targets_api`` only once.-PLUGIN_API_VERSION: int = 3+#+# v4 split the single ``pipelex.plugins`` entry-point group into the two ``PluginGroup`` groups+# below: a plugin now declares its layer by the group it publishes under, and a kernel-group plugin+# may no longer reach the interpreter tier of the menu.+PLUGIN_API_VERSION: int = 4@runtime_checkable@@ -27,18 +31,30 @@ class PipelexPlugin(Protocol):hub-slot claims, HTTP-error mappers and teardown callbacks by calling the menumethods on the ``PluginRegistrar`` it is handed.- **Invariant — a plugin belongs to exactly one layer.** Its adapters are either all runtime-layer- (an inference backend, a storage or secrets provider) or all interpreter-layer (anything that- constructs a `Pipe`-aware object: an orchestrator, a bundle validator, a PipeFunc executor). A- capability that needs both is two plugins, because the built-in ones are filed by layer —- ``pipelex.providers`` for the runtime half, ``pipelex.interpreter_plugins`` for the interpreter- half — and a plugin straddling the two would put the method interpreter back into every runtime- import closure. External plugins are discovered through an entry point and so live in no declared- layer, but the same rule keeps them honest about what they pull in.+ **Invariant — a plugin belongs to exactly one layer, and it is the highest tier it contributes+ to.** A plugin that contributes *any* interpreter-layer capability — anything constructing a+ `Pipe`-aware object: an orchestrator, a bundle validator, a PipeFunc executor — is an+ interpreter-layer plugin and publishes under ``PluginGroup.INTERPRETER``. It may contribute+ kernel-tier capabilities alongside them, and ours does: it registers an orchestrator+ (interpreter-tier) *and* an HTTP-error mapper (kernel-tier). Do not split such a plugin in two.+ A plugin contributing only kernel-tier capabilities — an inference backend, a model lister, a+ storage or secrets provider, an HTTP-error mapper — is a kernel-layer plugin and publishes under+ ``PluginGroup.KERNEL``.++ An external plugin declares its layer by the group it publishes under, and the registrar enforces+ the declaration in the one direction that matters: a kernel-group plugin registering an+ interpreter-layer capability fails loud at register time (``PluginLayerViolationError``), because+ a kernel-only boot reads the kernel group and must never end up constructing a `Pipe`-aware+ object. The reverse needs no rule — a kernel-only boot never reads the interpreter group at all.+ Publishing the same plugin under *both* groups is its own error+ (``PluginDeclaredInMultipleGroupsError``): the group is the declaration, so declaring two says+ nothing. Built-ins carry no group and are filed by layer in-tree instead — ``pipelex.providers``+ for the kernel half, ``pipelex.interpreter_plugins`` for the interpreter half — where the+ hub-layering guard polices the same boundary statically.Note that ``pipelex.providers`` is where the built-in *adapters* live, while this module and therest of ``pipelex.plugins`` are the *mechanism* they register through. Both packages are- runtime-layer; the split is about direction, not about layers — adapters depend on the mechanism+ kernel-layer; the split is about direction, not about layers — adapters depend on the mechanismand never the reverse. An external plugin imports ``pipelex.plugins.contract`` and``pipelex.plugins.registrar``, so it is unaffected by where the built-in adapters are filed.diff --git a/pipelex/plugins/discovery.py b/pipelex/plugins/discovery.pyindex 8461fafa6..0c61661aa 100644--- a/pipelex/plugins/discovery.py+++ b/pipelex/plugins/discovery.py@@ -1,5 +1,5 @@import importlib.metadata-from typing import TYPE_CHECKING, cast+from typing import TYPE_CHECKING, NamedTuple, castfrom pipelex import logfrom pipelex.plugins.contract import PLUGIN_API_VERSION, PipelexPlugin@@ -7,8 +7,11 @@ from pipelex.plugins.exceptions import (BrokenPluginError,CoreUnconditionalPluginDisabledError,PluginApiVersionMismatchError,+ PluginDeclaredInMultipleGroupsError,PluginError,+ RetiredPluginEntryPointGroupError,)+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.plugins.registrar import PluginDiscovery, PluginOrigin, PluginRegistrar, PluginStatusif TYPE_CHECKING:@@ -16,10 +19,25 @@ if TYPE_CHECKING:from pipelex.system.configuration.configs import PipelexConfig-# External plugins advertise themselves under this entry-point group:-# [project.entry-points."pipelex.plugins"]+# External plugins advertise themselves under one of the two ``PluginGroup`` groups, which is how+# they declare their layer:+# [project.entry-points."pipelex.plugins.kernel"]# my_plugin = "my_package:make_plugin"-ENTRY_POINT_GROUP = "pipelex.plugins"+#+# The single group they all used before the layer split. Nothing reads it any more, so a plugin left+# behind there would silently never be discovered — probed below, and fail-loud.+RETIRED_ENTRY_POINT_GROUP = "pipelex.plugins"+++class GroupedEntryPoint(NamedTuple):+ """One installed entry point together with the group it was found under.++ A ``NamedTuple`` because it holds an ``EntryPoint`` (a non-pydantic third-party type) and is+ never serialized. The pairing is what lets the registrar attribute a layer to the plugin.+ """++ group: PluginGroup+ entry_point: importlib.metadata.EntryPointdef build_registrar(@@ -27,57 +45,67 @@ def build_registrar(config: "PipelexConfig",builtin_plugins: "Sequence[PipelexPlugin]",core_unconditional_plugin_names: frozenset[str],+ entry_point_groups: "Sequence[PluginGroup]",) -> PluginRegistrar:"""Discover every plugin and let each register itself into a fresh registrar.A **pure function**: it touches no global state and constructs no client/SDK,so it is safe to call more than once (it runs at boot and again in the- ``pipelex plugins list`` diagnostic command). Iterates ``builtin_plugins`` first, then external- ``pipelex.plugins`` entry points; version-checks each; skips (and logs) any- plugin named in ``config.plugins.disabled`` — externals are denylisted by their+ ``pipelex plugins list`` diagnostic command). Iterates ``builtin_plugins`` first, then the+ external entry points published under ``entry_point_groups``; version-checks each; skips (and+ logs) any plugin named in ``config.plugins.disabled`` — externals are denylisted by theirentry-point name *before* ``load()`` so a broken installed plugin can still bedisabled; and is fail-loud on every conflict (duplicate backend/mode/slot,- version mismatch, broken plugin).+ version mismatch, broken plugin, a kernel-group plugin reaching the interpreter tier).Args:config: The fully-resolved config; supplies the ``plugins.disabled`` denylist and is handedto the registrar for the plugins that read it.builtin_plugins: The built-ins to discover, in order. Injected rather than imported: some- built-ins adapt interpreter-layer ports, and this module is runtime-layer, so importing- the list here would put the method interpreter back into every runtime closure. The+ built-ins adapt interpreter-layer ports, and this module is kernel-layer, so importing+ the list here would put the method interpreter back into every kernel closure. Thecomposed list lives in ``pipelex.interpreter_plugins.builtins`` — the layer allowed toweld the two halves.core_unconditional_plugin_names: The built-in names that may not be denylisted. Injected forthe same reason and from the same module, so the constant never splits away from theplugins it describes.+ entry_point_groups: The groups to read installed plugins from — the kernel group alone for a+ kernel-only boot, both for the interpreter boot. Injected for the same reason as the two+ above: naming which groups compose a full boot is a layer decision, and this module is+ kernel-layer. A group left out is never queried, so its plugins' modules are never+ imported — which is what a kernel-only trust-base claim actually rests on."""+ _reject_retired_entry_point_group()registrar = PluginRegistrar(config=config)disabled = set(config.plugins.disabled)- # Built-ins are already instantiated, so their name is known up front.+ # Built-ins are already instantiated, so their name is known up front. They carry no group: they+ # are filed by layer in-tree, and the caller passes only the halves its layer may run.for plugin in builtin_plugins:if _skip_if_disabled(registrar=registrar,name=plugin.name,origin=PluginOrigin.BUILTIN,targets_api=plugin.targets_api,+ group=None,disabled=disabled,core_unconditional_plugin_names=core_unconditional_plugin_names,):continue- _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.BUILTIN)+ _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.BUILTIN, group=None)# External entry points: denylist by entry-point name *before* load(), so a# broken/dependency-missing installed plugin can still be recovered by disabling# it. A working external plugin may set a ``.name`` that differs from its# entry-point name; the post-load check honors the denylist on that too, so# either name disables it.- for entry_point in _external_entry_points():+ for group, entry_point in _external_entry_points(groups=entry_point_groups):if _skip_if_disabled(registrar=registrar,name=entry_point.name,origin=PluginOrigin.EXTERNAL,targets_api=None,+ group=group,disabled=disabled,core_unconditional_plugin_names=core_unconditional_plugin_names,):@@ -88,11 +116,12 @@ def build_registrar(name=plugin.name,origin=PluginOrigin.EXTERNAL,targets_api=plugin.targets_api,+ group=group,disabled=disabled,core_unconditional_plugin_names=core_unconditional_plugin_names,):continue- _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.EXTERNAL)+ _register_plugin(registrar=registrar, plugin=plugin, origin=PluginOrigin.EXTERNAL, group=group)return registrar@@ -103,6 +132,7 @@ def _skip_if_disabled(name: str,origin: PluginOrigin,targets_api: int | None,+ group: PluginGroup | None,disabled: set[str],core_unconditional_plugin_names: frozenset[str],) -> bool:@@ -122,14 +152,57 @@ def _skip_if_disabled(origin=origin,status=PluginStatus.DISABLED,targets_api=targets_api,+ group=group,detail="disabled via plugins.disabled",))return True-def _external_entry_points() -> list[importlib.metadata.EntryPoint]:- return list(importlib.metadata.entry_points(group=ENTRY_POINT_GROUP))+def _external_entry_points(*, groups: "Sequence[PluginGroup]") -> list[GroupedEntryPoint]:+ """Every installed entry point in the requested groups, paired with the group it came from.++ A group not requested is not queried, so nothing published under it is even named here — the+ ``load()`` that would import an interpreter-layer module can never be reached from a kernel-only+ boot.+ """+ grouped = [+ GroupedEntryPoint(group=group, entry_point=entry_point) for group in groups for entry_point in importlib.metadata.entry_points(group=group)+ ]+ _reject_multi_group_declaration(grouped=grouped)+ return grouped+++def _reject_multi_group_declaration(*, grouped: "Sequence[GroupedEntryPoint]") -> None:+ """Fail loud on one plugin name declared under more than one of the requested groups.++ Scoped to the groups actually read, which is also the only place the harm exists: reading two+ groups is what loads such a plugin twice and runs its ``register`` twice. A kernel-only boot+ reads one group, sees the plugin once, and is unaffected — so probing the group it deliberately+ does not query would buy a diagnostic for a boot that has nothing to diagnose.+ """+ groups_by_name: dict[str, set[str]] = {}+ for candidate in grouped:+ groups_by_name.setdefault(candidate.entry_point.name, set()).add(candidate.group)+ for name, declared_groups in groups_by_name.items():+ if len(declared_groups) > 1:+ raise PluginDeclaredInMultipleGroupsError(plugin_name=name, groups=list(declared_groups))+++def _reject_retired_entry_point_group() -> None:+ """Fail loud on any plugin still published under the pre-split single group.++ Probed on every build, whichever groups the caller asked for: a plugin left behind is broken in+ both boots, and the symptom without this — a capability that is simply absent, with no error —+ is the expensive one to diagnose.+ """+ stragglers = [entry_point.name for entry_point in importlib.metadata.entry_points(group=RETIRED_ENTRY_POINT_GROUP)]+ if stragglers:+ raise RetiredPluginEntryPointGroupError(+ plugin_names=stragglers,+ retired_group=RETIRED_ENTRY_POINT_GROUP,+ groups=list(PluginGroup),+ )def _load_external_plugin(entry_point: importlib.metadata.EntryPoint) -> PipelexPlugin:@@ -143,13 +216,13 @@ def _load_external_plugin(entry_point: importlib.metadata.EntryPoint) -> Pipelexraise BrokenPluginError(plugin_name=entry_point.name, reason=f"failed to load entry point: {exc}") from exc-def _register_plugin(*, registrar: PluginRegistrar, plugin: PipelexPlugin, origin: PluginOrigin) -> None:+def _register_plugin(*, registrar: PluginRegistrar, plugin: PipelexPlugin, origin: PluginOrigin, group: PluginGroup | None) -> None:targets_api = getattr(plugin, "targets_api", None)if targets_api != PLUGIN_API_VERSION:raise PluginApiVersionMismatchError(plugin_name=getattr(plugin, "name", "<unknown>"), targets_api=targets_api, supported_api=PLUGIN_API_VERSION)- registrar.begin_plugin(name=plugin.name, origin=origin, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name=plugin.name, origin=origin, targets_api=PLUGIN_API_VERSION, group=group)try:plugin.register(registrar)except PluginError:diff --git a/pipelex/plugins/exceptions.py b/pipelex/plugins/exceptions.pyindex b0a5b2b74..11a6fd892 100644--- a/pipelex/plugins/exceptions.py+++ b/pipelex/plugins/exceptions.py@@ -174,6 +174,92 @@ class CoreUnconditionalPluginDisabledError(PluginError):super().__init__(message)+class PluginLayerViolationError(PluginError):+ """A kernel-group plugin registered an interpreter-layer capability.++ The entry-point group a plugin publishes under declares its layer, and a kernel-only boot reads+ the kernel group alone precisely so no interpreter-layer object is ever constructed there. A+ plugin whose declaration and menu calls disagree would defeat that: installed as kernel, loaded+ into a kernel-only process, it would hand back a ``Pipe``-aware object. Caught at register time,+ before anything it contributed is wired.+ """++ def __init__(self, *, plugin_name: str, capability: str, declared_group: str, interpreter_group: str):+ self.plugin_name = plugin_name+ self.capability = capability+ self.declared_group = declared_group+ self.interpreter_group = interpreter_group+ message = (+ f"Plugin '{plugin_name}' is published under the entry-point group '{declared_group}' but registered "+ f"an interpreter-layer capability ({capability}). Publish it under '{interpreter_group}' instead — a "+ "kernel-group plugin may only contribute kernel-layer capabilities (inference backends, model listers, "+ "storage and secrets providers, HTTP-error mappers, teardown callbacks, and the content_generator, "+ "task_manager and isolated_execution_probe hub slots)."+ )+ super().__init__(message)+++class RetiredPluginEntryPointGroupError(PluginError):+ """An installed plugin still advertises itself under the retired single entry-point group.++ Nothing reads that group any more, so without this probe the plugin would simply never be+ discovered: no orchestrator, no backend, no error — a process quietly running without the+ capability it was installed for. Fail loud instead, naming the plugins and the group each+ should move to.+ """++ # The message names the caller's own installed distributions and the exact fix; it is fully+ # actionable, so keep it verbatim under STRICT disclosure.+ _authors_caller_facing_message = True++ def __init__(self, *, plugin_names: list[str], retired_group: str, groups: list[str]):+ self.plugin_names = plugin_names+ self.retired_group = retired_group+ self.groups = groups+ named = ", ".join(f"'{name}'" for name in sorted(plugin_names))+ available = " or ".join(f"'{group}'" for group in groups)+ message = (+ f"Plugin(s) {named} advertise themselves under the retired entry-point group '{retired_group}', which is "+ f"no longer read. Upgrade each to a release published under {available}, or uninstall it to recover "+ "startup. If you author it: re-publish under the group matching its layer — a kernel-layer plugin "+ "(inference backend, model lister, storage or secrets provider) goes in the kernel group; anything that "+ "constructs a Pipe-aware object (orchestrator, bundle validator, PipeFunc executor) goes in the "+ "interpreter group."+ )+ super().__init__(message)+++class PluginDeclaredInMultipleGroupsError(PluginError):+ """One installed plugin advertises the same name under more than one entry-point group.++ A boot that reads both groups then finds it twice, loads it twice and runs its ``register``+ twice. Most menu methods collide on the second pass, but the resulting ``Duplicate*Error``+ names the same plugin as both parties to the conflict — which reads as a bug in Pipelex rather+ than as a misdeclared distribution. ``add_teardown`` does not collide at all: it appends, so the+ callback lands twice and runs twice at shutdown with nothing raised. Neither symptom points at+ the cause, hence this error.++ The group is how a plugin declares its layer, so declaring two is not an over-declaration to be+ tolerated — it is the declaration failing to say anything.+ """++ # The message names the caller's own installed distribution and the exact fix.+ _authors_caller_facing_message = True++ def __init__(self, *, plugin_name: str, groups: list[str]):+ self.plugin_name = plugin_name+ self.groups = groups+ named = " and ".join(f"'{group}'" for group in sorted(groups))+ message = (+ f"Plugin '{plugin_name}' is published under {named}. The entry-point group is how a plugin declares "+ "which layer it belongs to, so it must appear in exactly one: keep the kernel group if it only "+ "contributes kernel-layer capabilities (inference backend, model lister, storage or secrets provider, "+ "HTTP-error mapper), and the interpreter group if it constructs any Pipe-aware object (orchestrator, "+ "bundle validator, PipeFunc executor). Remove the other declaration and reinstall."+ )+ super().__init__(message)++class BrokenPluginError(PluginError):"""A discovered plugin failed while loading or registering itself."""diff --git a/pipelex/plugins/plugin_group.py b/pipelex/plugins/plugin_group.pynew file mode 100644index 000000000..17915d05a--- /dev/null+++ b/pipelex/plugins/plugin_group.py@@ -0,0 +1,27 @@+from enum import StrEnum+++class PluginGroup(StrEnum):+ """The entry-point group a plugin publishes under — and therefore the layer it declares.++ ``[project.entry-points."pipelex.plugins.kernel"]`` for a plugin whose adapters are all+ kernel-layer, ``[project.entry-points."pipelex.plugins.interpreter"]`` for one that constructs+ any ``Pipe``-aware object. The group is not documentation: a kernel-only boot asks the+ installed-distribution metadata for the kernel group *alone*, so an interpreter-group plugin's+ module is never even imported there — which is the whole point, since importing it is what drags+ the method interpreter into the process.++ Its own module rather than ``contract.py`` only because the registrar needs it at runtime (it is+ a ``PluginDiscovery`` field) while ``contract.py`` names the registrar back.+ """++ KERNEL = "pipelex.plugins.kernel"+ INTERPRETER = "pipelex.plugins.interpreter"++ @property+ def is_kernel(self) -> bool:+ match self:+ case PluginGroup.KERNEL:+ return True+ case PluginGroup.INTERPRETER:+ return Falsediff --git a/pipelex/plugins/registrar.py b/pipelex/plugins/registrar.pyindex 06e9741d2..f0eec1b30 100644--- a/pipelex/plugins/registrar.py+++ b/pipelex/plugins/registrar.py@@ -16,11 +16,13 @@ from pipelex.plugins.exceptions import (DuplicateSecretsProviderError,DuplicateStorageProviderError,HubSlotAlreadyClaimedError,+ PluginLayerViolationError,)from pipelex.plugins.inference_backend_registry import InferenceFamily, MakeWorkerFnfrom pipelex.plugins.model_lister_registry import ListModelsFnfrom pipelex.plugins.orchestrator_registry import OrchestratorProtocolfrom pipelex.plugins.pipe_func_executor_registry import PipeFuncExecutorFactoryFn+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.plugins.secrets_provider_registry import SecretsProviderFactoryFnfrom pipelex.plugins.storage_provider_registry import StorageProviderFactoryFnfrom pipelex.runtime_bridge.orchestration_mode import OrchestrationMode@@ -71,6 +73,30 @@ class HubSlot(StrEnum):TASK_MANAGER = "task_manager"ISOLATED_EXECUTION_PROBE = "isolated_execution_probe"+ @property+ def is_interpreter_layer(self) -> bool:+ """Whether the claim is applied in ``Pipelex.setup`` rather than in the kernel boot.++ The apply-point is the criterion because it is the one every slot has: a kernel-only boot+ runs the kernel boot and not the interpreter tail, so it can never apply an interpreter+ claim — which is exactly what a kernel-group plugin must not be able to reach.++ For the five slots that hand a value back to core, the returned type corroborates the+ classification — the interpreter ones yield a ``Pipe``-aware object, the kernel ones do not.+ ``TASK_MANAGER`` is why that reading cannot govern on its own: its thunk is invoked for its+ side effects and its return is *discarded*, so there is no handed-back object to classify.+ Its work is kernel-tier all the same — a worker registering only leaf content-generation+ activities names no interpreter type, which is precisely the shape of our Temporal plugin's+ per-backend runner scopes.++ The exhaustive match is the point: a new slot cannot be added without classifying it.+ """+ match self:+ case HubSlot.PIPE_FUNC_EXECUTOR | HubSlot.PIPE_ROUTER | HubSlot.PIPE_RUN:+ return True+ case HubSlot.CONTENT_GENERATOR | HubSlot.TASK_MANAGER | HubSlot.ISOLATED_EXECUTION_PROBE:+ return False+class PluginOrigin(StrEnum):BUILTIN = "builtin"@@ -90,7 +116,7 @@ class PluginStatus(StrEnum):class PluginDiscovery(BaseModel):"""Observability record of one discovered plugin and what it contributed.- Populated by ``build_registrar`` (origin/status/targets_api) and the registrar+ Populated by ``build_registrar`` (origin/status/targets_api/group) and the registrarmenu methods (one ``contributions`` line per contribution). Read by``pipelex plugins list``."""@@ -99,6 +125,9 @@ class PluginDiscovery(BaseModel):origin: PluginOrigin = Field(strict=False)status: PluginStatus = Field(strict=False)targets_api: int | None = None+ #: The entry-point group the plugin arrived under, and so the layer it declares. ``None`` for a+ #: built-in: built-ins are handed in as a list, filed by layer in-tree rather than declared.+ group: PluginGroup | None = Field(default=None, strict=False)contributions: list[str] = Field(default_factory=list)detail: str | None = None@@ -148,8 +177,8 @@ class PluginRegistrar:# Driven by build_registrar (not by plugins)# ------------------------------------------------------------------ #- def begin_plugin(self, *, name: str, origin: PluginOrigin, targets_api: int) -> PluginDiscovery:- discovery = PluginDiscovery(name=name, origin=origin, status=PluginStatus.REGISTERED, targets_api=targets_api)+ def begin_plugin(self, *, name: str, origin: PluginOrigin, targets_api: int, group: PluginGroup | None) -> PluginDiscovery:+ discovery = PluginDiscovery(name=name, origin=origin, status=PluginStatus.REGISTERED, targets_api=targets_api, group=group)self.discoveries.append(discovery)self._active = discoveryreturn discovery@@ -183,6 +212,7 @@ class PluginRegistrar:)def add_orchestrator(self, *, mode: OrchestrationMode, orchestrator: OrchestratorProtocol) -> None:+ self._require_interpreter_layer(capability=f"orchestrator {mode}")self._add(store=self.orchestrators,sources=self._orchestrator_sources,@@ -195,6 +225,7 @@ class PluginRegistrar:)def add_bundle_validator(self, *, mode: OrchestrationMode, validator: BundleValidatorProtocol) -> None:+ self._require_interpreter_layer(capability=f"bundle validator {mode}")self._add(store=self.bundle_validators,sources=self._bundle_validator_sources,@@ -259,6 +290,7 @@ class PluginRegistrar:``register`` stays import-light. This is the PipeFunc-execution axis, orthogonal to theorchestration axis. Fail-loud on a duplicate mode, naming both plugins."""+ self._require_interpreter_layer(capability=f"pipe_func executor {mode}")self._add(store=self.pipe_func_executors,sources=self._pipe_func_executor_sources,@@ -379,7 +411,28 @@ class PluginRegistrar:sources[key] = self._active.nameself._active.contributions.append(contribution)+ def _require_interpreter_layer(self, *, capability: str) -> None:+ """Reject an interpreter-layer contribution from a plugin that published itself as kernel-layer.++ One-directional by design: an interpreter-group plugin may contribute kernel-tier+ capabilities alongside its interpreter-tier ones — ours registers an orchestrator+ (interpreter-tier, guarded here) *and* an HTTP-error mapper (kernel-tier, not) — and nothing+ is at risk there because a kernel-only boot never reads that group. Built-ins declare no+ group and are skipped: they are filed by layer in-tree, where the hub-layering guard polices+ them statically.+ """+ group = self._active.group+ if group is not None and group.is_kernel:+ raise PluginLayerViolationError(+ plugin_name=self._active.name,+ capability=capability,+ declared_group=group,+ interpreter_group=PluginGroup.INTERPRETER,+ )+def _claim(self, *, slot: HubSlot, factory: Callable[[], Any]) -> None:+ if slot.is_interpreter_layer:+ self._require_interpreter_layer(capability=f"hub slot {slot}")if slot in self.slot_claims:raise HubSlotAlreadyClaimedError(slot=slot, first_plugin=self._slot_sources[slot], second_plugin=self._active.name)self.slot_claims[slot] = factorydiff --git a/pipelex/providers/builtins.py b/pipelex/providers/builtins.pyindex 126e0abb7..74c011b4b 100644--- a/pipelex/providers/builtins.py+++ b/pipelex/providers/builtins.py@@ -1,4 +1,5 @@from pipelex.plugins.contract import PipelexPlugin+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.providers.anthropic.anthropic_plugin import AnthropicPluginfrom pipelex.providers.azure_rest.azure_rest_plugin import AzureRestPluginfrom pipelex.providers.bedrock.bedrock_plugin import BedrockPlugin@@ -17,8 +18,8 @@ from pipelex.providers.pypdfium2.pypdfium2_plugin import Pypdfium2Pluginfrom pipelex.providers.secrets.secrets_plugin import SecretsPluginfrom pipelex.providers.storage.storage_plugin import StoragePlugin-# The **runtime-layer** half of the plugins Pipelex ships with: inference backends, extraction and-# search drivers, storage and secrets. Every one of them adapts a runtime-layer port, so this module+# The **kernel-layer** half of the plugins Pipelex ships with: inference backends, extraction and+# search drivers, storage and secrets. Every one of them adapts a kernel-layer port, so this module# — like the rest of ``pipelex.providers`` — stays importable without loading the method interpreter.# The interpreter-touching built-ins live in ``pipelex.interpreter_plugins.builtins``, which composes# both halves into the single ``BUILTIN_PLUGINS`` list the boot entrypoint hands to discovery. See@@ -31,7 +32,7 @@ from pipelex.providers.storage.storage_plugin import StoragePlugin## Each is import-light: importing this module imports no backend SDK (the SDKs load lazily inside the# make_worker closures).-RUNTIME_BUILTIN_PLUGINS: list[PipelexPlugin] = [+KERNEL_BUILTIN_PLUGINS: list[PipelexPlugin] = [StoragePlugin(),SecretsPlugin(),OpenAIPlugin(),@@ -51,11 +52,17 @@ RUNTIME_BUILTIN_PLUGINS: list[PipelexPlugin] = [LinkupPlugin(),]-# Runtime-layer built-ins that core requires unconditionally — naming one in ``plugins.disabled`` is a+# Kernel-layer built-ins that core requires unconditionally — naming one in ``plugins.disabled`` is a# configuration error, not a no-op. ``storage`` supplies every built-in storage backend# (``storage_config.method`` must resolve to a registered factory or boot fails loud); ``secrets``# supplies the built-in ``env`` secrets backend (``secrets_config.method`` must likewise resolve or boot# fails loud); ``openai`` is the always-on default inference driver (no optional SDK to avoid), so# disabling it would only break the out-of-the-box experience. The interpreter-layer half of this set# lives beside its plugins, in ``pipelex.interpreter_plugins.builtins``.-RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES: frozenset[str] = frozenset({"storage", "secrets", "openai"})+KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES: frozenset[str] = frozenset({"storage", "secrets", "openai"})++# The entry-point groups a kernel-only boot reads: its own, and only its own. Sits beside the+# built-in manifest because it answers the same question for the other half of discovery — what an+# installation contributes to *this* layer. The interpreter's composed list lives next to its own+# built-ins, in ``pipelex.interpreter_plugins.builtins``.+KERNEL_ENTRY_POINT_GROUPS: tuple[PluginGroup, ...] = (PluginGroup.KERNEL,)diff --git a/pipelex/providers/secrets/secrets_plugin.py b/pipelex/providers/secrets/secrets_plugin.pyindex d6d8f4177..bb41e8096 100644--- a/pipelex/providers/secrets/secrets_plugin.py+++ b/pipelex/providers/secrets/secrets_plugin.py@@ -13,7 +13,7 @@ class SecretsPlugin:"""Always-on built-in provider of the ``env`` secrets backend (reads secrets from env vars).Core-unconditional: secrets is required infra, so this plugin cannot be disabled into a boot- with no secrets provider (see ``RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES``). It registers the one built-in+ with no secrets provider (see ``KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES``). It registers the one built-in``env`` method; ``secrets_config.method`` selects which factory boot invokes. Importing this moduleis import-light — no SDK loads at register (the env provider needs none, and an external``pipelex-secrets-<backend>`` plugin defers its SDK import to its own factory).diff --git a/pipelex/providers/storage/storage_plugin.py b/pipelex/providers/storage/storage_plugin.pyindex 8745ccf67..1fe698c8d 100644--- a/pipelex/providers/storage/storage_plugin.py+++ b/pipelex/providers/storage/storage_plugin.py@@ -64,7 +64,7 @@ class StoragePlugin:"""Always-on built-in provider of the local / in_memory / s3 / gcp storage backends.Core-unconditional: storage is required infra, so this plugin cannot be disabled into a- boot with no storage (see ``RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES``). It registers one factory per+ boot with no storage (see ``KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES``). It registers one factory perbuilt-in method; ``storage_config.method`` selects which one boot invokes. Importing thismodule is import-light — the s3/gcp SDKs load lazily inside their providers, not at register."""diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex e6f3daca9..68bdeeca5 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -1,4 +1,4 @@-"""The runtime layer's composition root: stand up inference without the method interpreter.+"""The kernel layer's composition root: stand up inference without the method interpreter.Pipelex has two layers and one hub each (``docs/contribute/hub-layering.md``). Every package in thetree is placed on one side of that line and pinned there, but the *composition root* was the one@@ -7,7 +7,7 @@ sequence, so the only way into the process constructed an ``InterpreterHub``, a``PipelineManager``, a ``PipeRouter`` and a ``PipeRun`` whether the caller would ever load a method ornot. The layering property was real for *importing* and vacuous for *booting*.-This module is the runtime half. It stands up config, logging, secrets, telemetry, the class and func+This module is the kernel half. It stands up config, logging, secrets, telemetry, the class and funcregistries, the template sets, the model deck, storage, the content generator, the inference manager,the reporting delegate and the observers — everything present at execution time whatever is loaded —and it loads **zero interpreter modules** doing it. ``pipelex.pipelex.Pipelex`` is the interpreter half:@@ -15,7 +15,7 @@ it subclasses this class, imports it downward (which the interpreter layer may dmethod machinery.The split is the same move the built-in plugin manifests made, and it is what finally gives-``RUNTIME_BUILTIN_PLUGINS`` a caller: a runtime-only boot discovers exactly that half, so the+``KERNEL_BUILTIN_PLUGINS`` a caller: a kernel-only boot discovers exactly that half, so the``direct`` orchestrator, the direct bundle validator and the built-in PipeFunc executor modes — allinterpreter-contributed — are simply absent. Nothing here resolves out of those registries at boot;they are looked up at run time, by the interpreter.@@ -23,13 +23,15 @@ they are looked up at run time, by the interpreter.**Every import in this module stays at module top level.** That is not incidental: a function-localimport is precisely what hides a breach from the static guard and the import-closure test at the sametime, so if one ever seems necessary here the placement is wrong and the type should move instead.-The module is declared in the hub-layering guard's ``RUNTIME_LAYER_PACKAGES`` and listed in the-closure test's ``RUNTIME_LAYER_ENTRY_POINTS``; a booted-runtime test pins the same property through+The module is declared in the hub-layering guard's ``KERNEL_LAYER_PACKAGES`` and listed in the+closure test's ``KERNEL_LAYER_ENTRY_POINTS``; a booted-kernel test pins the same property through``make()`` rather than through an import.-Three ``runtime_*`` names now live at the top of the package and they are different things:-``runtime_hub`` is the runtime layer's service container, ``runtime_bridge`` is a transport, and-``runtime_boot`` — this module — is the runtime layer's composition root.+Three ``runtime_*`` names still live at the top of the package and they are different things:+``runtime_hub`` is the kernel layer's service container, ``runtime_bridge`` is a transport, and+``runtime_boot`` — this module — is the kernel layer's composition root. Two of the three are named+after the layer under its former name; only ``runtime_bridge`` means "runtime" in the+orchestration-venue sense and keeps the word for good."""import types@@ -84,7 +86,7 @@ from pipelex.plugins.registrar import HubSlot, PluginRegistrarfrom pipelex.plugins.sdk_client_manager import SdkClientManagerfrom pipelex.plugins.secrets_provider_registry import SecretsProviderRegistryfrom pipelex.plugins.storage_provider_registry import StorageProviderRegistry-from pipelex.providers.builtins import RUNTIME_BUILTIN_PLUGINS, RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES+from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS, KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES, KERNEL_ENTRY_POINT_GROUPSfrom pipelex.reporting.reporting_manager import ReportingManagerfrom pipelex.reporting.reporting_protocol import ReportingProtocolfrom pipelex.runtime_hub import RuntimeHub, set_runtime_hub@@ -125,6 +127,7 @@ if TYPE_CHECKING:from collections.abc import Sequencefrom pipelex.plugins.contract import PipelexPlugin+ from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.system.pipelex_service.remote_config import RemoteConfigfrom pipelex.system.pipelex_service.types import RemoteConfigSource@@ -134,7 +137,7 @@ _HubSlotImplT = TypeVar("_HubSlotImplT")class RuntimeBoot(metaclass=MetaSingleton):- """Boot the runtime layer: inference, storage, models, telemetry — no method interpreter.+ """Boot the kernel layer: inference, storage, models, telemetry — no method interpreter.Subclassed by ``pipelex.pipelex.Pipelex``, which appends the interpreter constructions. Thesingleton is therefore shared between the two: the class-level accessors below resolve **by@@ -248,6 +251,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.needs_model_specs: bool | None = None,builtin_plugins: "Sequence[PipelexPlugin] | None" = None,core_unconditional_plugin_names: frozenset[str] | None = None,+ entry_point_groups: "Sequence[PluginGroup] | None" = None,class_registry: ClassRegistryAbstract | None = None,secrets_provider: SecretsProviderAbstract | None = None,storage_provider: StorageProviderAbstract | None = None,@@ -260,15 +264,17 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.observers: dict[str, ObserverProtocol] | None = None,**kwargs: Any,) -> None:- """Stand up the runtime layer.+ """Stand up the kernel layer.- ``builtin_plugins`` defaults to ``RUNTIME_BUILTIN_PLUGINS`` — the runtime-layer half — so a bare- runtime boot never loads the interpreter-touching built-ins; the interpreter boot passes the- composed list instead. ``core_unconditional_plugin_names`` defaults to the runtime-layer half for+ ``builtin_plugins`` defaults to ``KERNEL_BUILTIN_PLUGINS`` — the kernel-layer half — so a bare+ kernel boot never loads the interpreter-touching built-ins; the interpreter boot passes the+ composed list instead. ``core_unconditional_plugin_names`` defaults to the kernel-layer half forthe same reason, and must describe the same set as ``builtin_plugins``: requiring a name that was- never discovered fails boot.+ never discovered fails boot. ``entry_point_groups`` is the same story for *installed* plugins and+ defaults to ``KERNEL_ENTRY_POINT_GROUPS``: a bare kernel boot never even queries the interpreter+ group, so no interpreter-side plugin module is imported into the process.- Every other argument is the runtime subset of the same injections ``Pipelex.make`` documents.+ Every other argument is the kernel subset of the same injections ``Pipelex.make`` documents."""if kwargs:msg = f"The base setup method does not support any additional arguments: {kwargs}"@@ -360,10 +366,11 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# applied at their ordered apply-points in later phases.plugin_registrar = build_registrar(config=get_config(),- builtin_plugins=RUNTIME_BUILTIN_PLUGINS if builtin_plugins is None else builtin_plugins,+ builtin_plugins=KERNEL_BUILTIN_PLUGINS if builtin_plugins is None else builtin_plugins,core_unconditional_plugin_names=(- RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES if core_unconditional_plugin_names is None else core_unconditional_plugin_names+ KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES if core_unconditional_plugin_names is None else core_unconditional_plugin_names),+ entry_point_groups=KERNEL_ENTRY_POINT_GROUPS if entry_point_groups is None else entry_point_groups,)self._plugin_registrar = plugin_registrar# Reject an unknown boot orchestrator before falling through to the core defaults. The requested@@ -373,18 +380,16 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# hub slots, so without this guard the run would silently execute in-process instead of under the# requested runtime. Checked here to fail fast, before the telemetry/model work.#- # On a runtime-only boot this rejects an orchestrator contributed by an interpreter-layer- # *built-in*, because ``builtin_plugins`` defaults to the runtime half and the name is therefore- # never registered. It does NOT reject an *external* entry-point plugin that is interpreter-side:- # ``build_registrar`` discovers external plugins unconditionally, so such a name satisfies this- # check, and a bare runtime boot would then apply the runtime slot claims while silently never- # applying the interpreter ones (``PIPE_ROUTER`` / ``PIPE_RUN`` / ``PIPE_FUNC_EXECUTOR``, all- # applied in ``Pipelex.setup``). Deliberately not guarded here, because every remedy needs a layer- # signal this layer does not have. Analysed in- # ``wip/boot-split/runtime-boot-external-interpreter-orchestrator.md``, which the first runtime-only- # caller (the Pipelex kernel's boot-contract test) has now settled: that caller names no- # ``boot_orchestrator``, so this gate is never reached and the hole is not on its path. Reassess- # when a runtime-only boot is offered to real callers — that is when naming one becomes reachable.+ # On a kernel-only boot this rejects an interpreter-side orchestrator from either source, and for+ # the same reason in both cases: the name was never registered, so it cannot satisfy the check.+ # A built-in one is absent because ``builtin_plugins`` defaults to the kernel half; an *external*+ # one is absent because ``entry_point_groups`` defaults to ``KERNEL_ENTRY_POINT_GROUPS``, so its+ # group is never even queried. The result is a loud ``UnknownBootOrchestratorError`` rather than+ # the half-application this comment used to defer — a boot that applied the kernel slot claims+ # 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``.requested_boot_orchestrator = get_config().plugins.boot_orchestratorif requested_boot_orchestrator is not None and requested_boot_orchestrator not in plugin_registrar.registered_plugin_names:raise UnknownBootOrchestratorError(requested=requested_boot_orchestrator)@@ -510,7 +515,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# these at run time.## The orchestrator and bundle-validator registries are interpreter-contributed and therefore- # empty on a runtime-only boot. That is fine and deliberate: nothing here resolves out of them,+ # empty on a kernel-only boot. That is fine and deliberate: nothing here resolves out of them,# they are looked up at run time by the interpreter.self.runtime_hub.set_inference_backend_registry(InferenceBackendRegistry(plugin_registrar.inference_backends))self.runtime_hub.set_model_lister_registry(ModelListerRegistry(plugin_registrar.model_listers))@@ -562,7 +567,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.self.class_registry.register_classes(TestRegistryModels.get_all_models())# --- Observers -------------------------------------------------------------------------- # Built from runtime-layer parts and held on the instance because the interpreter half's+ # Built from kernel-layer parts and held on the instance because the interpreter half's# PipeRouter consumes it — one of the two seams that lets the interpreter constructions be a# tail rather than an interleaving.@@ -682,7 +687,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.finally:# The runtime hub releases its process-global config. ``class_registry_scoping`` is reset here# too: the interpreter half installs the resolver at boot, so releasing it belongs to whichever- # teardown runs — and on a runtime-only boot nothing installed it, where the reset is a no-op.+ # teardown runs — and on a kernel-only boot nothing installed it, where the reset is a no-op.self.runtime_hub.reset_config()class_registry_scoping.reset()# The same three ``_release_after_failed_boot`` releases, deliberately kept identical: these are@@ -835,7 +840,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.config_dir: Path | None = None,config_overrides: dict[str, Any] | None = None,) -> Self:- """Create and initialize a runtime-layer singleton: inference, storage, models, telemetry.+ """Create and initialize a kernel-layer singleton: inference, storage, models, telemetry.Loads no method interpreter. Use ``pipelex.pipelex.Pipelex.make`` to boot the full stack.See that method for the shared arguments — including ``config_dir``, which scopes the *maindiff --git a/pipelex/runtime_hub.py b/pipelex/runtime_hub.pyindex b5eab6810..7f538d2ac 100644--- a/pipelex/runtime_hub.py+++ b/pipelex/runtime_hub.py@@ -1,21 +1,21 @@-"""The runtime layer's dependency hub: process-scoped infrastructure services.+"""The kernel layer's dependency hub: process-scoped infrastructure services.``RuntimeHub`` brokers everything that is configured once at boot and never varies per method:config, console, secrets, storage, telemetry, the model deck and inference workers, the contentgenerator, the reporting delegate, and the plugin registries. That is the machinery present at-execution time whatever is loaded — hence *runtime*, in the language-implementation sense.+execution time whatever is loaded — the **kernel layer**, in the language-implementation sense.**The one rule:** ``interpreter_hub`` imports ``runtime_hub``; ``runtime_hub`` must never import``interpreter_hub``. Nothing here may name ``libraries``, ``pipe_operators``, ``pipe_controllers``,``codegen``, ``builder``, ``interpreter_plugins``, ``pipe_machinery``, ``pipe_signature``,``mthds_parsing``, ``pipeline`` or ``pipe_run`` at module level. That list is the interpreter'stop-level packages — all of them, with no qualification — so the property it buys is stated-outright: **importing the Pipelex runtime loads zero interpreter modules.** It used to have to trail+outright: **importing the Pipelex kernel layer loads zero interpreter modules.** It used to have to trail"…or the Pipe-touching modules of ``core.pipes``", because some of what it forbids lived under a-runtime-named package, and it had to leave out ``pipeline`` and ``pipe_run``, because four leaf+package declared kernel-layer, and it had to leave out ``pipeline`` and ``pipe_run``, because four leafmodels of theirs landed in this module's closure. Both qualifications are gone the same way — themisfiled code moved. ``pipelex.core`` is *not* on the list at all: the whole package is declared-runtime-layer, and this module's own closure runs straight through it. See+kernel-layer, and this module's own closure runs straight through it. See``docs/contribute/hub-layering.md``."""diff --git a/pipelex/system/registries/class_registry_access.py b/pipelex/system/registries/class_registry_access.pyindex 55af305bc..79b57605b 100644--- a/pipelex/system/registries/class_registry_access.py+++ b/pipelex/system/registries/class_registry_access.py@@ -7,7 +7,7 @@ plain top-level import instead of a lazy ``importlib`` shim.Exactly one module needs that today, and the constraint is a **static-analysis** cycle rather than aruntime one — measure before restating it. ``pipe_machinery.pipe_abstract`` decorates graph-registry-entries with a concept's JSON Schema. It is *not* in ``runtime_hub``'s runtime import closure (a+entries with a concept's JSON Schema. It is *not* in ``runtime_hub``'s kernel import closure (aclean-interpreter probe after ``import pipelex.runtime_hub`` shows it, ``pipe_run.pipe_job`` and``plugins.orchestrator_registry`` all absent — those edges are ``TYPE_CHECKING``-only). But pyright's``reportImportCycles`` counts ``TYPE_CHECKING`` edges, so importing **either** hub there is a hard@@ -47,7 +47,7 @@ everywhere except inside this module's own import closure.Scoping: a run may pin a per-library ClassRegistry (a workflow's own registry) rather than theprocess-global Kajson one. Resolving *which* library is current is interpreter-layer knowledge, so-the runtime layer holds only a slot — ``pipelex.interpreter_hub.set_interpreter_hub`` installs the real+the kernel layer holds only a slot — ``pipelex.interpreter_hub.set_interpreter_hub`` installs the realresolver at boot. Unresolved, or with no library pinned, callers get the process-global registry."""diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 340fb3f45..b6e5ad23a 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -230,7 +230,9 @@ PipelineInputContentError | Pipeline input content | https://docs.pipelex.com/laPipelineManagerAlreadyExistsError | Pipeline manager already exists | https://docs.pipelex.com/latest/errors/pipeline-manager-already-exists-error/PipelineManagerNotFoundError | Pipeline manager not found | https://docs.pipelex.com/latest/errors/pipeline-manager-not-found-error/PluginApiVersionMismatchError | Plugin api version mismatch | https://docs.pipelex.com/latest/errors/plugin-api-version-mismatch-error/+PluginDeclaredInMultipleGroupsError | Plugin declared in multiple groups | https://docs.pipelex.com/latest/errors/plugin-declared-in-multiple-groups-error/PluginError | Plugin error | https://docs.pipelex.com/latest/errors/plugin-error/+PluginLayerViolationError | Plugin layer violation | https://docs.pipelex.com/latest/errors/plugin-layer-violation-error/PortkeyCredentialsError | Portkey credentials | https://docs.pipelex.com/latest/errors/portkey-credentials-error/PortkeyError | Portkey | https://docs.pipelex.com/latest/errors/portkey-error/PortkeyFactoryError | Portkey factory | https://docs.pipelex.com/latest/errors/portkey-factory-error/@@ -243,6 +245,7 @@ RemoteConfigFetchError | Remote config fetch | https://docs.pipelex.com/latest/eRemoteConfigUnavailableError | Remote config unavailable | https://docs.pipelex.com/latest/errors/remote-config-unavailable-error/RemoteConfigValidationError | Remote config validation | https://docs.pipelex.com/latest/errors/remote-config-validation-error/ReportingManagerError | Reporting manager | https://docs.pipelex.com/latest/errors/reporting-manager-error/+RetiredPluginEntryPointGroupError | Retired plugin entry point group | https://docs.pipelex.com/latest/errors/retired-plugin-entry-point-group-error/RoutingProfileBlueprintValueError | Routing profile blueprint value | https://docs.pipelex.com/latest/errors/routing-profile-blueprint-value-error/RoutingProfileDisabledBackendError | Routing profile disabled backend | https://docs.pipelex.com/latest/errors/routing-profile-disabled-backend-error/RoutingProfileLibraryError | Routing profile library | https://docs.pipelex.com/latest/errors/routing-profile-library-error/diff --git a/tests/integration/pipelex/plugins/test_secrets_external_plugin.py b/tests/integration/pipelex/plugins/test_secrets_external_plugin.pyindex 51880c58b..bd24ca4a0 100644--- a/tests/integration/pipelex/plugins/test_secrets_external_plugin.py+++ b/tests/integration/pipelex/plugins/test_secrets_external_plugin.py@@ -3,7 +3,7 @@ and the storage↔secrets ordering guard.The built-in ``env`` method is the default and is selected onto the hub by an ordinary boot; anexplicit ``setup(secrets_provider=...)`` still wins ahead of registry selection; a fake external-method token discovered through a ``pipelex.plugins`` entry point is selectable via+method token discovered through a ``pipelex.plugins.kernel`` entry point is selectable via``secrets_config.method``. The final test is the ordering guard: with a non-env secrets method AND``gcp`` storage, storage's gcp factory reads the config-selected secrets provider from the hub —proving secrets is resolved and set on the hub before storage selection runs.@@ -12,13 +12,15 @@ proving secrets is resolved and set on the hub before storage selection runs.from __future__ import annotationsfrom types import SimpleNamespace-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, castimport pytestfrom typing_extensions import overridefrom pipelex.pipelex import Pipelexfrom pipelex.plugins.contract import PLUGIN_API_VERSION+from pipelex.plugins.discovery import GroupedEntryPoint+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.runtime_hub import get_secrets_provider, get_secrets_provider_registry, get_storage_providerfrom pipelex.system.runtime import IntegrationMode, runtime_managerfrom pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider@@ -27,6 +29,7 @@ from pipelex.tools.storage.gcp_storage_provider import GcpStorageProviderif TYPE_CHECKING:from collections.abc import Generator+ from importlib.metadata import EntryPointfrom pytest_mock import MockerFixture@@ -97,7 +100,9 @@ def _test_integration_mode() -> IntegrationMode:def _patch_external_secrets_plugin(mocker: MockerFixture) -> None:# The entry point resolves to the plugin class (a zero-arg factory); discovery instantiates it.fake_entry_point = SimpleNamespace(name=EXTERNAL_PLUGIN_NAME, load=lambda: _FakeSecretsPlugin)- mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[fake_entry_point])+ # A secrets provider is a kernel-layer capability, so its dist publishes under the kernel group.+ grouped = GroupedEntryPoint(group=PluginGroup.KERNEL, entry_point=cast("EntryPoint", fake_entry_point))+ mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[grouped])class TestSecretsExternalPlugin:diff --git a/tests/integration/pipelex/plugins/test_storage_external_plugin.py b/tests/integration/pipelex/plugins/test_storage_external_plugin.pyindex d942532ef..ac5d2e7dc 100644--- a/tests/integration/pipelex/plugins/test_storage_external_plugin.py+++ b/tests/integration/pipelex/plugins/test_storage_external_plugin.py@@ -1,4 +1,4 @@-"""End-to-end: an out-of-tree storage plugin discovered through a ``pipelex.plugins`` entry point is+"""End-to-end: an out-of-tree storage plugin discovered through a ``pipelex.plugins.kernel`` entry point isselectable via ``storage_config.method`` and lands on the hub.This exercises the whole discovery → selection → hub chain the built-in providers ride, with a fake@@ -9,19 +9,22 @@ config selects that token, and the resolved provider is the one set on the hub.from __future__ import annotationsfrom types import SimpleNamespace-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, castimport pytestfrom typing_extensions import overridefrom pipelex.pipelex import Pipelexfrom pipelex.plugins.contract import PLUGIN_API_VERSION+from pipelex.plugins.discovery import GroupedEntryPoint+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.runtime_hub import get_storage_provider, get_storage_provider_registryfrom pipelex.system.runtime import IntegrationMode, runtime_managerfrom pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredDataif TYPE_CHECKING:from collections.abc import Generator+ from importlib.metadata import EntryPointfrom pytest_mock import MockerFixture@@ -86,7 +89,9 @@ class TestStorageExternalPlugin:"""A fake entry point + a config naming its token boots with that external provider on the hub."""# The entry point resolves to the plugin class (a zero-arg factory); discovery instantiates it.fake_entry_point = SimpleNamespace(name=EXTERNAL_PLUGIN_NAME, load=lambda: _FakeStoragePlugin)- mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[fake_entry_point])+ # A storage provider is a kernel-layer capability, so its dist publishes under the kernel group.+ grouped = GroupedEntryPoint(group=PluginGroup.KERNEL, entry_point=cast("EntryPoint", fake_entry_point))+ mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[grouped])Pipelex.make(integration_mode=_test_integration_mode(),diff --git a/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py b/tests/integration/pipelex/system/test_hub_slot_injection_precedence.pyindex c5ce1a8e6..efa075d12 100644--- a/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py+++ b/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py@@ -50,7 +50,7 @@ def _fake_registrar(mocker: MockerFixture) -> PluginRegistrar:than provider/executor selection."""registrar = PluginRegistrar(config=cast("PipelexConfig", SimpleNamespace(temporal=SimpleNamespace(is_enabled=False))))- registrar.begin_plugin(name="pipe_func", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="pipe_func", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION, group=None)PipeFuncPlugin().register(registrar)mocker.patch("pipelex.runtime_boot.build_registrar", return_value=registrar)return registrardiff --git a/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py b/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.pyindex 5758a6de9..09208af31 100644--- a/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py+++ b/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py@@ -21,7 +21,7 @@ from rich.console import Consolefrom pipelex.cli.dev_cli.commands import check_hub_layering_cmd as cmd_modfrom pipelex.cli.dev_cli.commands.check_hub_layering_cmd import check_hub_layering_cmdfrom pipelex.cli.dev_cli.commands.hub_layering_guard import (- RUNTIME_LAYER_PACKAGES,+ KERNEL_LAYER_PACKAGES,HubLayeringViolation,HubLayeringViolationKind,)@@ -69,15 +69,15 @@ class TestCheckHubLayeringCmd:check_hub_layering_cmd(quiet=True) # returns normally (exit 0)output = console_buffer.getvalue()assert "Hub-layering check: PASSED" in output- assert "Runtime layer:" not in output+ assert "Kernel layer:" not in output- def test_verbose_success_names_every_declared_runtime_package(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ def test_verbose_success_names_every_declared_kernel_package(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:"""The success panel is where a reader learns what the declaration covers, so it must be complete."""_patch_scans(mocker)check_hub_layering_cmd(quiet=False)output = console_buffer.getvalue()assert "Hub-layering Check: PASSED" in output- for package in RUNTIME_LAYER_PACKAGES:+ for package in KERNEL_LAYER_PACKAGES:assert package in output, packagedef test_violations_exit_1_and_locate_every_site(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.pyindex 4910cf8f7..0d42d1c36 100644--- a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py@@ -6,13 +6,13 @@ import textwrapfrom pathlib import Pathfrom pipelex.cli.dev_cli.commands.hub_layering_guard import (- RUNTIME_LAYER_PACKAGES,+ KERNEL_LAYER_PACKAGES,HubLayeringViolation,HubLayeringViolationKind,find_violations_in_source,- is_runtime_layer,+ is_kernel_layer,)-from tests.unit.pipelex.test_runtime_layer_import_closure import INTERPRETER_PACKAGES+from tests.unit.pipelex.test_kernel_layer_import_closure import INTERPRETER_PACKAGES#: Anchored on `tests/` by name rather than by a parent count. A depth index is not merely fragile#: here, it is *silent*: `parents[6]` is the workspace root, which holds a sibling `pipelex/` checkout,@@ -20,7 +20,7 @@ from tests.unit.pipelex.test_runtime_layer_import_closure import INTERPRETER_PAC#: pass. That is the failure this track already hit once, in the golden-renderer test._REPO_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests").parent-#: A runtime-layer module path, and a interpreter-layer one, for the same snippet.+#: A kernel-layer module path, and a interpreter-layer one, for the same snippet.RUNTIME_PATH = "pipelex/cogt/sample/worker.py"INTERPRETER_PATH = "pipelex/pipeline/sample/runner.py"TEST_PATH = "tests/helpers/sample_helpers.py"@@ -40,62 +40,62 @@ def _kinds(violations: list[HubLayeringViolation]) -> set[HubLayeringViolationKiclass TestHubLayeringGuard:- def test_runtime_layer_membership(self) -> None:- """The declared runtime layer is matched on package boundaries, and `pipeline` is outside it."""- assert is_runtime_layer(module_qname="pipelex.cogt.llm.llm_worker_abstract")- assert is_runtime_layer(module_qname="pipelex.tools")- assert not is_runtime_layer(module_qname="pipelex.pipeline.runner")- # A package whose name merely starts with a runtime-layer name is not in the runtime layer.- assert not is_runtime_layer(module_qname="pipelex.toolsmith.thing")+ def test_kernel_layer_membership(self) -> None:+ """The declared kernel layer is matched on package boundaries, and `pipeline` is outside it."""+ assert is_kernel_layer(module_qname="pipelex.cogt.llm.llm_worker_abstract")+ assert is_kernel_layer(module_qname="pipelex.tools")+ assert not is_kernel_layer(module_qname="pipelex.pipeline.runner")+ # A package whose name merely starts with a kernel-layer name is not in the kernel layer.+ assert not is_kernel_layer(module_qname="pipelex.toolsmith.thing")def test_core_is_declared_as_one_whole_package(self) -> None:"""`core/` is declared wholesale — one entry, no sub-entries — because nothing interpreter-layeris left inside it.Stated as a property of the declaration rather than as a list of member modules. Once- `pipelex.core` is a single prefix entry, `is_runtime_layer` answers True for *any* string+ `pipelex.core` is a single prefix entry, `is_kernel_layer` answers True for *any* stringunder it, so asserting ten real module names would carry the same one bit as asserting teninvented ones — an inventory, not an invariant. What is worth pinning is the shape that tookthe whole M1 track to reach: re-introducing a `pipelex.core.<sub>` entry would mean core hassplit again, and that is what fails here."""- assert "pipelex.core" in RUNTIME_LAYER_PACKAGES- resplit = [package for package in RUNTIME_LAYER_PACKAGES if package.startswith("pipelex.core.")]+ assert "pipelex.core" in KERNEL_LAYER_PACKAGES+ resplit = [package for package in KERNEL_LAYER_PACKAGES if package.startswith("pipelex.core.")]assert not resplit, (f"`pipelex.core` is declared wholesale, but these sub-package entries are declared too: {resplit}. ""A sub-entry means some of `core/` is being carved out again — either move the interpreter-layer ""module to `pipe_machinery`/`mthds_parsing` as M1 did, or record why the split is back.")- def test_no_interpreter_package_is_declared_runtime_layer(self) -> None:+ def test_no_interpreter_package_is_declared_kernel_layer(self) -> None:"""The two layer declarations are disjoint — derived from both, so neither can drift alone.- `RUNTIME_LAYER_PACKAGES` (this guard) and `INTERPRETER_PACKAGES` (the import-closure test) are+ `KERNEL_LAYER_PACKAGES` (this guard) and `INTERPRETER_PACKAGES` (the import-closure test) arethe two halves of one partition, maintained in separate modules and never previously compared.Declaring a package in both would make the guard vouch for a package the closure test flags —each check would keep passing while contradicting the other."""for package in INTERPRETER_PACKAGES:qname = f"pipelex.{package}"- assert not is_runtime_layer(module_qname=qname), (+ assert not is_kernel_layer(module_qname=qname), (f"{qname} is named by the import-closure test's INTERPRETER_PACKAGES *and* matched by "- "this guard's RUNTIME_LAYER_PACKAGES. The two declarations describe opposite layers."+ "this guard's KERNEL_LAYER_PACKAGES. The two declarations describe opposite layers.")- assert not is_runtime_layer(module_qname=f"{qname}.some_module")+ assert not is_kernel_layer(module_qname=f"{qname}.some_module")- def test_declared_runtime_layer_names_only_real_packages(self) -> None:- """Every declared entry resolves on disk — `is_runtime_layer` is a string predicate that cannot tell.+ def test_declared_kernel_layer_names_only_real_packages(self) -> None:+ """Every declared entry resolves on disk — `is_kernel_layer` is a string predicate that cannot tell.A renamed or deleted package leaves its entry matching nothing, which makes the declarationquietly *narrower* than it reads: the transitive rule filters its domain through this predicate,so an entry that matches nothing removes modules from the check rather than adding them."""source_root = _REPO_ROOT / "pipelex"- for package in RUNTIME_LAYER_PACKAGES:+ for package in KERNEL_LAYER_PACKAGES:relative = package.removeprefix("pipelex.").replace(".", "/")target = source_root / relativeassert target.is_dir() or target.with_suffix(".py").is_file(), (- f"RUNTIME_LAYER_PACKAGES names {package!r}, which resolves to neither a package directory "+ f"KERNEL_LAYER_PACKAGES names {package!r}, which resolves to neither a package directory "f"nor a module file under {source_root}. A declared entry that matches nothing silently "f"shrinks the layer rule's domain instead of failing.")@@ -104,23 +104,23 @@ class TestHubLayeringGuard:"""Splitting one declared package into two must leave two declarations, not one.`plugins/` was carved in half: the mechanism stayed, the built-in adapters became `providers/`.- Both halves are runtime-layer, so the split moved no boundary — but it introduced one silent+ Both halves are kernel-layer, so the split moved no boundary — but it introduced one silentfailure mode, and it runs the opposite way to intuition. Omitting an entry does not make theguard complain; it makes the guard go *quiet*. The transitive rule iterates only modules- `is_runtime_layer` already accepts, so an undeclared package leaves the rule's domain rather- than being reported by it, and the largest runtime-layer package would stop being checked+ `is_kernel_layer` already accepts, so an undeclared package leaves the rule's domain rather+ than being reported by it, and the largest kernel-layer package would stop being checkedwhile every gate stayed green. Nothing else in the suite catches that.- Membership is the whole assertion, deliberately. `is_runtime_layer` matches by dotted prefix,+ Membership is the whole assertion, deliberately. `is_kernel_layer` matches by dotted prefix,so once an entry is present it answers True for *any* string beneath it — enumerating theadapters on disk would carry the same one bit as enumerating invented names, and would add asecond failure mode (an adapter without an `__init__.py` is importable as a namespace packagebut would be silently skipped). See `test_core_is_declared_as_one_whole_package` above."""for package in ("pipelex.plugins", "pipelex.providers"):- assert package in RUNTIME_LAYER_PACKAGES, (+ assert package in KERNEL_LAYER_PACKAGES, (f"{package} is one half of the plugin mechanism/adapter split and is not declared "- "runtime-layer. Undeclared means unchecked, not flagged — add the covering entry."+ "kernel-layer. Undeclared means unchecked, not flagged — add the covering entry.")def test_the_measured_clean_packages_stay_declared(self) -> None:@@ -129,7 +129,7 @@ class TestHubLayeringGuard:`graph`, `tracing`, `observer` and `errors` load zero interpreter modules and always did —yet leaving them out of the tuple is what let `graph.graph_rendering` reach `interpreter_hub`through `pipeline.dry_run_pipeline` for a whole release with every gate green. Both the layer- rule and the transitive rule filter their candidates through `is_runtime_layer`, so an+ rule and the transitive rule filter their candidates through `is_kernel_layer`, so anundeclared package sits outside the rules' domain rather than being reported by them: **anundeclared package is not neutral, it is unpoliced.**@@ -137,41 +137,41 @@ class TestHubLayeringGuard:The neighbouring checks all *iterate* the tuple — every entry resolves on disk, no entry isalso an interpreter package — so they say nothing about a name that is simply gone. Sameshape and same reasoning as `test_the_plugin_split_left_both_halves_declared` above, and- membership is likewise the whole assertion: `is_runtime_layer` matches by dotted prefix, so+ membership is likewise the whole assertion: `is_kernel_layer` matches by dotted prefix, sothe entry's presence is the one bit that matters."""for package in ("pipelex.graph", "pipelex.tracing", "pipelex.observer", "pipelex.errors"):- assert package in RUNTIME_LAYER_PACKAGES, (- f"{package} was measured clean and declared runtime-layer, and is no longer in the "+ assert package in KERNEL_LAYER_PACKAGES, (+ f"{package} was measured clean and declared kernel-layer, and is no longer in the ""declaration. Undeclared means unchecked, not flagged — restore the entry, or move ""whatever made it dirty to the layer it belongs to.")- def test_the_boot_split_left_the_runtime_half_declared(self) -> None:- """The runtime composition root must stay declared — and its interpreter half must not be.+ def test_the_boot_split_left_the_kernel_half_declared(self) -> None:+ """The kernel composition root must stay declared — and its interpreter half must not be.`pipelex.py` was carved in half the way the plugin manifests were: the runtime boot became`pipelex/runtime_boot.py`, and `Pipelex` became the interpreter boot that subclasses it. Only- the runtime half is declarable, and declaring it is the entire reason the rule reaches it:+ the kernel half is declarable, and declaring it is the entire reason the rule reaches it:both halves were undeclared before the split, which made the composition root — the one modulethat constructs *both* layers — the single largest unpoliced surface in the tree.The negative half of the assertion matters just as much. `pipelex.pipelex` imports`interpreter_hub` by construction, so declaring it would make the layer rule fail by design;- a well-meaning "the boot should be runtime-layer, surely" edit is a plausible future mistake+ a well-meaning "the boot should be kernel-layer, surely" edit is a plausible future mistakeand this is what catches it.- Membership is the whole assertion, for the same reason as the two tests above: `is_runtime_layer`+ Membership is the whole assertion, for the same reason as the two tests above: `is_kernel_layer`matches by dotted prefix, so presence is the one bit that matters."""- assert "pipelex.runtime_boot" in RUNTIME_LAYER_PACKAGES, (- "pipelex.runtime_boot is the runtime layer's composition root and is not declared "- "runtime-layer. Undeclared means unchecked, not flagged — restore the entry, or move "+ assert "pipelex.runtime_boot" in KERNEL_LAYER_PACKAGES, (+ "pipelex.runtime_boot is the kernel layer's composition root and is not declared "+ "kernel-layer. Undeclared means unchecked, not flagged — restore the entry, or move ""whatever made it dirty to the layer it belongs to.")- assert "pipelex.pipelex" not in RUNTIME_LAYER_PACKAGES, (+ assert "pipelex.pipelex" not in KERNEL_LAYER_PACKAGES, ("pipelex.pipelex is the *interpreter* half of the boot — it installs the InterpreterHub "- "and constructs the method machinery — so declaring it runtime-layer makes the layer rule "+ "and constructs the method machinery — so declaring it kernel-layer makes the layer rule ""fail by design. Declare pipelex.runtime_boot instead; that is the half that stays clean.")@@ -186,20 +186,20 @@ class TestHubLayeringGuard:breach, unlike the four above.Deleting the entry is the silent regression: the layer rule and the transitive rule both- filter through `is_runtime_layer`, and the `pipelex.exceptions` aggregate gate iterates this+ filter through `is_kernel_layer`, and the `pipelex.exceptions` aggregate gate iterates thisvery tuple — so removing the entry takes the kernel out of *three* checks at once whileevery one of them keeps reporting PASSED. Membership is the whole assertion, for the reasonthe neighbouring tests give."""- assert "pipelex.kernel" in RUNTIME_LAYER_PACKAGES, (+ assert "pipelex.kernel" in KERNEL_LAYER_PACKAGES, ("pipelex.kernel holds the operator-execution semantics that must stay callable on a "- "runtime-only boot, and it is no longer declared runtime-layer. Undeclared means "+ "kernel-only boot, and it is no longer declared kernel-layer. Undeclared means ""unchecked, not flagged — restore the entry, or move whatever made it dirty to the ""layer it belongs to.")- def test_runtime_layer_may_import_runtime_hub(self) -> None:- """The permitted direction is never flagged — the runtime layer lives on `runtime_hub`."""+ def test_kernel_layer_may_import_runtime_hub(self) -> None:+ """The permitted direction is never flagged — the kernel layer lives on `runtime_hub`."""violations = _violate("""from pipelex.runtime_hub import get_console, get_model_deck@@ -207,8 +207,8 @@ class TestHubLayeringGuard:)assert violations == []- def test_runtime_layer_importing_interpreter_hub_is_a_violation(self) -> None:- """`from pipelex.interpreter_hub import …` in the runtime layer is the forbidden arrow."""+ def test_kernel_layer_importing_interpreter_hub_is_a_violation(self) -> None:+ """`from pipelex.interpreter_hub import …` in the kernel layer is the forbidden arrow."""violations = _violate("""from pipelex.interpreter_hub import get_pipe_router@@ -285,7 +285,7 @@ class TestHubLayeringGuard:assert violations == []def test_interpreter_layer_may_import_interpreter_hub(self) -> None:- """Outside the declared runtime layer the layer rule does not apply."""+ """Outside the declared kernel layer the layer rule does not apply."""violations = _violate("""from pipelex.interpreter_hub import get_pipe_routerdiff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.pyindex 80ba2fa90..0d932a0a0 100644--- a/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py@@ -33,7 +33,7 @@ DEAD_HUB_PATCH = f'mocker.patch("{DEAD_HUB}.get_console")\n'def _make_tree(root: Path) -> None:"""A miniature repo covering every branch the walk has to get right.- `cogt/` is a declared runtime-layer package, so its breach is a violation; `pipeline/` is not, so+ `cogt/` is a declared kernel-layer package, so its breach is a violation; `pipeline/` is not, sothe identical import there is legal and must stay unreported; `__pycache__` holds a stale copy ofthe offender; and `tests/` is scanned for the dead-module rule only."""@@ -86,7 +86,7 @@ class TestHubLayeringGuardFilesystem:"pipelex/pipeline/runner.py",]- def test_a_runtime_layer_package_init_is_inside_its_own_layer(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ def test_a_kernel_layer_package_init_is_inside_its_own_layer(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:"""`__init__`-stripping is load-bearing: without it `pipelex/cogt/__init__.py` would resolve to`pipelex.cogt.__init__`, still match the layer by prefix — but a top-level `pipelex/__init__.py`would resolve to `pipelex.__init__` and land in no layer at all. Pin the package form end to end.diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py b/tests/unit/pipelex/cli/dev/test_hub_layering_transitive.pyindex 69431faed..858735464 100644--- a/tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_transitive.py@@ -1,7 +1,7 @@"""Unit tests for the hub-layering guard's transitive rule — the one that follows the import graph.The other two rules are per-file and see one hop, which is exactly how the breach that motivated this-rule stayed invisible: four modules of the declared runtime-layer `pipelex.plugins` package reached+rule stayed invisible: four modules of the declared kernel-layer `pipelex.plugins` package reached`interpreter_hub` through `runtime_bridge`, `pipeline` and `pipe_operators`, and both gates stayedgreen. So the tests here are about the *graph*: which edges exist, which do not, and which of themodules that reach the hub are the guard's business.@@ -40,7 +40,7 @@ def _write(*, path: Path, source: str) -> None:def _make_tree(root: Path) -> None:"""A miniature repo holding one instance of every case the rule must get right.- `cogt/` is a declared runtime-layer package; `runtime_bridge/` and `pipeline/` are in no declared+ `cogt/` is a declared kernel-layer package; `runtime_bridge/` and `pipeline/` are in no declaredlayer, so they may reach the hub freely — which is precisely what makes them usable asintermediaries."""@@ -48,7 +48,7 @@ def _make_tree(root: Path) -> None:_write(path=root / "pipelex" / "runtime_hub.py", source="def get_console():\n return None\n")_write(path=root / "pipelex" / "runtime_bridge" / "orchestrator.py", source=INTERMEDIARY_SOURCE)- # The canonical breach: runtime-layer module -> legal intermediary -> the hub.+ # The canonical breach: kernel-layer module -> legal intermediary -> the hub._write(path=root / "pipelex" / "cogt" / "breach.py",source="from pipelex.runtime_bridge.orchestrator import DirectOrchestrator\n",@@ -62,7 +62,7 @@ def _make_tree(root: Path) -> None:class TestHubLayeringTransitiveRule:- def test_reports_exactly_the_runtime_layer_modules_that_reach_the_hub(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ def test_reports_exactly_the_kernel_layer_modules_that_reach_the_hub(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:"""The breacher and its aggregator, with the chain that explains each — and nothing else.`pipeline/runner.py` reaches the hub by the same edge and is correctly silent: it sits in no@@ -250,7 +250,7 @@ class TestHubLayeringTransitiveRule:def test_a_dynamic_import_in_an_intermediary_is_an_edge(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:"""A module-level `import_module("pipelex.interpreter_hub")` loads the hub, so it is an edge.- Rule 1 catches that string in a runtime-layer module; the gap this closes is the same string+ Rule 1 catches that string in a kernel-layer module; the gap this closes is the same stringin an intermediary, which sits in no declared layer. Both hub references that actuallyoccurred in this repo were strings, not imports."""diff --git a/tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py b/tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.pyindex 1b47e31d2..ec9962bf0 100644--- a/tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py+++ b/tests/unit/pipelex/cogt/img_gen/test_img_gen_mapping_neutrality.py@@ -4,7 +4,7 @@# adapter (the `openai` and `azure_openai` decks both ship GPT Image models; the gateway worker# resolves Gemini geometry through the same mapping the native Google worker uses).# Nothing else 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+# `pipelex.providers` are BOTH kernel-layer, so the hub-layering guard and the import-closure test are# blind to an edge between them by construction — see docs/contribute/hub-layering.md, "Known inversions".## Two complementary checks, because the coupling can come back by two routes. The direct one is a fresh@@ -114,6 +114,6 @@ class TestImgGenMappingNeutrality:assert result.returncode == 0, ("an img-gen mapping module reached a provider adapter. The dependency runs the other way: adapters ""import inward to these mappings, never the reverse. Neither the hub-layering guard nor the "- "import-closure test can see this edge — both packages are runtime-layer.\n"+ "import-closure test can see this edge — both packages are kernel-layer.\n"f"stdout={result.stdout}\nstderr={result.stderr}")diff --git a/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py b/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.pyindex 0326dadf9..8c4faae34 100644--- a/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py+++ b/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py@@ -1,5 +1,5 @@# `pipelex.cogt` is the vendor-neutral inference engine: it owns the taxonomies, the worker protocols and-# the model registry, and it is the half of the runtime you can embed without the MTHDS interpreter. Two+# the model registry, and it is the kernel-layer half you can embed without the MTHDS interpreter. Two# facts make that neutrality real rather than aspirational, and neither is visible to any other gate:## 1. `cogt` imports no vendor SDK. Its third-party surface is framework and infrastructure only.@@ -12,7 +12,7 @@# the sanctioned edges from a new one. A golden set needs none — it turns the sixth edge into a diff a# reviewer sees, which is exactly what happened by hand three times during the modularity track.#-# Why nothing else can see this: `pipelex.cogt` and `pipelex.providers` are BOTH runtime-layer, so the+# Why nothing else can see this: `pipelex.cogt` and `pipelex.providers` are BOTH kernel-layer, so the# hub-layering guard and the import-closure test are blind to an edge between them by construction. See# docs/contribute/hub-layering.md, "Known inversions", which documents the same list in prose.#@@ -226,7 +226,7 @@ class TestCogtDependencyBoundaries:"the set of `cogt -> pipelex.providers` import statements changed.\n"f" added: {sorted(actual_edges - EXPECTED_PROVIDER_EDGES)}\n"f" removed: {sorted(EXPECTED_PROVIDER_EDGES - actual_edges)}\n"- "No other gate in this repo can see this: both packages are runtime-layer, so the hub-layering guard "+ "No other gate in this repo can see this: both packages are kernel-layer, so the hub-layering guard ""and the import-closure test are blind to an edge between them by construction. A NEW edge means the ""vendor-neutral engine grew a sixth reason to name a specific vendor — route it through ""`inference_backend_registry`, or move the code to the provider side and import inward, before "diff --git a/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py b/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.pyindex 6723cfa8a..981cea930 100644--- a/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py+++ b/tests/unit/pipelex/core/concepts/test_concept_registry_boundary.py@@ -12,7 +12,7 @@# Pinned as a golden set rather than as a rule, for the reason the `cogt` boundary test gives: there is no# predicate separating the sanctioned write-side reads from a new read-side one, and a golden set needs# none — it turns the third module into a diff a reviewer sees. Nothing else can see this: both the-# accessor and its users are runtime-layer, so the hub-layering guard is blind to the edge by construction.+# accessor and its users are kernel-layer, so the hub-layering guard is blind to the edge by construction.from __future__ import annotationsdiff --git a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py b/tests/unit/pipelex/kernel/test_kernel_boot_contract.pyindex bd9f512ec..78947be62 100644--- a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py+++ b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py@@ -6,9 +6,9 @@ router or a pipeline manager. So it is pinned permanently here rather than proveThree layers already guard neighbouring properties and none of them covers this one. The statichub-layering guard proves no kernel *module* imports `interpreter_hub`.-`test_runtime_layer_import_closure.py` proves `pipelex.kernel.pipelex_kernel` *imports* clean.+`test_kernel_layer_import_closure.py` proves `pipelex.kernel.pipelex_kernel` *imports* clean.`test_runtime_boot_closure.py` proves `RuntimeBoot.make()` *boots* clean. What none of them does is-**call** a kernel op on that boot — and a call is where a runtime-only process would actually break:+**call** a kernel op on that boot — and a call is where a kernel-only process would actually break:by resolving out of a registry the interpreter half fills (`OrchestratorRegistry`,`BundleValidatorRegistry`, the PipeFunc executor modes are all empty here), or by reaching theinterpreter through a function-local import, which is invisible to the static graph and to the@@ -21,7 +21,7 @@ memory-boundary ops (`shape_inputs` and the four extraction helpers), with the texists for is per-function, so covering one op says nothing about the next: a function-local importinside `run_search` is caught only by calling `run_search`. That also makes this the only gate theops modules other than `llm_ops` have — `PipelexKernel` is an LLM-era façade that does not import-them, so `test_runtime_layer_import_closure.py`'s `pipelex.kernel.pipelex_kernel` entry point does not+them, so `test_kernel_layer_import_closure.py`'s `pipelex.kernel.pipelex_kernel` entry point does notreach them even at import time.The memory-boundary arm carries a second proof the operator arms cannot: `shape_inputs` needs a@@ -39,27 +39,27 @@ setting below names a model the deck never has to resolve. The settings are builthan through the `resolve_*_setting` helpers for that same reason — those read the deck, which is aseparate question from the one this test asks.-**On the deferred orchestrator question.** `runtime_boot.py`'s orchestrator-rejection comment defers-the external-interpreter-orchestrator half-application hole to "the first caller of a runtime-only-boot", which is this test. It is settled, not inherited: this boot names no `boot_orchestrator` and-its config sets none, so the gate is never reached and the hole is not on this path. The remedy the-analysis proposes (a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class-attribute) remains unbuilt on purpose — it is real machinery for a path that still has no production-caller. Recorded in `wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`.+**On the once-deferred orchestrator question.** `runtime_boot.py`'s orchestrator-rejection comment used+to defer the external-interpreter-orchestrator half-application hole to "the first caller of a+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`."""import subprocess # noqa: S404import sysimport textwrap-from tests.unit.pipelex.test_runtime_layer_import_closure import INTERPRETER_PACKAGES+from tests.unit.pipelex.test_kernel_layer_import_closure import INTERPRETER_PACKAGES#: Wall-clock bound on the kernel-call subprocess, matching both sibling harnesses: a boot or a call#: that deadlocks must present as a failure, not as a hung suite#: (`docs/agents/debugging-hanging-pytest-runs.md`).SUBPROCESS_TIMEOUT_SECONDS = 300-#: Boot the runtime layer in a fresh interpreter, run **every** operator's kernel entry point, assert+#: Boot the kernel layer in a fresh interpreter, run **every** operator's kernel entry point, assert#: the typed results, and only then sweep `sys.modules`. The order is the point: a function-local#: interpreter import inside a kernel op would land in `sys.modules` during the call and nowhere else.#: Both LLM arms run because they share almost nothing below the façade — `resolve_llm_setting_for_text`@@ -131,7 +131,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(def check_stored(result, label, expected_type):# Every op ends by writing what it produced into memory as the new main stuff, and that- # write-back is the half a runtime-only caller most depends on — so each arm checks it landed.+ # write-back is the half a kernel-only caller most depends on — so each arm checks it landed.# Checked by type rather than by identity because the two are not universally the same object:# `ExtractResult` narrows its `content` field below `StuffContent`, so pydantic revalidates it# into a fresh container (see `pipelex/kernel/extract_results.py`).@@ -141,7 +141,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(class NativeOnlyConceptProvider(ConceptProviderAbstract):# A caller without a loaded library still has to answer concept questions, and this is what- # that costs on a runtime-only boot: native concepts from the pure factory, compatibility+ # that costs on a kernel-only boot: native concepts from the pure factory, compatibility# from the declaration tier the kernel doctrine routes to, and structure classes from the# class registry a RuntimeBoot fills. `shape_inputs` takes the provider explicitly for# exactly this reason — the interpreter hands over its library, a programmatic caller hands@@ -175,7 +175,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(# The input end of the memory boundary, driven the way a library-free caller drives it: raw values# plus the specs it declares for them. The shaped memory is then what the first op runs on, so the# two ends of the boundary are proven against each other rather than in isolation.- SHAPED_TOPIC = "what a runtime-only boot can run"+ SHAPED_TOPIC = "what a kernel-only boot can run"shaped_memory = shape_inputs(inputs={"topic": SHAPED_TOPIC},concept_provider=NativeOnlyConceptProvider(),@@ -323,7 +323,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(fail(f"run_img_gen produced {type(img_gen_result.content).__name__}, not the ImageContent class it was given")check_stored(img_gen_result, "run_img_gen", ImageContent)- search_query = "What runs on a runtime-only boot?"+ search_query = "What runs on a kernel-only boot?"search_result = asyncio.run(run_search(memory=WorkingMemoryFactory.make_empty(),@@ -343,7 +343,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(fail(f"run_search rendered {search_result.rendered_query!r}, not the query it was given")check_stored(search_result, "run_search", SearchResultContent)- composed_text = "Composed on a runtime-only boot."+ composed_text = "Composed on a kernel-only boot."compose_result = asyncio.run(run_compose_template(memory=WorkingMemoryFactory.make_empty(),@@ -360,7 +360,7 @@ _KERNEL_CALL_SCRIPT = textwrap.dedent(check_stored(compose_result, "run_compose_template", TextContent)# Registered here rather than imported, because the func path's whole point is that the function is- # the caller's: a runtime-only process has no library to have registered one for it.+ # the caller's: a kernel-only process has no library to have registered one for it.FUNCTION_NAME = "kernel_boot_contract_function"FUNCTION_TEXT = "produced by a registered function"@@ -408,7 +408,7 @@ CONTROL_PACKAGE_THE_KERNEL_ALWAYS_LOADS = "cogt"def _run_kernel_call(*, interpreter_packages: tuple[str, ...]) -> subprocess.CompletedProcess[str]:- """Boot the runtime layer in a fresh interpreter, call the kernel, and return the verdict."""+ """Boot the kernel layer in a fresh interpreter, call the kernel, and return the verdict."""try:return subprocess.run( # noqa: S603[sys.executable, "-c", _KERNEL_CALL_SCRIPT, *interpreter_packages],@@ -436,7 +436,7 @@ class TestKernelBootContract:assert "interpreter module(s)" in result.stdoutassert "kernel boot contract OK" not in result.stdout- def test_every_kernel_call_runs_on_a_runtime_only_boot_with_no_library(self) -> None:+ def test_every_kernel_call_runs_on_a_kernel_only_boot_with_no_library(self) -> None:result = _run_kernel_call(interpreter_packages=INTERPRETER_PACKAGES)assert result.returncode == 0, (diff --git a/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py b/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.pyindex 4846f9393..fa310edaf 100644--- a/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py+++ b/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py@@ -33,7 +33,7 @@ class TestGenerateGraphForBundle:"""Create the bundle file and patch the bundle_graph_rendering collaborators.The renderer is patched as a whole: since the split, `render_graph_from_spec` lives in the- runtime-layer `pipelex.graph.graph_rendering` and is this module's collaborator, not its+ kernel-layer `pipelex.graph.graph_rendering` and is this module's collaborator, not itsinternals. How it maps the inclusion flags onto the graph config is its own test's business(`tests/unit/pipelex/graph/test_graph_rendering.py`); what belongs here is the dispatch."""diff --git a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py b/tests/unit/pipelex/plugins/test_bundle_validator_registry.pyindex 8759fa84b..6ad1e32ea 100644--- a/tests/unit/pipelex/plugins/test_bundle_validator_registry.py+++ b/tests/unit/pipelex/plugins/test_bundle_validator_registry.py@@ -49,7 +49,7 @@ class TestBundleValidatorRegistry:def test_registered_validator_is_retrievable_by_mode(self) -> None:"""A validator registered for a mode is the exact instance the built registry returns for it."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)validator = _FakeBundleValidator()registrar.add_bundle_validator(mode=DIRECT_ORCHESTRATION_MODE, validator=validator)@@ -62,7 +62,7 @@ class TestBundleValidatorRegistry:def test_contribution_recorded_on_the_active_plugin(self) -> None:"""Registering a validator records a ``bundle validator <mode>`` contribution line on the plugin's discovery."""registrar = _make_registrar()- discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_bundle_validator(mode="temporal", validator=_FakeBundleValidator())@@ -71,9 +71,9 @@ class TestBundleValidatorRegistry:def test_duplicate_mode_fails_loud_naming_both_plugins(self) -> None:"""Two plugins registering a validator for the same mode is a fail-loud conflict naming both."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_bundle_validator(mode=DIRECT_ORCHESTRATION_MODE, validator=_FakeBundleValidator())- registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)with pytest.raises(DuplicateBundleValidatorError) as exc_info:registrar.add_bundle_validator(mode=DIRECT_ORCHESTRATION_MODE, validator=_FakeBundleValidator())diff --git a/tests/unit/pipelex/plugins/test_http_error_mapper_seam.py b/tests/unit/pipelex/plugins/test_http_error_mapper_seam.pyindex ced3dc81d..b2660e5d3 100644--- a/tests/unit/pipelex/plugins/test_http_error_mapper_seam.py+++ b/tests/unit/pipelex/plugins/test_http_error_mapper_seam.py@@ -40,7 +40,7 @@ class TestHttpErrorMapperSeam:def test_add_and_get_mapper(self) -> None:"""A registered mapper is returned keyed by its resolved exc_type and produces the classified ErrorReport when invoked."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_http_error_mapper(exc_type_provider=lambda: _FakeTransportError, to_error_report=_to_report)@@ -54,7 +54,7 @@ class TestHttpErrorMapperSeam:def test_provider_resolved_lazily_not_at_registration(self) -> None:"""The exc-type provider runs only on get_http_error_mappers (read time), never at register — the import-light invariant."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)resolutions: list[int] = []@@ -72,7 +72,7 @@ class TestHttpErrorMapperSeam:def test_contribution_is_recorded_without_resolving(self) -> None:"""Adding a mapper records a contribution line on the active plugin's discovery — and does so without resolving the exc type."""registrar = _make_registrar()- discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)def _exploding_provider() -> type[Exception]:pytest.fail("provider must not run at registration")@@ -84,9 +84,9 @@ class TestHttpErrorMapperSeam:def test_duplicate_exc_type_fails_loud_naming_both_plugins(self) -> None:"""Two plugins resolving to the same exception type is a fail-loud conflict naming both — detected at resolution time."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_http_error_mapper(exc_type_provider=lambda: _FakeTransportError, to_error_report=_to_report)- registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_http_error_mapper(exc_type_provider=lambda: _FakeTransportError, to_error_report=_to_report)with pytest.raises(DuplicateHttpErrorMapperError) as exc_info:@@ -99,7 +99,7 @@ class TestHttpErrorMapperSeam:def test_get_returns_a_fresh_dict(self) -> None:"""The accessor hands back a freshly built dict, so a consumer cannot mutate the registrar's accumulated state."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_http_error_mapper(exc_type_provider=lambda: _FakeTransportError, to_error_report=_to_report)snapshot = registrar.get_http_error_mappers()diff --git a/tests/unit/pipelex/plugins/test_import_light_boot.py b/tests/unit/pipelex/plugins/test_import_light_boot.pyindex 7463c4f45..50e32d220 100644--- a/tests/unit/pipelex/plugins/test_import_light_boot.py+++ b/tests/unit/pipelex/plugins/test_import_light_boot.py@@ -50,11 +50,11 @@ _GUARD_SCRIPT = textwrap.dedent(# The composed built-in list, both layers' halves — the same one the boot entrypoint hands to# discovery. Importing it loads the method interpreter, which is expected and is exactly why# `discovery` takes the list as a parameter instead of importing it.- from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES+ from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES, ENTRY_POINT_GROUPS# Isolate to the built-ins: ignore any external entry points installed in this venv,# whose load() could legitimately import an optional SDK.- discovery._external_entry_points = lambda: []+ discovery._external_entry_points = lambda *, groups: []# Core's built-ins claim no hub slots; building the registrar must register them all# import-light, pulling none of the BLOCKED backend SDKs into sys.modules.@@ -63,6 +63,7 @@ _GUARD_SCRIPT = textwrap.dedent(config=config,builtin_plugins=BUILTIN_PLUGINS,core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,+ entry_point_groups=ENTRY_POINT_GROUPS,)assert registrar.inference_backends, "expected the built-in LLM backends to be registered"assert registrar.model_listers, "expected the built-in model listers to be registered import-light"diff --git a/tests/unit/pipelex/plugins/test_installed_plugin_group_isolation.py b/tests/unit/pipelex/plugins/test_installed_plugin_group_isolation.pynew file mode 100644index 000000000..abd9412bd--- /dev/null+++ b/tests/unit/pipelex/plugins/test_installed_plugin_group_isolation.py@@ -0,0 +1,149 @@+"""A kernel-only boot never imports an interpreter-group plugin's module — proven against a real+installed distribution.++`test_plugin_group_split.py` asks the same question with `importlib.metadata.entry_points` patched.+That is the right tool for the *branching* (which groups get queried, which menu calls are refused),+but a patched metadata API cannot answer the question this module exists for: the claim is about+what the real discovery machinery does with real installed metadata, and every interesting part of+that path — `entry_points(group=…)` reading `entry_points.txt`, `EntryPoint.load()` importing a+module by name — is exactly the part the patch replaces. A green test there is compatible with a+`build_registrar` that mishandles real metadata.++So this one synthesizes an actual distribution on disk (`*.dist-info/` with `entry_points.txt`),+puts it on `sys.path`, and observes whether the plugin's module body ran. It runs in a+**subprocess** because the observable is a *first* import: once anything in the pytest process has+imported the module, the body never runs again and the assertion would pass vacuously forever after.++The kernel-only arm is the property. The both-groups arm is the vacuity guard, and it is not+optional: a fixture that no boot can discover — a typo in the group, an unreadable `dist-info`, a+`sys.path` that never took — makes the kernel-only arm pass for the wrong reason and look identical+to success.+"""++from __future__ import annotations++import os+import subprocess # noqa: S404+import sys+import textwrap+from typing import TYPE_CHECKING++from pipelex.plugins.contract import PLUGIN_API_VERSION+from pipelex.plugins.plugin_group import PluginGroup++if TYPE_CHECKING:+ from pathlib import Path++#: Wall-clock bound on the discovery subprocess, matching the other subprocess harnesses: a boot that+#: deadlocks must present as a failure, not as a hung suite+#: (`docs/agents/debugging-hanging-pytest-runs.md`).+SUBPROCESS_TIMEOUT_SECONDS = 300++#: The synthetic distribution's import name, entry-point name, and dist name. Distinct from each+#: other on purpose: discovery denylists by entry-point name *before* `load()` and by plugin `.name`+#: after, so a fixture that spelled all three the same could hide a mix-up between them.+_MODULE_NAME = "synthetic_interpreter_plugin"+_ENTRY_POINT_NAME = "synthetic-interpreter"+_DIST_NAME = "synthetic-interpreter-plugin"++#: Importing this module writes the sentinel. A file rather than an in-process flag because the+#: question is asked across a process boundary, and it records *module-body execution* — the thing+#: that actually drags an interpreter-layer dependency chain into the process — rather than the+#: weaker "the name appeared in `sys.modules`".+_PLUGIN_SOURCE = textwrap.dedent(+ f"""+ import os+ import pathlib++ pathlib.Path(os.environ["PLUGIN_IMPORT_SENTINEL"]).write_text("imported", encoding="utf-8")+++ class SyntheticInterpreterPlugin:+ name = "{_ENTRY_POINT_NAME}"+ targets_api = {PLUGIN_API_VERSION}++ def register(self, registrar):+ # Contributes nothing: this fixture exists to be imported or not imported, and a real+ # contribution would drag the menu-tier cross-check into an unrelated assertion.+ pass+ """+)++#: The kernel-only arm boots through `RuntimeBoot.make()` and passes **no** `entry_point_groups`, so+#: the group set under test is the production default rather than one the test supplies. That is+#: deliberate and it is the only place anything asserts it: `KERNEL_ENTRY_POINT_GROUPS` and the+#: `runtime_boot` call site that reads it are otherwise unreferenced by any test, so a mutation of+#: either — widening the constant, or passing the composed `ENTRY_POINT_GROUPS` at the call site —+#: would load every installed interpreter-group plugin and leave the whole suite green.+_DISCOVERY_SCRIPT = textwrap.dedent(+ """+ import pathlib+ import sys+ from types import SimpleNamespace++ site_dir, sentinel_path, entry_point_name = sys.argv[1:4]+ sys.path.insert(0, site_dir)+ sentinel = pathlib.Path(sentinel_path)++ from pipelex.plugins.discovery import build_registrar+ from pipelex.plugins.plugin_group import PluginGroup+ from pipelex.runtime_boot import RuntimeBoot+ from pipelex.system.runtime import IntegrationMode++ RuntimeBoot.make(integration_mode=IntegrationMode.PYTEST, needs_inference=False)+ if sentinel.exists():+ print("a kernel-only boot imported the interpreter-group plugin's module")+ raise SystemExit(2)++ both = build_registrar(+ config=SimpleNamespace(plugins=SimpleNamespace(disabled=[])),+ builtin_plugins=[],+ core_unconditional_plugin_names=frozenset(),+ entry_point_groups=(PluginGroup.KERNEL, PluginGroup.INTERPRETER),+ )+ if not sentinel.exists():+ print("the fixture is inert: a both-groups discovery did not import it either")+ raise SystemExit(4)+ # Membership, not equality: the subprocess keeps the ambient site-packages, so a developer who+ # has any real migrated plugin installed would otherwise get a false red here — and that is+ # exactly the population most likely to run this suite. "Our fixture was discovered" is the+ # property; "nothing else was" is a fact about the machine.+ if entry_point_name not in [discovery.name for discovery in both.discoveries]:+ print(f"a both-groups discovery did not register the plugin: {both.discoveries}")+ raise SystemExit(5)++ print("group isolation OK")+ """+)+++class TestInstalledPluginGroupIsolation:+ def test_a_kernel_only_boot_never_imports_an_installed_interpreter_group_plugin(self, tmp_path: Path) -> None:+ """Not discovered, not loaded, module body never run — against real installed metadata."""+ site_dir = tmp_path / "site"+ site_dir.mkdir()+ (site_dir / f"{_MODULE_NAME}.py").write_text(_PLUGIN_SOURCE, encoding="utf-8")++ dist_info = site_dir / f"{_DIST_NAME.replace('-', '_')}-1.0.dist-info"+ dist_info.mkdir()+ (dist_info / "METADATA").write_text(+ f"Metadata-Version: 2.1\nName: {_DIST_NAME}\nVersion: 1.0\n",+ encoding="utf-8",+ )+ (dist_info / "entry_points.txt").write_text(+ f"[{PluginGroup.INTERPRETER}]\n{_ENTRY_POINT_NAME} = {_MODULE_NAME}:SyntheticInterpreterPlugin\n",+ encoding="utf-8",+ )++ sentinel = tmp_path / "imported.sentinel"+ result = subprocess.run( # noqa: S603+ [sys.executable, "-c", _DISCOVERY_SCRIPT, str(site_dir), str(sentinel), _ENTRY_POINT_NAME],+ capture_output=True,+ text=True,+ check=False,+ env={**os.environ, "PLUGIN_IMPORT_SENTINEL": str(sentinel)},+ timeout=SUBPROCESS_TIMEOUT_SECONDS,+ )++ assert result.returncode == 0, f"group isolation failed:\nstdout={result.stdout}\nstderr={result.stderr}"+ assert "group isolation OK" in result.stdoutdiff --git a/tests/unit/pipelex/plugins/test_pipe_func_executor_registry.py b/tests/unit/pipelex/plugins/test_pipe_func_executor_registry.pyindex a9c264af9..50eedd7a4 100644--- a/tests/unit/pipelex/plugins/test_pipe_func_executor_registry.py+++ b/tests/unit/pipelex/plugins/test_pipe_func_executor_registry.py@@ -41,7 +41,7 @@ class TestPipeFuncExecutorRegistry:def test_registered_factory_is_retrievable_by_mode(self) -> None:"""A factory registered for a mode is the exact callable the built registry returns for it."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_pipe_func_executor(mode="daytona", factory=_fake_factory)registry = PipeFuncExecutorRegistry(registrar.pipe_func_executors)@@ -52,7 +52,7 @@ class TestPipeFuncExecutorRegistry:def test_contribution_recorded_on_the_active_plugin(self) -> None:"""Registering an executor records a ``pipe_func executor <mode>`` contribution on the plugin's discovery."""registrar = _make_registrar()- discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_pipe_func_executor(mode="daytona", factory=_fake_factory)@@ -61,7 +61,7 @@ class TestPipeFuncExecutorRegistry:def test_get_required_miss_raises_listing_registered_modes(self) -> None:"""A miss names the requested mode and lists the registered ones (the boot-time actionable error)."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_pipe_func_executor(mode="direct", factory=_fake_factory)registrar.add_pipe_func_executor(mode="local_sandbox", factory=_fake_factory)registry = PipeFuncExecutorRegistry(registrar.pipe_func_executors)@@ -87,9 +87,9 @@ class TestPipeFuncExecutorRegistry:def test_duplicate_mode_fails_loud_naming_both_plugins(self) -> None:"""Two plugins registering an executor for the same mode is a fail-loud conflict naming both."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_pipe_func_executor(mode="daytona", factory=_fake_factory)- registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)with pytest.raises(DuplicatePipeFuncExecutorError) as exc_info:registrar.add_pipe_func_executor(mode="daytona", factory=_fake_factory)@@ -101,7 +101,7 @@ class TestPipeFuncExecutorRegistry:def test_builtin_plugin_registers_only_direct(self) -> None:"""The core PipeFuncPlugin contributes exactly ``direct`` (in-process); sandbox modes are out of tree."""registrar = _make_registrar()- registrar.begin_plugin(name="pipe_func", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="pipe_func", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION, group=None)PipeFuncPlugin().register(registrar)registry = PipeFuncExecutorRegistry(registrar.pipe_func_executors)diff --git a/tests/unit/pipelex/plugins/test_plugin_discovery.py b/tests/unit/pipelex/plugins/test_plugin_discovery.pyindex 3e8482f00..370b6b227 100644--- a/tests/unit/pipelex/plugins/test_plugin_discovery.py+++ b/tests/unit/pipelex/plugins/test_plugin_discovery.py@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING, castimport pytestfrom pipelex.plugins.contract import PLUGIN_API_VERSION, PipelexPlugin-from pipelex.plugins.discovery import build_registrar+from pipelex.plugins.discovery import GroupedEntryPoint, build_registrarfrom pipelex.plugins.exceptions import (BrokenPluginError,CoreUnconditionalPluginDisabledError,@@ -21,10 +21,12 @@ from pipelex.plugins.exceptions import (PluginApiVersionMismatchError,)from pipelex.plugins.inference_backend_registry import InferenceFamily+from pipelex.plugins.plugin_group import PluginGroupfrom pipelex.plugins.registrar import PluginOrigin, PluginRegistrar, PluginStatusif TYPE_CHECKING:from collections.abc import Sequence+ from importlib.metadata import EntryPointfrom pytest_mock import MockerFixture@@ -37,6 +39,9 @@ DISCOVERY_MODULE = "pipelex.plugins.discovery"#: The default for tests that exercise no core-unconditional plugin: nothing is undisableable.NO_CORE_UNCONDITIONAL: frozenset[str] = frozenset()+#: What a method-running boot reads. The layer split itself is exercised in test_plugin_group_split.+BOTH_GROUPS: tuple[PluginGroup, ...] = (PluginGroup.KERNEL, PluginGroup.INTERPRETER)+def _noop_make_worker(**_kwargs: object) -> InferenceWorkerAbstract:msg = "make_worker is never invoked by discovery tests"@@ -97,8 +102,8 @@ def _build_registrar_with("""Build a registrar over exactly ``plugins``, with external entry points stubbed out.The built-in list is a *parameter* of ``build_registrar`` rather than a module global it imports:- some built-ins adapt interpreter-layer ports, so importing them from the runtime-layer discovery- module would put the method interpreter back into every runtime import closure. Which is why these+ some built-ins adapt interpreter-layer ports, so importing them from the kernel-layer discovery+ module would put the method interpreter back into every kernel import closure. Which is why thesetests hand the list in instead of patching a module attribute."""mocker.patch(f"{DISCOVERY_MODULE}._external_entry_points", return_value=[])@@ -106,6 +111,7 @@ def _build_registrar_with(config=_fake_config(disabled or []),builtin_plugins=cast("Sequence[PipelexPlugin]", plugins),core_unconditional_plugin_names=core_unconditional,+ entry_point_groups=BOTH_GROUPS,)@@ -121,7 +127,7 @@ class TestPluginDiscovery:def test_the_two_layer_halves_compose_into_one_list(self) -> None:"""The composition root's list is exactly both halves, and each name appears once.- The halves are filed by layer — `pipelex.plugins` for the runtime adapters,+ The halves are filed by layer — `pipelex.providers` for the kernel adapters,`pipelex.interpreter_plugins` for the ones that construct interpreter-layer objects — so thefailure mode this pins is a half silently dropping out of the composition, which would presentas a plugin quietly missing at boot rather than as an import error.@@ -132,10 +138,10 @@ class TestPluginDiscovery:INTERPRETER_BUILTIN_PLUGINS,INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES,)- from pipelex.providers.builtins import RUNTIME_BUILTIN_PLUGINS, RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES # noqa: PLC0415+ from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS, KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES # noqa: PLC0415- assert [*INTERPRETER_BUILTIN_PLUGINS, *RUNTIME_BUILTIN_PLUGINS] == BUILTIN_PLUGINS- assert CORE_UNCONDITIONAL_PLUGIN_NAMES == INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES | RUNTIME_CORE_UNCONDITIONAL_PLUGIN_NAMES+ assert [*INTERPRETER_BUILTIN_PLUGINS, *KERNEL_BUILTIN_PLUGINS] == BUILTIN_PLUGINS+ assert CORE_UNCONDITIONAL_PLUGIN_NAMES == INTERPRETER_CORE_UNCONDITIONAL_PLUGIN_NAMES | KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMESnames = [plugin.name for plugin in BUILTIN_PLUGINS]assert len(names) == len(set(names))assert set(names) >= CORE_UNCONDITIONAL_PLUGIN_NAMES@@ -190,9 +196,12 @@ class TestPluginDiscovery:raise ImportError(msg)bad_entry_point = SimpleNamespace(name="bad_ep", load=_explode)- mocker.patch(f"{DISCOVERY_MODULE}._external_entry_points", return_value=[bad_entry_point])+ grouped = GroupedEntryPoint(group=PluginGroup.KERNEL, entry_point=cast("EntryPoint", bad_entry_point))+ mocker.patch(f"{DISCOVERY_MODULE}._external_entry_points", return_value=[grouped])with pytest.raises(BrokenPluginError) as exc_info:- build_registrar(config=_fake_config([]), builtin_plugins=[], core_unconditional_plugin_names=NO_CORE_UNCONDITIONAL)+ build_registrar(+ config=_fake_config([]), builtin_plugins=[], core_unconditional_plugin_names=NO_CORE_UNCONDITIONAL, entry_point_groups=BOTH_GROUPS+ )assert "bad_ep" in str(exc_info.value)def test_disabled_broken_external_entry_point_is_skipped_before_load(self, mocker: MockerFixture) -> None:@@ -205,9 +214,12 @@ class TestPluginDiscovery:raise ImportError(msg)bad_entry_point = SimpleNamespace(name="bad_ep", load=_explode)- mocker.patch(f"{DISCOVERY_MODULE}._external_entry_points", return_value=[bad_entry_point])+ grouped = GroupedEntryPoint(group=PluginGroup.KERNEL, entry_point=cast("EntryPoint", bad_entry_point))+ mocker.patch(f"{DISCOVERY_MODULE}._external_entry_points", return_value=[grouped])- registrar = build_registrar(config=_fake_config(["bad_ep"]), builtin_plugins=[], core_unconditional_plugin_names=NO_CORE_UNCONDITIONAL)+ registrar = build_registrar(+ config=_fake_config(["bad_ep"]), builtin_plugins=[], core_unconditional_plugin_names=NO_CORE_UNCONDITIONAL, entry_point_groups=BOTH_GROUPS+ )disabled_discovery = next(discovery for discovery in registrar.discoveries if discovery.name == "bad_ep")assert disabled_discovery.status == PluginStatus.DISABLED@@ -237,6 +249,7 @@ class TestPluginDiscovery:config=_fake_config([plugin_name]),builtin_plugins=BUILTIN_PLUGINS,core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,+ entry_point_groups=BOTH_GROUPS,)assert plugin_name in str(exc_info.value)@@ -248,6 +261,7 @@ class TestPluginDiscovery:config=_fake_config([]),builtin_plugins=BUILTIN_PLUGINS,core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,+ entry_point_groups=BOTH_GROUPS,)by_name = {discovery.name: discovery for discovery in registrar.discoveries}assert "openai" in by_namediff --git a/tests/unit/pipelex/plugins/test_plugin_group_split.py b/tests/unit/pipelex/plugins/test_plugin_group_split.pynew file mode 100644index 000000000..75fa9b260--- /dev/null+++ b/tests/unit/pipelex/plugins/test_plugin_group_split.py@@ -0,0 +1,293 @@+"""The layer split in plugin discovery: two entry-point groups, the menu-tier cross-check that+keeps a kernel-group plugin honest, and the fail-loud probe on the retired single group.+"""++from __future__ import annotations++from types import SimpleNamespace+from typing import TYPE_CHECKING, cast++import pytest++from pipelex.plugins.contract import PLUGIN_API_VERSION+from pipelex.plugins.discovery import RETIRED_ENTRY_POINT_GROUP, build_registrar+from pipelex.plugins.exceptions import PluginDeclaredInMultipleGroupsError, PluginLayerViolationError, RetiredPluginEntryPointGroupError+from pipelex.plugins.inference_backend_registry import InferenceFamily+from pipelex.plugins.plugin_group import PluginGroup++if TYPE_CHECKING:+ from collections.abc import Callable, Sequence++ from pytest_mock import MockerFixture++ from pipelex.base_exceptions import ErrorReport+ from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract+ from pipelex.plugins.bundle_validator_registry import BundleValidatorProtocol+ from pipelex.plugins.contract import PipelexPlugin+ from pipelex.plugins.orchestrator_registry import OrchestratorProtocol+ from pipelex.plugins.pipe_func_executor_registry import PipeFuncExecutorFactoryFn+ from pipelex.plugins.registrar import PluginRegistrar+ from pipelex.system.configuration.configs import PipelexConfig++#: Every menu call that contributes an interpreter-layer capability — the set a kernel-group plugin+#: may not reach. Keyed by the fragment its violation message must name, so a renamed capability+#: shows up here rather than silently weakening the cross-check.+INTERPRETER_TIER_CALLS: dict[str, Callable[[PluginRegistrar], None]] = {+ "orchestrator": lambda registrar: registrar.add_orchestrator(mode="temporal", orchestrator=cast("OrchestratorProtocol", object())),+ "bundle validator": lambda registrar: registrar.add_bundle_validator(mode="temporal", validator=cast("BundleValidatorProtocol", object())),+ "pipe_func executor": lambda registrar: registrar.add_pipe_func_executor(mode="daytona", factory=cast("PipeFuncExecutorFactoryFn", object)),+ "hub slot pipe_router": lambda registrar: registrar.claim_pipe_router(object),+ "hub slot pipe_run": lambda registrar: registrar.claim_pipe_run(object),+ "hub slot pipe_func_executor": lambda registrar: registrar.claim_pipe_func_executor(object),+}++#: The other half of `HubSlot.is_interpreter_layer` — the slots a kernel-group plugin may claim.+#: Asserted explicitly because the exhaustive match forces a *classification* on every new slot but+#: not a correct one: with only the refusals pinned, moving any of these into the interpreter arm+#: would silently narrow what a kernel-group plugin can do and no test would object.+KERNEL_TIER_CLAIMS: dict[str, Callable[[PluginRegistrar], None]] = {+ "content_generator": lambda registrar: registrar.claim_content_generator(object),+ "task_manager": lambda registrar: registrar.claim_task_manager(object),+ "isolated_execution_probe": lambda registrar: registrar.claim_isolated_execution_probe(object),+}+++def _noop_make_worker(**_kwargs: object) -> InferenceWorkerAbstract:+ msg = "make_worker is never invoked by discovery tests"+ raise AssertionError(msg)+++def _fake_config() -> PipelexConfig:+ return cast("PipelexConfig", SimpleNamespace(plugins=SimpleNamespace(disabled=[])))+++class _ContributingPlugin:+ """A plugin whose ``register`` runs exactly the menu calls it was handed."""++ def __init__(self, *, name: str, contributions: Sequence[Callable[[PluginRegistrar], None]]):+ self.name = name+ self.targets_api = PLUGIN_API_VERSION+ self._contributions = contributions++ def register(self, registrar: PluginRegistrar) -> None:+ for contribute in self._contributions:+ contribute(registrar)+++def _add_inference_backend(registrar: PluginRegistrar) -> None:+ registrar.add_inference_backend(family=InferenceFamily.LLM, sdk="synthetic_sdk", make_worker=_noop_make_worker)+++def _add_http_error_mapper(registrar: PluginRegistrar) -> None:+ registrar.add_http_error_mapper(exc_type_provider=lambda: TimeoutError, to_error_report=cast("Callable[..., ErrorReport]", object))+++def _add_teardown(registrar: PluginRegistrar) -> None:+ registrar.add_teardown(lambda: None)+++def _entry_point(*, name: str, plugin: object) -> SimpleNamespace:+ """An entry point resolving to an already-instantiated plugin, like ``my_package:make_plugin``."""+ return SimpleNamespace(name=name, load=lambda: plugin)+++def _discover(+ *,+ mocker: MockerFixture,+ external: dict[str, list[object]] | None = None,+ retired: list[object] | None = None,+ groups: Sequence[PluginGroup] = (PluginGroup.KERNEL, PluginGroup.INTERPRETER),+ builtins: Sequence[object] = (),+) -> PluginRegistrar:+ """Run discovery against a synthetic installed-distribution set, keyed by entry-point group.++ Patches ``importlib.metadata.entry_points`` rather than this module's own helper, so the+ group filtering under test is the real one — a group the caller did not ask for must never+ be read, and that is only observable if discovery does the querying itself.+ """+ by_group: dict[str, list[object]] = dict(external or {})+ by_group[RETIRED_ENTRY_POINT_GROUP] = retired or []++ def _installed(*, group: str) -> list[object]:+ return by_group.get(group, [])++ mocker.patch("importlib.metadata.entry_points", side_effect=_installed)+ return build_registrar(+ config=_fake_config(),+ builtin_plugins=cast("Sequence[PipelexPlugin]", builtins),+ core_unconditional_plugin_names=frozenset(),+ entry_point_groups=groups,+ )+++class TestPluginGroupSplit:+ def test_a_kernel_group_plugin_contributes_kernel_capabilities_and_records_its_group(self, mocker: MockerFixture) -> None:+ """The kernel tier is what a kernel-group plugin is for; `plugins list` reads the group back."""+ plugin = _ContributingPlugin(name="synthetic_backend", contributions=[_add_inference_backend, _add_http_error_mapper])+ registrar = _discover(mocker=mocker, external={PluginGroup.KERNEL: [_entry_point(name="synthetic_backend", plugin=plugin)]})++ assert (InferenceFamily.LLM, "synthetic_sdk") in registrar.inference_backends+ discovery = next(discovery for discovery in registrar.discoveries if discovery.name == "synthetic_backend")+ assert discovery.group == PluginGroup.KERNEL++ @pytest.mark.parametrize("capability", list(INTERPRETER_TIER_CALLS))+ def test_a_kernel_group_plugin_reaching_the_interpreter_tier_fails_loud(self, capability: str, mocker: MockerFixture) -> None:+ """A plugin lying about its layer is caught at register time, before anything is wired."""+ plugin = _ContributingPlugin(name="liar", contributions=[INTERPRETER_TIER_CALLS[capability]])+ with pytest.raises(PluginLayerViolationError) as exc_info:+ _discover(mocker=mocker, external={PluginGroup.KERNEL: [_entry_point(name="liar", plugin=plugin)]})++ message = str(exc_info.value)+ assert "liar" in message+ assert capability in message+ assert PluginGroup.INTERPRETER in message++ @pytest.mark.parametrize("slot", list(KERNEL_TIER_CLAIMS))+ def test_a_kernel_group_plugin_may_claim_the_kernel_tier_hub_slots(self, slot: str, mocker: MockerFixture) -> None:+ """Not every hub slot is interpreter-layer, and the permission matters as much as the refusal.++ These three hand back no `Pipe`-aware object and are applied in the kernel boot, so refusing+ them would push a plugin that needs one into the interpreter group — where a kernel-only boot+ would never load it at all. That is the silent-absence failure the split exists to remove, so+ over-restricting here is not a safe direction to err in.+ """+ plugin = _ContributingPlugin(name="kernel_claimant", contributions=[KERNEL_TIER_CLAIMS[slot]])+ registrar = _discover(mocker=mocker, external={PluginGroup.KERNEL: [_entry_point(name="kernel_claimant", plugin=plugin)]})++ discovery = next(discovery for discovery in registrar.discoveries if discovery.name == "kernel_claimant")+ assert discovery.group == PluginGroup.KERNEL+ assert slot in str(discovery.contributions)++ def test_an_interpreter_group_plugin_may_contribute_both_tiers(self, mocker: MockerFixture) -> None:+ """The tiers are a *menu restriction on the kernel group*, not a partition.++ Our own Temporal plugin is the case that settles the direction: it is interpreter-side (it+ contributes an orchestrator) and it also contributes an HTTP-error mapper, a kernel-tier+ capability. A symmetric rule would reject it — and would be rejecting nothing dangerous, since+ a kernel-only boot never loads the interpreter group in the first place.+ """+ plugin = _ContributingPlugin(+ name="synthetic_orchestrator",+ contributions=[INTERPRETER_TIER_CALLS["orchestrator"], _add_http_error_mapper, _add_inference_backend],+ )+ registrar = _discover(mocker=mocker, external={PluginGroup.INTERPRETER: [_entry_point(name="synthetic_orchestrator", plugin=plugin)]})++ assert registrar.orchestrators+ assert registrar.http_error_mappers+ assert (InferenceFamily.LLM, "synthetic_sdk") in registrar.inference_backends++ def test_a_builtin_is_not_subject_to_the_cross_check(self, mocker: MockerFixture) -> None:+ """Built-ins arrive under no entry-point group — they are filed by layer in-tree instead.++ `direct` and `pipe_func` are interpreter-layer built-ins that a kernel-only boot simply never+ passes in, and the hub-layering guard already polices where they may live.+ """+ plugin = _ContributingPlugin(name="direct_like", contributions=[INTERPRETER_TIER_CALLS["orchestrator"]])+ registrar = _discover(mocker=mocker, builtins=[plugin])++ assert registrar.orchestrators+ discovery = next(discovery for discovery in registrar.discoveries if discovery.name == "direct_like")+ assert discovery.group is None++ def test_a_kernel_only_boot_never_loads_an_interpreter_group_entry_point(self, mocker: MockerFixture) -> None:+ """The whole point of the split: not loaded, not merely not registered.++ An interpreter-group plugin's module is what drags the method interpreter into the process, so+ the guarantee has to be about ``load()``, not about what ends up in the registrar.+ """+ loaded: list[str] = []++ def _exploding_load() -> object:+ loaded.append("interpreter_side")+ msg = "a kernel-only boot must not load an interpreter-group entry point"+ raise AssertionError(msg)++ interpreter_entry_point = SimpleNamespace(name="interpreter_side", load=_exploding_load)+ kernel_plugin = _ContributingPlugin(name="kernel_side", contributions=[_add_inference_backend])+ registrar = _discover(+ mocker=mocker,+ external={+ PluginGroup.KERNEL: [_entry_point(name="kernel_side", plugin=kernel_plugin)],+ PluginGroup.INTERPRETER: [interpreter_entry_point],+ },+ groups=(PluginGroup.KERNEL,),+ )++ assert not loaded+ assert [discovery.name for discovery in registrar.discoveries] == ["kernel_side"]++ def test_the_retired_group_is_a_loud_migration_error(self, mocker: MockerFixture) -> None:+ """Silent nondiscovery is the failure this probe exists to prevent.++ A plugin still advertising under `pipelex.plugins` would otherwise just never be found —+ no orchestrator, no backend, no error, and a run that quietly does the wrong thing.+ """++ def _never_loaded() -> object:+ msg = "a retired-group entry point must be reported, never loaded"+ raise AssertionError(msg)++ with pytest.raises(RetiredPluginEntryPointGroupError) as exc_info:+ _discover(mocker=mocker, retired=[SimpleNamespace(name="unmigrated_plugin", load=_never_loaded)])++ message = str(exc_info.value)+ assert "unmigrated_plugin" in message+ assert RETIRED_ENTRY_POINT_GROUP in message+ assert PluginGroup.KERNEL in message+ assert PluginGroup.INTERPRETER in message++ def test_a_group_the_caller_did_not_ask_for_is_never_even_queried(self, mocker: MockerFixture) -> None:+ """Group filtering happens at the metadata query, not by discarding loaded plugins afterwards."""+ queried: list[str] = []++ def _record(*, group: str) -> list[object]:+ queried.append(group)+ return []++ mocker.patch("importlib.metadata.entry_points", side_effect=_record)+ build_registrar(+ config=_fake_config(),+ builtin_plugins=[],+ core_unconditional_plugin_names=frozenset(),+ entry_point_groups=(PluginGroup.KERNEL,),+ )++ assert PluginGroup.INTERPRETER not in queried+ assert PluginGroup.KERNEL in queried+ assert RETIRED_ENTRY_POINT_GROUP in queried++ def test_a_plugin_declared_under_both_groups_fails_loud(self, mocker: MockerFixture) -> None:+ """One plugin, two groups: read twice, loaded twice, and `register` run twice.++ The contribution here is a bare teardown callback on purpose — it is the one menu method+ with neither a key nor a tier guard, so the double registration is *silent*: the callback+ simply lands in the list twice and runs twice at shutdown. Every other menu method happens+ to collide on its own, but it does so by naming the same plugin as both parties to the+ conflict, which reads as a bug in Pipelex rather than as a misdeclared distribution. Neither+ symptom points at the cause, so discovery names it.+ """+ plugin = _ContributingPlugin(name="double_dipper", contributions=[_add_teardown])+ with pytest.raises(PluginDeclaredInMultipleGroupsError) as exc_info:+ _discover(+ mocker=mocker,+ external={+ PluginGroup.KERNEL: [_entry_point(name="double_dipper", plugin=plugin)],+ PluginGroup.INTERPRETER: [_entry_point(name="double_dipper", plugin=plugin)],+ },+ )++ message = str(exc_info.value)+ assert "double_dipper" in message+ assert PluginGroup.KERNEL in message+ assert PluginGroup.INTERPRETER in message++ def test_the_same_plugin_name_in_one_group_is_untouched(self, mocker: MockerFixture) -> None:+ """The check is about one name spanning two groups, not about the name itself.++ Guards the obvious over-reach: a dedup keyed on the name alone would also reject the+ ordinary single-group plugin, and every other test here would still pass.+ """+ plugin = _ContributingPlugin(name="honest", contributions=[_add_teardown])+ registrar = _discover(mocker=mocker, external={PluginGroup.KERNEL: [_entry_point(name="honest", plugin=plugin)]})++ assert [discovery.name for discovery in registrar.discoveries] == ["honest"]diff --git a/tests/unit/pipelex/plugins/test_secrets_provider_registry.py b/tests/unit/pipelex/plugins/test_secrets_provider_registry.pyindex e0af20edc..bc09d6501 100644--- a/tests/unit/pipelex/plugins/test_secrets_provider_registry.py+++ b/tests/unit/pipelex/plugins/test_secrets_provider_registry.py@@ -38,7 +38,7 @@ class TestSecretsProviderRegistry:def test_registered_factory_is_retrievable_by_method(self) -> None:"""A factory registered for a method is the exact callable the built registry returns for it."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_secrets_provider(method="vault", factory=_fake_factory)registry = SecretsProviderRegistry(registrar.secrets_providers)@@ -49,7 +49,7 @@ class TestSecretsProviderRegistry:def test_contribution_recorded_on_the_active_plugin(self) -> None:"""Registering a provider records a ``secrets provider <method>`` contribution on the plugin's discovery."""registrar = _make_registrar()- discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_secrets_provider(method="vault", factory=_fake_factory)@@ -58,7 +58,7 @@ class TestSecretsProviderRegistry:def test_get_required_miss_raises_listing_registered_methods(self) -> None:"""A miss names the requested method and lists the registered ones (the boot-time actionable error)."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_secrets_provider(method="env", factory=_fake_factory)registrar.add_secrets_provider(method="vault", factory=_fake_factory)registry = SecretsProviderRegistry(registrar.secrets_providers)@@ -84,9 +84,9 @@ class TestSecretsProviderRegistry:def test_duplicate_method_fails_loud_naming_both_plugins(self) -> None:"""Two plugins registering a provider for the same method is a fail-loud conflict naming both."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_secrets_provider(method="vault", factory=_fake_factory)- registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)with pytest.raises(DuplicateSecretsProviderError) as exc_info:registrar.add_secrets_provider(method="vault", factory=_fake_factory)diff --git a/tests/unit/pipelex/plugins/test_storage_provider_registry.py b/tests/unit/pipelex/plugins/test_storage_provider_registry.pyindex 2139967b3..839c5dc53 100644--- a/tests/unit/pipelex/plugins/test_storage_provider_registry.py+++ b/tests/unit/pipelex/plugins/test_storage_provider_registry.py@@ -38,7 +38,7 @@ class TestStorageProviderRegistry:def test_registered_factory_is_retrievable_by_method(self) -> None:"""A factory registered for a method is the exact callable the built registry returns for it."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_storage_provider(method="azure", factory=_fake_factory)registry = StorageProviderRegistry(registrar.storage_providers)@@ -49,7 +49,7 @@ class TestStorageProviderRegistry:def test_contribution_recorded_on_the_active_plugin(self) -> None:"""Registering a provider records a ``storage provider <method>`` contribution on the plugin's discovery."""registrar = _make_registrar()- discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_storage_provider(method="azure", factory=_fake_factory)@@ -58,7 +58,7 @@ class TestStorageProviderRegistry:def test_get_required_miss_raises_listing_registered_methods(self) -> None:"""A miss names the requested method and lists the registered ones (the boot-time actionable error)."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_storage_provider(method="local", factory=_fake_factory)registrar.add_storage_provider(method="s3", factory=_fake_factory)registry = StorageProviderRegistry(registrar.storage_providers)@@ -84,9 +84,9 @@ class TestStorageProviderRegistry:def test_duplicate_method_fails_loud_naming_both_plugins(self) -> None:"""Two plugins registering a provider for the same method is a fail-loud conflict naming both."""registrar = _make_registrar()- registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)registrar.add_storage_provider(method="azure", factory=_fake_factory)- registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION)+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)with pytest.raises(DuplicateStorageProviderError) as exc_info:registrar.add_storage_provider(method="azure", factory=_fake_factory)diff --git a/tests/unit/pipelex/providers/secrets/test_secrets_plugin.py b/tests/unit/pipelex/providers/secrets/test_secrets_plugin.pyindex b4bee840c..2798424f4 100644--- a/tests/unit/pipelex/providers/secrets/test_secrets_plugin.py+++ b/tests/unit/pipelex/providers/secrets/test_secrets_plugin.py@@ -36,7 +36,7 @@ class TestSecretsPlugin:assert plugin.targets_api == PLUGIN_API_VERSIONregistrar = PluginRegistrar(config=cast("PipelexConfig", SimpleNamespace(plugins=SimpleNamespace(disabled=[]))))- discovery = registrar.begin_plugin(name="secrets", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="secrets", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION, group=None)plugin.register(registrar)assert set(registrar.secrets_providers) == {"env"}diff --git a/tests/unit/pipelex/providers/storage/test_storage_plugin.py b/tests/unit/pipelex/providers/storage/test_storage_plugin.pyindex 42a230e04..f68940d08 100644--- a/tests/unit/pipelex/providers/storage/test_storage_plugin.py+++ b/tests/unit/pipelex/providers/storage/test_storage_plugin.py@@ -63,7 +63,7 @@ class TestStoragePlugin:assert plugin.targets_api == PLUGIN_API_VERSIONregistrar = PluginRegistrar(config=cast("PipelexConfig", SimpleNamespace(plugins=SimpleNamespace(disabled=[]))))- discovery = registrar.begin_plugin(name="storage", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION)+ discovery = registrar.begin_plugin(name="storage", origin=PluginOrigin.BUILTIN, targets_api=PLUGIN_API_VERSION, group=None)plugin.register(registrar)# StrEnum keys compare equal to their plain-str form, so boot's plain-str config.method resolves them.diff --git a/tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py b/tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.pysimilarity index 86%rename from tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.pyrename to tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.pyindex 6d02f8414..fa22e4f1c 100644--- a/tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py+++ b/tests/unit/pipelex/test_kernel_layer_exceptions_aggregate_gate.py@@ -1,8 +1,8 @@-"""No declared runtime-layer module may import the `pipelex.exceptions` aggregate — mechanically.+"""No declared kernel-layer module may import the `pipelex.exceptions` aggregate — mechanically.`pipelex/exceptions.py` is the public all-errors aggregate: it re-exports every interpreterpackage's exceptions, so importing anything from it loads `pipelex.libraries`, `pipelex.pipeline`,-`pipelex.pipe_operators` and more. From a runtime-layer module that is a layer breach, and it is+`pipelex.pipe_operators` and more. From a kernel-layer module that is a layer breach, and it isexactly the breach neither existing gate can see: `check-hub-layering`'s rules only chase`pipelex.interpreter_hub`, which the aggregate never reaches, and the import-closure test onlycovers module-level imports under its declared entry points — a function-local import is invisible@@ -10,7 +10,7 @@ to both. Five vendor adapters once loaded interpreter modules apiece through prewith both gates green (see `docs/contribute/hub-layering.md`, the aggregate section).Until now the rule was prose — *import from the definition site, never from the aggregate*. This-test makes it mechanical for every package declared in `RUNTIME_LAYER_PACKAGES`: it AST-walks each+test makes it mechanical for every package declared in `KERNEL_LAYER_PACKAGES`: it AST-walks eachmodule and fails on any import of `pipelex.exceptions`, module-level or function-local, absolute orrelative — and on any bare string literal naming it, because `importlib.import_module`,`__import__` and a `mocker.patch` target all load the aggregate through a path no import node@@ -20,14 +20,14 @@ the aggregate is not a reference. The fix for a violation is always the same andimport the error class from the `exceptions.py` module that defines it.Interpreter-side code and tests are out of scope on purpose — the aggregate is a legitimate public-surface for callers *outside* the runtime layer; the ban is on the layer whose import closure it+surface for callers *outside* the kernel layer; the ban is on the layer whose import closure itwould silently widen."""import astfrom pathlib import Path-from pipelex.cli.dev_cli.commands.hub_layering_guard import RUNTIME_LAYER_PACKAGES, references_module+from pipelex.cli.dev_cli.commands.hub_layering_guard import KERNEL_LAYER_PACKAGES, references_module_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")_REPO_ROOT = _TESTS_ROOT.parent@@ -80,7 +80,7 @@ def find_aggregate_references(*, module_path: Path, module_dotted: str) -> list[def _module_paths_for(*, dotted_package: str) -> list[Path]:- """Yield the .py files a `RUNTIME_LAYER_PACKAGES` entry covers — a package directory or a lone module."""+ """Yield the .py files a `KERNEL_LAYER_PACKAGES` entry covers — a package directory or a lone module."""base_path = _REPO_ROOT / Path(*dotted_package.split("."))if base_path.is_dir():return sorted(base_path.rglob("*.py"))@@ -95,15 +95,15 @@ def _dotted_for(*, module_path: Path) -> str:return ".".join(relative_parts)-class TestRuntimeLayerExceptionsAggregateGate:- def test_no_runtime_layer_module_imports_the_exceptions_aggregate(self) -> None:+class TestKernelLayerExceptionsAggregateGate:+ def test_no_kernel_layer_module_imports_the_exceptions_aggregate(self) -> None:violations: list[str] = []- for dotted_package in RUNTIME_LAYER_PACKAGES:+ for dotted_package in KERNEL_LAYER_PACKAGES:for module_path in _module_paths_for(dotted_package=dotted_package):violations.extend(find_aggregate_references(module_path=module_path, module_dotted=_dotted_for(module_path=module_path)))assert not violations, (- "Runtime-layer modules reference the `pipelex.exceptions` aggregate, which drags interpreter packages "- "into the runtime closure. Import each error class from the `exceptions.py` module that defines it instead:\n" + "\n".join(violations)+ "Kernel-layer modules reference the `pipelex.exceptions` aggregate, which drags interpreter packages "+ "into the kernel closure. Import each error class from the `exceptions.py` module that defines it instead:\n" + "\n".join(violations))def test_the_gate_detects_every_banned_reference_shape(self, tmp_path: Path) -> None:diff --git a/tests/unit/pipelex/test_runtime_layer_import_closure.py b/tests/unit/pipelex/test_kernel_layer_import_closure.pysimilarity index 90%rename from tests/unit/pipelex/test_runtime_layer_import_closure.pyrename to tests/unit/pipelex/test_kernel_layer_import_closure.pyindex fdf3eb6ab..dfaf2f156 100644--- a/tests/unit/pipelex/test_runtime_layer_import_closure.py+++ b/tests/unit/pipelex/test_kernel_layer_import_closure.py@@ -1,26 +1,26 @@-"""Importing the Pipelex runtime loads zero interpreter modules — the property, not the rule.+"""Importing the Pipelex kernel layer loads zero interpreter modules — the property, not the rule.-`pipelex-dev check-hub-layering` guards the *rule* (no runtime-layer module imports `pipelex.interpreter_hub`).+`pipelex-dev check-hub-layering` guards the *rule* (no kernel-layer module imports `pipelex.interpreter_hub`).This guards the *property* the rule exists to buy: importing the inference layer, or the runtime hubitself, must pull in zero interpreter modules. The distinction matters because a stray import somewhere-else entirely — a runtime-layer module reaching into `pipe_operators` directly, without touching a hub —+else entirely — a kernel-layer module reaching into `pipe_operators` directly, without touching a hub —would break the property while the lint stays green."Interpreter module" used to need spelling out twice, because core's Pipe-machinery modules were-interpreter-layer while living under a runtime-named package — so the predicate carried a second tuple-naming them one by one, plus an exclusion for the one leaf model that landed in every runtime closure.+interpreter-layer while living under a package declared kernel-layer — so the predicate carried a second tuple+naming them one by one, plus an exclusion for the one leaf model that landed in every kernel closure.It does not any more: every one of those modules now lives under `pipe_machinery` or `mthds_parsing`,so the top-level package set says exactly what it means, with no per-module list and no exclusion. Apackage-granular predicate is only honest once the packages match the layers, which is what M1 bought.The set below now names every interpreter package, with no exclusion and no qualification. `pipeline`and `pipe_run` were the last two absent, and their absence was a *placement* problem rather than a-broken hub arrow: four leaf models of theirs landed in every runtime closure, so naming them here+broken hub arrow: four leaf models of theirs landed in every kernel closure, so naming them herewould have failed every entry point over an address. The remedy was the one `mthds_parsing` used —-move the leaves to a runtime-layer home, then widen the predicate. `SpecialPipelineId` is now in+move the leaves to a kernel-layer home, then widen the predicate. `SpecialPipelineId` is now in`system.job_metadata` beside the `pipeline_run_id` it names, `PipeRunMode` and `PipeRunParamKey` are`system.pipe_run_mode` / `system.pipe_run_param_key`, and `PipeRunError` sits in-`core.pipes.exceptions` with the runtime-layer subclasses that derive from it. Moving the leaf is+`core.pipes.exceptions` with the kernel-layer subclasses that derive from it. Moving the leaf iswhat buys the clean predicate; excluding it would only have recorded the problem.Run in a subprocess so the closure is exactly what the entry point pulls in: an in-process@@ -39,16 +39,16 @@ from pathlib import Pathimport pytest#: Entry points that must never load the interpreter: the inference layer, the runtime hub itself, the-#: built-in plugin aggregator, and the heaviest module of each runtime-layer `core/` package — the ones+#: built-in plugin aggregator, and the heaviest module of each kernel-layer `core/` package — the ones#: that historically reached for a library and now take a `ConceptProviderAbstract` instead. There is no#: longer a Pipe-touching remainder of `core/` to leave out: all of it moved to `pipe_machinery` and#: `mthds_parsing`, which is what let `pipelex.core` be declared wholesale (see the guard's-#: `RUNTIME_LAYER_PACKAGES` note).+#: `KERNEL_LAYER_PACKAGES` note).#:#: `providers.builtins` earns its place by history, under its former name `plugins.builtins`: it and#: three neighbours reached `interpreter_hub` transitively — through `runtime_bridge`, `pipeline` and#: `pipe_operators` — while both gates stayed green, because the guard was one hop deep and-#: `pipelex.plugins`, the largest declared runtime-layer package, had no entry point here. The guard+#: `pipelex.plugins`, the largest declared kernel-layer package, had no entry point here. The guard#: now follows the import graph, but that is *static* analysis: it cannot see a dynamic import, so the#: package that bit us gets a runtime-truth check too. It instantiates every built-in vendor adapter,#: so importing it pulls in every one of them — the broadest single entry point into `pipelex.providers`,@@ -56,7 +56,7 @@ import pytest#: in `pipelex.plugins` and is reached from here, so one entry point still covers both halves.#:#: `providers.anthropic.anthropic_list` is here because `providers.builtins` turned out **not** to cover-#: it: the vendor plugins import their `*_list` modules inside a function (`# noqa: PLC0415`), so a+#: it: the vendor plugins import their `*_list` modules inside a function (under a `PLC0415` noqa), so a#: deferred import hides them from the static graph *and* from the aggregator's own closure. Five of#: them imported `MissingDependencyError` from the top-level `pipelex.exceptions` aggregate rather than#: from its definition site in `pipelex.system.exceptions`, and since that aggregate re-exports every@@ -78,7 +78,7 @@ import pytest#: Note the blind spot the kernel's own doctrine restates: this test sees module-level imports only,#: so a function-local import inside a kernel module is invisible to it *and* to the static graph at#: once. That is precisely the hole the boot-contract test's post-call sweep exists to close.-RUNTIME_LAYER_ENTRY_POINTS = [+KERNEL_LAYER_ENTRY_POINTS = ["pipelex.cogt.content_generation.content_generator","pipelex.runtime_hub","pipelex.runtime_boot",@@ -156,7 +156,7 @@ _CLOSURE_SCRIPT = textwrap.dedent(print(f"{target} loaded {len(offenders)} interpreter module(s): {offenders}")raise SystemExit(1)- # The interpreter hub must not be reachable from the runtime layer at all — the forbidden arrow, measured.+ # The interpreter hub must not be reachable from the kernel layer at all — the forbidden arrow, measured.if "pipelex.interpreter_hub" in sys.modules:print(f"{target} loaded pipelex.interpreter_hub")raise SystemExit(1)@@ -192,7 +192,7 @@ class TestHubImportClosure:@pytest.mark.parametrize(("entry_point", "expected_returncode"),[- *((entry_point, 0) for entry_point in RUNTIME_LAYER_ENTRY_POINTS),+ *((entry_point, 0) for entry_point in KERNEL_LAYER_ENTRY_POINTS),# The negative control: same detector, opposite verdict. See DIRTY_ENTRY_POINT above.(DIRTY_ENTRY_POINT, 1),],@@ -202,7 +202,7 @@ class TestHubImportClosure:assert result.returncode == expected_returncode, (f"unexpected hub import-closure verdict for {entry_point} (wanted exit {expected_returncode}).\n""Exit 0 means the entry point loaded no interpreter module; exit 1 means the detector found one. "- "A runtime-layer entry point failing is a real breach — see docs/contribute/hub-layering.md for how "+ "A kernel-layer entry point failing is a real breach — see docs/contribute/hub-layering.md for how ""to find the shortest import path to an offender. The dirty entry point passing instead means the ""detector has stopped detecting, and every other case above is now vacuous.\n"f"stdout={result.stdout}\nstderr={result.stderr}"diff --git a/tests/unit/pipelex/test_runtime_boot_closure.py b/tests/unit/pipelex/test_runtime_boot_closure.pyindex eab14441c..db2b303f2 100644--- a/tests/unit/pipelex/test_runtime_boot_closure.py+++ b/tests/unit/pipelex/test_runtime_boot_closure.py@@ -1,7 +1,7 @@-"""Booting the runtime layer loads zero interpreter modules — the boot-time half of the property.+"""Booting the kernel layer loads zero interpreter modules — the boot-time half of the property.-`pipelex-dev check-hub-layering` proves no runtime-layer *module* imports `interpreter_hub`, and-`test_runtime_layer_import_closure.py` proves the declared runtime-layer entry points *import* clean.+`pipelex-dev check-hub-layering` proves no kernel-layer *module* imports `interpreter_hub`, and+`test_kernel_layer_import_closure.py` proves the declared kernel-layer entry points *import* clean.Neither says anything about *booting*: until `RuntimeBoot` existed, the only composition root in thetree built an `InterpreterHub`, a `LibraryManager`, a `PipelineManager`, a `PipeRouter` and a`PipeRun` whether the caller would ever load a method or not.@@ -13,8 +13,8 @@ deliberately does not clear — so once anything in this process has booted a `Ppass vacuously. A fresh interpreter is the only place the question is answerable.It is also strictly stronger than the import-closure entry point it complements: that one *imports*-`pipelex.runtime_boot`, this one *runs* `RuntimeBoot.make()`. A runtime-only boot builds its plugin-registrar from `RUNTIME_BUILTIN_PLUGINS` alone, so `OrchestratorRegistry`, `BundleValidatorRegistry`+`pipelex.runtime_boot`, this one *runs* `RuntimeBoot.make()`. A kernel-only boot builds its plugin+registrar from `KERNEL_BUILTIN_PLUGINS` alone, so `OrchestratorRegistry`, `BundleValidatorRegistry`and the PipeFunc executor modes are all empty on it — an import-time check cannot notice a boot stepthat tries to resolve out of one of them."""@@ -23,14 +23,14 @@ import subprocess # noqa: S404import sysimport textwrap-from tests.unit.pipelex.test_runtime_layer_import_closure import INTERPRETER_PACKAGES+from tests.unit.pipelex.test_kernel_layer_import_closure import INTERPRETER_PACKAGES#: Wall-clock bound on the booted-runtime subprocess, matching the import-closure harness: a boot#: that deadlocks must present as a failure, not as a hung suite#: (`docs/agents/debugging-hanging-pytest-runs.md`).SUBPROCESS_TIMEOUT_SECONDS = 300-#: Boot the runtime layer in a fresh interpreter, then answer the three questions this module exists+#: Boot the kernel layer in a fresh interpreter, then answer the three questions this module exists#: to ask. `needs_inference=False` keeps it offline: no gateway terms gate, no model-deck validation.#: The `sys.modules` sweep runs *before* `pipelex.interpreter_hub` is imported for the hub assertion,#: so importing it to ask the question cannot be what makes the answer wrong.@@ -76,7 +76,7 @@ _BOOTED_RUNTIME_SCRIPT = textwrap.dedent(# The documented degradation: with no InterpreterHub installed, class-registry scoping stays at# its unscoped default rather than raising (docs/contribute/hub-layering.md).if class_registry_scoping.resolve() is not None:- print("class_registry_scoping resolved a scoped registry on a runtime-only boot")+ print("class_registry_scoping resolved a scoped registry on a kernel-only boot")raise SystemExit(1)print("runtime boot OK")@@ -101,7 +101,7 @@ CONTROL_PACKAGE_THE_RUNTIME_ALWAYS_LOADS = "cogt"def _run_booted_runtime(*, interpreter_packages: "tuple[str, ...]") -> subprocess.CompletedProcess[str]:- """Boot the runtime layer in a fresh interpreter and return the sweep's verdict."""+ """Boot the kernel layer in a fresh interpreter and return the sweep's verdict."""try:return subprocess.run( # noqa: S603[sys.executable, "-c", _BOOTED_RUNTIME_SCRIPT, *interpreter_packages],@@ -115,7 +115,7 @@ def _run_booted_runtime(*, interpreter_packages: "tuple[str, ...]") -> subprocesraise AssertionError(message) from exc-class TestBootedRuntimeLayer:+class TestBootedKernelLayer:def test_the_sweep_still_detects_a_package_the_runtime_boot_really_loads(self) -> None:"""The control: same script, opposite verdict. Without this, every other case is vacuous."""result = _run_booted_runtime(interpreter_packages=(CONTROL_PACKAGE_THE_RUNTIME_ALWAYS_LOADS,))@@ -129,10 +129,10 @@ class TestBootedRuntimeLayer:assert "interpreter module(s)" in result.stdoutassert "runtime boot OK" not in result.stdout- def test_booting_the_runtime_layer_loads_no_interpreter_module_and_installs_no_interpreter_hub(self) -> None:+ def test_booting_the_kernel_layer_loads_no_interpreter_module_and_installs_no_interpreter_hub(self) -> None:result = _run_booted_runtime(interpreter_packages=INTERPRETER_PACKAGES)assert result.returncode == 0, (- "booting the runtime layer must load zero interpreter modules and install no InterpreterHub.\n"+ "booting the kernel layer must load zero interpreter modules and install no InterpreterHub.\n""This is the boot-time half of the hub-layering property — see docs/contribute/hub-layering.md ""for how to find the shortest import path to an offender.\n"f"stdout={result.stdout}\nstderr={result.stderr}"diff --git a/wip/boot-split/README.md b/wip/boot-split/README.mdindex 005b9b5d6..7b7ca6014 100644--- a/wip/boot-split/README.md+++ b/wip/boot-split/README.md@@ -8,7 +8,7 @@ Every deferral note was raised by a review pass, verified against the source, an| Note | What it defers ||---|---|-| [`runtime-boot-external-interpreter-orchestrator.md`](runtime-boot-external-interpreter-orchestrator.md) | A runtime-only boot rejects an interpreter-layer orchestrator contributed by a *built-in*, but not one contributed by an *external* entry-point plugin — `build_registrar` discovers externals unconditionally. Every remedy needs a layer signal the runtime layer deliberately does not have. Cited from `runtime_boot.py`'s boot-orchestrator gate. |+| [`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. |diff --git a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md b/wip/boot-split/runtime-boot-external-interpreter-orchestrator.mdindex 903b220dd..cdfc75037 100644--- a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md+++ b/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md@@ -1,6 +1,6 @@# A runtime-only boot accepts an external interpreter-side orchestrator, then half-applies it-**Status:** deferred, deliberately. Found by Codex on PR #1073 (the boot split), verified real, not fixed there.+**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@@ -58,3 +58,16 @@ That check also subsumes the narrower orchestrator question: it catches *any* ex## What exists today insteadThe 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/kernel/README.md b/wip/kernel/README.mdindex a2c6e651e..b02a6057d 100644--- a/wip/kernel/README.md+++ b/wip/kernel/README.md@@ -6,3 +6,7 @@ Extraction of operator-execution semantics out of the interpreter's operator cla| --- | --- || [`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.mdnew file mode 100644index 000000000..353373b27--- /dev/null+++ b/wip/kernel/a2-pipelex-temporal-branch-question.md@@ -0,0 +1,33 @@+# 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.mdindex 39fff150e..d97d6984f 100644--- a/wip/kernel/deferred-follow-ups.md+++ b/wip/kernel/deferred-follow-ups.md@@ -206,3 +206,18 @@ The façade takes one explicit `model`, which wins `resolve_llm_setting_for_obje- **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.mdnew file mode 100644index 000000000..1c6220479--- /dev/null+++ b/wip/kernel/kernel-distribution-footprint.md@@ -0,0 +1,225 @@+# 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-plugin-groups-and-distribution-plan.md b/wip/kernel/kernel-plugin-groups-and-distribution-plan.mdnew file mode 100644index 000000000..33c454ba5--- /dev/null+++ b/wip/kernel/kernel-plugin-groups-and-distribution-plan.md@@ -0,0 +1,260 @@+# 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.mdnew file mode 100644index 000000000..82f73b4e9--- /dev/null+++ b/wip/kernel/plugin-group-split-deferred-items.md@@ -0,0 +1,109 @@+# 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.