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.
Consolidate (#1008)
Louis Choqueldee747ad0f33
diff --git a/.pipelex/pipelex.toml b/.pipelex/pipelex.tomlindex 75af5d268..3126ec3dc 100644--- a/.pipelex/pipelex.toml+++ b/.pipelex/pipelex.toml@@ -180,14 +180,6 @@ console_print_target = "stdout"# Log levels for specific packages (use "-" instead of "." in package names)pipelex = "INFO"-####################################################################################################-# Feature Config-####################################################################################################--[pipelex.feature_config]-# WIP/Experimental feature flags-is_reporting_enabled = true-##################################################################################################### Reporting Config####################################################################################################diff --git a/docs/advanced/index.md b/docs/advanced/index.mdindex 56e33ecaf..225473de9 100644--- a/docs/advanced/index.md+++ b/docs/advanced/index.md@@ -35,15 +35,6 @@ hub.set_reporting_delegate(MyReportingDelegate())# ... and so on for other components```-## NoOp Implementations--Some components have "NoOp" (No Operation) implementations that are used when the feature is disabled:--- `ReportingNoOp`: Used when reporting is disabled-- `ActivityManagerNoOp`: Used when activity tracking is disabled--These NoOp implementations implement the same protocol but do nothing, allowing the system to function without the specific feature.-## Protocol ComplianceAll custom implementations MUST:@@ -54,14 +45,6 @@ All custom implementations MUST:4. Handle errors appropriately5. Clean up resources when needed-## Feature Flags--Some components are controlled by feature flags in the configuration:--- `is_reporting_enabled`: Controls Reporting system--When a feature is disabled, the corresponding NoOp implementation is used automatically.-## Available Injectable ComponentsPipelex supports injection of the following components:@@ -69,7 +52,8 @@ Pipelex supports injection of the following components:**Reporting Delegate** (`ReportingManager`)- Protocol: `ReportingProtocol`-- Default: `ReportingManager` or `ReportingNoOp` if disabled+- Default: `ReportingManager`+- No-op option: inject `ReportingNoOp` to disable reporting explicitly- [Details](reporting-delegate-injection.md)**Secrets Provider** (`EnvSecretsProvider`)diff --git a/docs/configuration/config-advanced/feature-config.md b/docs/configuration/config-advanced/feature-config.mddeleted file mode 100644index 5f790cce7..000000000--- a/docs/configuration/config-advanced/feature-config.md+++ /dev/null@@ -1,51 +0,0 @@-----description: "Toggle Pipelex feature flags — enable or disable the reporting system and other optional capabilities through TOML configuration."------# Feature Configuration--The `FeatureConfig` class controls which features are enabled in Pipelex.--## Configuration Options--```python-class FeatureConfig(ConfigModel):- is_reporting_enabled: bool-```--### Fields--- `is_reporting_enabled`: When true, enables the reporting system--## Impact on Dependency Injection--The feature flags directly affect which implementation is used for certain components:--| Feature Flag | When True | When False |-|--------------|-----------|------------|-| `is_reporting_enabled` | `ReportingManager` | `ReportingNoOp` |--## Feature Details--### Reporting--```toml-is_reporting_enabled = true-```--- Controls whether reporting functionality is enabled-- When enabled, generates the cost report of the pipelex execution (LLM costs, OCR costs, etc...)-- Default: `true`--## Example Configuration--```toml-[pipelex.feature_config]-# Enable reporting for cost monitoring-is_reporting_enabled = true-```--## Related Documentation--- [Cost Tracking](../../features/cost-tracking.md) - Track and monitor AI usage costs-- [Reporting Config](../config-practical/reporting-config.md) - Detailed reporting configuration optionsdiff --git a/docs/features/configuration.md b/docs/features/configuration.mdindex 07067f3f2..ffe5b3b4c 100644--- a/docs/features/configuration.md+++ b/docs/features/configuration.md@@ -32,6 +32,5 @@ Use `${VAR_NAME}` syntax in TOML files for dynamic configuration from environmen- **[Telemetry](../configuration/config-practical/telemetry-config.md)** — Observability settings- **[Reporting](../configuration/config-practical/reporting-config.md)** — Cost tracking and reports- **[Dry Run](../configuration/config-pipeline-validation/dry-run-config.md)** — Mock generation settings-- **[Features](../configuration/config-advanced/feature-config.md)** — Feature flagsFor full configuration reference, see [Configuration](../configuration/index.md).diff --git a/mkdocs.yml b/mkdocs.ymlindex 11315311c..0db0e4f8b 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -147,7 +147,6 @@ plugins:'home/6-build-reliable-ai-workflows/pipes/provide-inputs.md': 'building-methods/pipes/provide-inputs.md''home/6-build-reliable-ai-workflows/pipes/understanding-multiplicity.md': 'building-methods/pipes/understanding-multiplicity.md''home/6-build-reliable-ai-workflows/pipes/working-memory.md': 'building-methods/pipes/working-memory.md'- 'home/7-configuration/config-advanced/feature-config.md': 'configuration/config-advanced/feature-config.md''home/7-configuration/config-pipeline-validation/dry-run-config.md': 'configuration/config-pipeline-validation/dry-run-config.md''home/7-configuration/config-practical/logging-config.md': 'configuration/config-practical/logging-config.md''home/7-configuration/config-practical/pipe-run-config.md': 'configuration/config-practical/pipe-run-config.md'@@ -290,7 +289,6 @@ plugins:- configuration/config-technical/cogt-config.md: "Cogt Configuration"- configuration/config-technical/inference-backend-config.md: "LLM Providers & Models Configuration"- configuration/config-technical/library-config.md: "Library Configuration"- - configuration/config-advanced/feature-config.md: "Feature Configuration"- tools/plxt.md: "plxt (Formatter & Linter)"- tools/logging.md: "Logging"- analytics/data-extraction.md: "Observer Data Extraction"@@ -526,7 +524,6 @@ nav:- Cogt: configuration/config-technical/cogt-config.md- LLM Providers & Models: configuration/config-technical/inference-backend-config.md- Library: configuration/config-technical/library-config.md- - Feature: configuration/config-advanced/feature-config.md- Advanced:- Advanced Customizations:- Overview: advanced/index.mddiff --git a/pipelex/core/interpreter/interpreter.py b/pipelex/core/interpreter/interpreter.pyindex 3ae86dc1e..213aba817 100644--- a/pipelex/core/interpreter/interpreter.py+++ b/pipelex/core/interpreter/interpreter.py@@ -1,8 +1,9 @@from pathlib import Path-from typing import TYPE_CHECKING, Any+from typing import Anyfrom pydantic import BaseModel, ValidationError+from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorDatafrom pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprintfrom pipelex.core.interpreter.bundle_elaborator import BundleElaboratorfrom pipelex.core.interpreter.exceptions import BundleElaboratorError, PipelexInterpreterError@@ -11,9 +12,6 @@ from pipelex.tools.misc.exceptions import TomlErrorfrom pipelex.tools.misc.toml_utils import load_toml_from_content, load_toml_from_pathfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error-if TYPE_CHECKING:- from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData-class PipelexInterpreter(BaseModel):"""MTHDS -> PipelexBundleBlueprint"""@@ -56,7 +54,16 @@ class PipelexInterpreter(BaseModel):raise PipelexInterpreterError(msg)except TomlError as exc:msg = f"TOML syntax error at line {exc.lineno}, column {exc.colno}: {exc.message}"- raise PipelexInterpreterError(msg) from exc+ source = str(bundle_path) if bundle_path is not None else mthds_source+ raise PipelexInterpreterError(+ msg,+ validation_errors=[+ PipelexBundleBlueprintValidationErrorData(+ source=source,+ message=msg,+ )+ ],+ ) from excif not blueprint_dict:msg = "Could not make 'PipelexBundleBlueprint': no blueprint found in the MTHDS file"diff --git a/pipelex/kit/configs/pipelex.toml b/pipelex/kit/configs/pipelex.tomlindex 75af5d268..3126ec3dc 100644--- a/pipelex/kit/configs/pipelex.toml+++ b/pipelex/kit/configs/pipelex.toml@@ -180,14 +180,6 @@ console_print_target = "stdout"# Log levels for specific packages (use "-" instead of "." in package names)pipelex = "INFO"-####################################################################################################-# Feature Config-####################################################################################################--[pipelex.feature_config]-# WIP/Experimental feature flags-is_reporting_enabled = true-##################################################################################################### Reporting Config####################################################################################################diff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex d868b6cb4..654ad2ab3 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -56,7 +56,7 @@ from pipelex.plugins.orchestrator_registry import OrchestratorRegistryfrom pipelex.plugins.registrar import HubSlot, PluginRegistrarfrom pipelex.plugins.sdk_client_manager import SdkClientManagerfrom pipelex.reporting.reporting_manager import ReportingManager-from pipelex.reporting.reporting_protocol import ReportingNoOp, ReportingProtocol+from pipelex.reporting.reporting_protocol import ReportingProtocolfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.config_root import ConfigRootfrom pipelex.system.configuration.configs import PipelexConfig@@ -412,10 +412,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# --- Libraries & Registries -------------------------------------------------------------- if get_config().pipelex.feature_config.is_reporting_enabled:- self.reporting_delegate = reporting_delegate or ReportingManager()- else:- self.reporting_delegate = ReportingNoOp()+ self.reporting_delegate = reporting_delegate or ReportingManager()self.pipelex_hub.set_report_delegate(self.reporting_delegate)self.reporting_delegate.setup()diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.tomlindex a2e199ae7..84398c551 100644--- a/pipelex/pipelex.toml+++ b/pipelex/pipelex.toml@@ -52,10 +52,6 @@ default_output_dir = "."default_bundle_file_name = "bundle"default_directory_base_name = "pipeline"-[pipelex.feature_config]-# WIP/Experimental feature flags-is_reporting_enabled = true-[pipelex.reporting_config]is_log_costs_to_console = trueis_generate_cost_report_file_enabled = falsediff --git a/pipelex/reporting/reporting_protocol.py b/pipelex/reporting/reporting_protocol.pyindex 3718caa34..87baa0403 100644--- a/pipelex/reporting/reporting_protocol.py+++ b/pipelex/reporting/reporting_protocol.py@@ -27,15 +27,15 @@ class ReportingProtocol(Protocol):class ReportingNoOp(ReportingProtocol):@override- def report_inference_job(self, inference_job: InferenceJobAbstract):+ def report_inference_job(self, inference_job: InferenceJobAbstract) -> None:pass@override- def setup(self):+ def setup(self) -> None:pass@override- def teardown(self):+ def teardown(self) -> None:pass@overridediff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.pyindex 419b5198b..7e55f9c2e 100644--- a/pipelex/system/configuration/configs.py+++ b/pipelex/system/configuration/configs.py@@ -85,10 +85,6 @@ class PromptingConfig(ConfigModel):return None-class FeatureConfig(ConfigModel):- is_reporting_enabled: bool--class ReportingConfig(ConfigModel):is_log_costs_to_console: boolis_generate_cost_report_file_enabled: bool@@ -209,7 +205,6 @@ class PipelineExecutionConfig(ConfigModel):class Pipelex(ConfigModel):storage_config: StorageConfig- feature_config: FeatureConfiglog_config: LogConfigaws_config: AwsConfigdiff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.pyindex c0b3ed26f..f15fcdabf 100644--- a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py@@ -37,8 +37,8 @@ description = "A customer""""# An unclosed table header is a TOML *syntax* error: it fails in the interpreter before any-# blueprint dict exists, so the ``PipelexInterpreterError`` carries only a message — no-# categorized error data and (crucially) no chance to seed the threaded ``source``.+# blueprint dict exists, so the interpreter must attach the threaded source directly to the+# structured error item._MALFORMED_TOML_MTHDS = """domain = "testapp"[concept.Customer@@ -85,19 +85,16 @@ class TestValidateBundleSourceThreading:assert seeded_items, "no validation_errors item carried the threaded source"assert any(item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in seeded_items)- async def test_parse_level_failure_yields_a_sourceless_residual_item(+ async def test_parse_level_failure_carries_threaded_source(self,load_empty_library: Callable[[], str],) -> None:- """A TOML-syntax error still surfaces a non-empty ``validation_errors`` — the invariant is total.-- Parse-level failures (TOML syntax, an empty blueprint, a bundle elaborator) are raised by- the interpreter with only a message — no per-error data, and (since they fail before the- blueprint dict is seeded) no threaded ``source``. The shared builder's last-resort residual- still emits one ``blueprint_validation`` item, so an invalid verdict never rides a bare- message with an empty ``validation_errors[]``. Being parse-level, the residual carries no- ``source`` — even though one was threaded in — which this contrasts against the categorized- cases above.+ """A TOML-syntax error surfaces a blueprint-validation item with the threaded source.++ Parse-level failures happen before a ``PipelexBundleBlueprint`` exists, so they cannot read+ ``blueprint.source``. The interpreter must attach the caller-supplied logical source directly+ to the structured blueprint-validation item; otherwise API/MCP clients receive an error+ message they cannot map back to the submitted file."""load_empty_library()with pytest.raises(ValidateBundleError) as exc_info:@@ -105,7 +102,7 @@ class TestValidateBundleSourceThreading:report = exc_info.value.to_error_report()assert report.validation_errors, "a parse-level failure must still carry a non-empty validation_errors[]"assert all(item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in report.validation_errors)- assert all(item.source is None for item in report.validation_errors)+ assert [item.source for item in report.validation_errors] == ["broken.mthds"]async def test_length_mismatch_is_a_host_contract_error(self,diff --git a/tests/pipelex_unit_test.toml b/tests/pipelex_unit_test.tomlindex 08017527c..f39e6446b 100644--- a/tests/pipelex_unit_test.toml+++ b/tests/pipelex_unit_test.toml@@ -5,7 +5,3 @@ method = "local"[cogt.model_deck_config]# Allow tests to run with restrictive routing profiles that don't support all presetsmissing_presets_reaction = "none"--[pipelex.feature_config]-# Enable reporting manager so that it can be tested-is_reporting_enabled = truediff --git a/tests/unit/pipelex/core/interpreter/test_interpreter.py b/tests/unit/pipelex/core/interpreter/test_interpreter.pyindex 4297537b1..c8b27b5c1 100644--- a/tests/unit/pipelex/core/interpreter/test_interpreter.py+++ b/tests/unit/pipelex/core/interpreter/test_interpreter.py@@ -2,6 +2,7 @@ import pytestfrom pipelex import log, pretty_printfrom pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint+from pipelex.core.interpreter.exceptions import PipelexInterpreterErrorfrom pipelex.core.interpreter.interpreter import PipelexInterpreterfrom tests.unit.pipelex.core.test_data import InterpreterTestCases@@ -22,3 +23,17 @@ class TestPipelexInterpreter:log.verbose(f"Testing invalid MTHDS content: {test_name}")with pytest.raises(expected_exception):PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=invalid_mthds_content)++ def test_toml_syntax_error_carries_mthds_source(self):+ """Parse-level errors must still expose the caller-supplied logical source."""+ with pytest.raises(PipelexInterpreterError) as exc_info:+ PipelexInterpreter.make_pipelex_bundle_blueprint(+ mthds_content='domain = "broken" trailing',+ mthds_source="broken.mthds",+ )++ err = exc_info.value+ assert err.validation_errors is not None+ assert len(err.validation_errors) == 1+ assert err.validation_errors[0].source == "broken.mthds"+ assert "TOML syntax error" in err.validation_errors[0].messagediff --git a/wip/README.md b/wip/README.mdindex f3d66bac8..bb8d42612 100644--- a/wip/README.md+++ b/wip/README.md@@ -1,42 +1,43 @@-# `wip/` — Work in Progress--This folder holds the **active** planning, design, and current-state docs for the Pipelex runtime — the things that are started or about to start. Finished plans and design history live in the private workspace (`docs/history/`, `docs/plans/`), not here. If a doc describes how the code got to where it is rather than where it is or is going, it does not belong in `wip/`.--## How this is organized--- **Track folders** group a multi-doc concern. Each has its own `README.md` that maps the track and states what's open. Open the README first.-- **Standalone docs** are single-topic designs that have no siblings — they live loose at the root with self-describing names (no folder needed).-- There is **no consolidated cross-cutting backlog** — deferred items and follow-ups live with their feature, in the relevant track or standalone doc's own "open / deferred" section. Follow-ups to features that already shipped live with that feature's record in the private workspace (`docs/history/`, `docs/plans/`), not here.--## Tracks--- **[distributed-execution/](distributed-execution/)** — running MTHDS methods as Temporal workflows across separate worker processes. Its [README](distributed-execution/README.md) is the priority-ordered plan; the folder also holds the tracing/cost-reporting as-built reference, the crate-packaging phases (6a/6b) and crate-first vision, the implemented Temporal IDs/naming design, the deferred Temporal-exception and schema-reconstruction hardening proposals, the `/temporal-e2e-validate` skill validation status, and the [mistral-workflows/](distributed-execution/mistral-workflows/) sub-track (landing the MISTRAL_NATIVE plugin onto `dev`). **This is the active headline track.**-- **[error-handling/](error-handling/)** — the current-state reference for error handling across Pipelex, track-organized (metadata model, worker classification, extract/classify/render, retry, CLI delivery, Temporal integration, testing). Mostly landed; its [README](error-handling/README.md) lists what's still open.-- **[concurrency/](concurrency/)** — direct-mode batching / backpressure design. The retry-jitter quick win shipped; the remaining design work is split into fan-out scheduling, rate limiting, and batch partial-failure docs. Status: design scoping.-- **[csv-support/](csv-support/)** — reading `.csv` files into typed `ListContent` and writing flat list outputs back out via `--save-csv`. Its [README](csv-support/README.md) is the feature + reviewer reference (codec, core input hook, CLI output hook, the I/O contract, locked decisions); the folder also holds the design rationale and the deferred review/security follow-ups. Landed in #955.-- **[runtime-bridge/](runtime-bridge/)** — review-triage and deferred-items record for the framework-agnostic `pipelex/runtime_bridge/` extraction (`feature/Runtime-bridge-extraction`, PR #969). Its [README](runtime-bridge/README.md) is the full triage of the SWE-agent review comments. The mechanical fixes and the design-fork resolutions (DIRECT-mode router scoping, the `graph_context`→`trace_context` contract, trace-flush false-positive) have all landed; what remains are the genuinely-deferred items, each with its own doc — notably the half-built-singleton boot race.-- **[keyword-only-arguments/](keyword-only-arguments/)** — the keyword-only-arguments refactor on `refactor/Function-calling-4`: every non-subject parameter across `pipelex/` is keyword-only, enforced by the `check-keyword-only` AST guard (in `agent-check` + CI) and a `PostToolUse` hook. Its [README](keyword-only-arguments/README.md) maps the track; the folder also holds the co-developer [HTML explainer](keyword-only-arguments/keyword-only-arguments.html), the resolved positional-subject-suspects record, the cross-repo downstream-breakage log, and the raw `audit/` artifacts. Landed on the branch; the one open item is the at-release pin swap for the four consumer repos.--## Standalone docs--- **[signature-based-validation.md](signature-based-validation/signature-based-validation.md)** — `PipeSignature` contract-only pipes plus strict/lenient (`--allow-signatures`) validation, on `feature/Validate-with-signatures-3`. Landed (Phases 1–7.3, tests green); current-state reference + reviewer verification map. The one open item is the Phase 7.4 cross-repo schema merge-gate (retire the branch-local MTHDS schema rule once `vscode-pipelex` ships the bundled schema).-- **[webhook-signing.md](webhook-signing.md)** — security track: HMAC body-signing for the completion-callback webhook, with a 3-step cross-repo rollout. The last open piece of the error-handling API-readiness companion work. Plan ready, not started.-- **[runtime-code-fixes.md](runtime-code-fixes.md)** — verified `pipelex/` runtime fixes to pick up.-- **[structured-logging.md](structured-logging.md)** — kickoff briefing for replacing string-interpolated log context with structured logging + contextvars. Kicked off, not started; sequenced after the error-handling stack merges.-- **[stuffs-as-nodespec.md](stuffs-as-nodespec.md)** — future graph-model rework to make stuffs first-class `NodeSpec` instances. A starter, not a worked plan.-- **[blueprint-elaboration-directives.md](blueprint-elaboration-directives.md)** — extending the build-time blueprint-elaboration system: first-class synthetic-pipe handling, a directive plugin registry, and supporting tooling.-- **[doctor-output-ansi-under-force-color.md](doctor-output-ansi-under-force-color.md)** — deferred decision: `pipelex doctor` emits ANSI when captured under `FORCE_COLOR` (an env artifact, not a pipelex defect — it's plain when piped without it). Records the evidence and the one optional follow-up (a `--plain`/`--no-color` flag for diagnostics). Low priority. Surfaced by pipelex-worker PR #23.-- **[structured-validation-errors-deferred-findings.md](structured-validation-errors-deferred-findings.md)** — lower-severity code-review follow-ups on the structured wiring/concept/type `validation_errors[]` work (`feature/Validate-api-render-format`): the missing-`type` (`union_tag_not_found`) categorization gap, dependency-validation fail-fast vs. concept-ref accumulation, qualified same-domain `concept_code`, the source-less `unresolved_pipe_dependency` item, a duplicate-message cleanup, and the `concept_code`-meaning trade-off baked in by the concept-owned fix. All low priority; each a contained pickup.-- **[pathlib-refactor.workflow.js](pathlib-refactor.workflow.js)** — a runnable multi-agent workflow that refactors filesystem path handling to `pathlib.Path` across `pipelex/` (intended for the `refactor/Paths` branch). Tooling, not a doc.--## Suggested priorities--A pickup order grounded in each doc's own status — adjust to current signals.--1. **[runtime-code-fixes.md](runtime-code-fixes.md)** — smallest and already verified. The `request_id`-on-delivery-failure fix is a quick win; the cross-worker cost-report assembly wiring is the one genuine functional gap (it is also **P1** of the distributed-execution track).-2. **[distributed-execution/](distributed-execution/)** — the active headline track. Take P1 (cross-worker cost report assembly) first, then the crate phases P2 (local cross-package deps) → P3 (remote deps).-3. **[webhook-signing.md](webhook-signing.md)** — security-reviewed plan, ready to execute; closes the last open error-handling-companion item. Cross-repo, so coordinate the rollout.-4. **error-handling long tail** — the metadata-model followups and the `request_id` correlation on delivery error paths in [error-handling/](error-handling/). Mostly landed; these are the remainder.-5. **[concurrency/](concurrency/)** — pick up when batch-at-scale becomes a priority. Fan-out scheduling and batch partial-failure are coupled (take together); rate limiting is independent.-6. **[runtime-bridge/](runtime-bridge/)** — tracks PR #969 (in review). The mechanical fixes and design-fork resolutions have landed; the remaining deferred items (notably the half-built-singleton boot-race hardening) can wait for a human decision.-7. **Deferred / larger / future** — [structured-logging.md](structured-logging.md) (after error-handling merges), [pathlib-refactor.workflow.js](pathlib-refactor.workflow.js) (run when ready), [stuffs-as-nodespec.md](stuffs-as-nodespec.md), the deferred Temporal-exception and schema-reconstruction proposals in [distributed-execution/](distributed-execution/), and [blueprint-elaboration-directives.md](blueprint-elaboration-directives.md). Take individually as needs and signals dictate.+# `wip/` - Work in Progress++This folder holds active planning, design, and current-state docs for Pipelex runtime work. Finished plans, point-in-time PR recaps, and old audit artifacts are collected under [`history/`](history/).++Start with [`executive.md`](executive.md) for priorities. Then open the track README for the area you are picking up.++## Active Tracks++- [`plugins/`](plugins/) - real plugin architecture for orchestrators and inference backends. This is the major architecture track: entry-point discovery, registries, orchestrator dispatch, Temporal extraction, version gating, and cutover follow-ups.+- [`distributed-execution/`](distributed-execution/) - Temporal/distributed execution productionization. P0/P1 tracing and cost reporting shipped; open work is P0.2 follow-ons, local cross-package crates, remote dependency fetch, nondeterminism decisions, and MISTRAL_NATIVE downstream reconciliation.+- [`dry-run-refactor/`](dry-run-refactor/) - unified dry-run and validation execution. Part A shipped, Part B/unified dry run is implemented, and Part C needs release/API merge and hardening decisions.+- [`error-handling/`](error-handling/) - current-state reference and open tail for structured errors: webhook signing, metadata long tail, delivery-path request ids, and Temporal fail-safe review backlog.+- [`runtime-bridge/`](runtime-bridge/) - runtime bridge review/deferred follow-ups. Most PR review items are resolved; active value is in remaining deferred hardening and testing gaps.+- [`concurrency/`](concurrency/) - direct-mode batching/backpressure design: fan-out scheduling, rate limiting, and batch partial failure.+- [`graph/`](graph/) - graph/validation graph improvements: source-map enrichment and explicit graph target selection.+- [`observer-and-telemetry/`](observer-and-telemetry/) - telemetry/identifier visibility notes, especially hosted privacy around structural ids.+- [`recursivity/`](recursivity/) - only low-priority additive multi-file polish remains active; completed recursivity records are in history.++## Active Standalone Docs++- [`webhook-signing.md`](webhook-signing.md) - HMAC body-signing rollout for completion webhooks.+- [`init-yes-mode-handoff.md`](init-yes-mode-handoff.md) - non-interactive `pipelex init --yes` for downstream CI.+- [`structured-logging.md`](structured-logging.md) - structured log fields and contextvars.+- [`runtime-code-fixes.md`](runtime-code-fixes.md) - verified runtime fixes to pick up.+- [`structured-validation-errors-deferred-findings.md`](structured-validation-errors-deferred-findings.md) - contained follow-ups on structured validation errors.+- [`validate-parse-level-source-attribution.md`](validate-parse-level-source-attribution.md) - source attribution for malformed TOML in multi-file validation.+- [`blueprint-elaboration-directives.md`](blueprint-elaboration-directives.md) - future elaboration directive system.+- [`stuffs-as-nodespec.md`](stuffs-as-nodespec.md) - future graph model rework for stuff nodes.+- [`doctor-output-ansi-under-force-color.md`](doctor-output-ansi-under-force-color.md) - optional plain diagnostic output decision.+- [`pathlib-refactor.workflow.js`](pathlib-refactor.workflow.js) - runnable path-refactor workflow.++## History++[`history/`](history/) now holds shipped or reference-only material moved out of the active surface:++- CSV support+- keyword-only arguments+- signature-based validation+- cost-reporting registry work+- completed test-grind notes+- completed recursivity handoffs+- old `archive/` records+- point-in-time HTML recapsdiff --git a/wip/distributed-execution/README.md b/wip/distributed-execution/README.mdindex 479ee2041..2981879c2 100644--- a/wip/distributed-execution/README.md+++ b/wip/distributed-execution/README.md@@ -36,7 +36,7 @@ This folder is the **distributed-execution track**: running MTHDS methods as Tem| **P2** | Local cross-package dependencies in the crate | [local-cross-package-deps.md](local-cross-package-deps.md) || **P3** | Remote dependencies from GitHub | needs P2 — [remote-deps-from-github.md](remote-deps-from-github.md) |-P0/P0.1/P0.2/P1 formed one chain (P0 unlocked the rest); **P0, P0.1, and P1 are now shipped** (see [the registry tracker](../registry/README.md) for the as-built sequencing). P0.2 is still open (independent follow-ons). P2/P3 are an independent chain (P2 blocks P3). [tracing-cost-reporting.md](tracing-cost-reporting.md) carries the as-built design; T1 and T2 are fixed, T3 (request-scoped tracing state) remains open.+P0/P0.1/P0.2/P1 formed one chain (P0 unlocked the rest); **P0, P0.1, and P1 are now shipped** (see [the registry tracker](../history/registry/README.md) for the as-built sequencing). P0.2 is still open (independent follow-ons). P2/P3 are an independent chain (P2 blocks P3). [tracing-cost-reporting.md](tracing-cost-reporting.md) carries the as-built design; T1 and T2 are fixed, T3 (request-scoped tracing state) remains open.Sibling track (separate branch, not in this plan): the error-handling work — see [`error-handling/README.md`](../error-handling/README.md).@@ -58,7 +58,7 @@ As built:- The synthetic usage is **reportable non-zero** (`MOCK_INFERENCE_NB_TOKENS_BY_CATEGORY = {INPUT: 100, OUTPUT: 50}`, model `mock_inference`) — distinct from `--dry-run`'s zero-token, suppressed usage — so the cross-worker cost report actually renders. This is the durable reason `--mock-inference` ≠ `--dry-run` at the reporting layer.- `temporal-e2e-validate` Tier 8b runs in this mode and surfaces `wf_*__w_act_*.ndjson` + a rendered cost report deterministically.-**Scope deviations (deliberate):** the leaf mock covers the **LLM leaf only**; image-gen / extract / search under `--mock-inference` fail loud with `MockInferenceUnsupportedError` (their output is stored *above* the leaf, so a leaf mock would push synthetic data through storage). `--mock-inference` is on the main `run` subcommands only (not the agent CLI). Full per-operator coverage and the eventual `is_mock_inference → run_mode=DRY` re-keying are tracked in [`../dry-run-refactor/followup-leaf-run-mode-mock.md`](../dry-run-refactor/followup-leaf-run-mode-mock.md) (B2). See [the registry feature](../registry/README.md) and its [`cost-reporting-overview.html`](../registry/cost-reporting-overview.html) for the full as-built.+**Scope deviations (deliberate):** the leaf mock covers the **LLM leaf only**; image-gen / extract / search under `--mock-inference` fail loud with `MockInferenceUnsupportedError` (their output is stored *above* the leaf, so a leaf mock would push synthetic data through storage). `--mock-inference` is on the main `run` subcommands only (not the agent CLI). Full per-operator coverage and the eventual `is_mock_inference → run_mode=DRY` re-keying are tracked in [`../dry-run-refactor/followup-leaf-run-mode-mock.md`](../dry-run-refactor/followup-leaf-run-mode-mock.md) (B2). See [the registry feature](../history/registry/README.md) and its [`cost-reporting-overview.html`](../history/registry/cost-reporting-overview.html) for the full as-built.---@@ -76,7 +76,7 @@ Each is independently scoped and not blocking. Pick up individually as signals d## P1 — Cross-worker cost report assembly — DONE-Shipped via **Option B** (the locked design; see [the registry overview](../registry/cost-reporting-overview.html)): rather than wire `read events → inject_tokens_usages → generate_report` onto the process-singleton manager, usage rides on `PipeOutput` exactly like the graph spec, and the submitter renders the report from that field. This resolved P1 **and** the `UsageRegistry` success-path leak in one move — with nothing populating a submitter-side registry, the registry was removed outright.+Shipped via **Option B** (the locked design; see [the registry overview](../history/registry/cost-reporting-overview.html)): rather than wire `read events → inject_tokens_usages → generate_report` onto the process-singleton manager, usage rides on `PipeOutput` exactly like the graph spec, and the submitter renders the report from that field. This resolved P1 **and** the `UsageRegistry` success-path leak in one move — with nothing populating a submitter-side registry, the registry was removed outright.As built:@@ -85,7 +85,7 @@ As built:- A dedicated `--costs` / `is_generate_costs` switch (default on) gates usage events + `UsageAggregator` over the shared event-log transport, independent of `--graph`.- Retired: `ReportingManager.inject_tokens_usages` / `generate_report` / `open_registry` / `close_registry`, the `UsageRegistry` model, and the local-only registry fallback (`_get_registry_strict` / `_try_add_to_registry`) are all gone.-Cross-worker case verified without spend: parent + child + activity usage aggregates into one end-of-run cost report — `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py`, `test_mock_inference_temporal.py`, and the `temporal-e2e-validate` skill's Tier 8b. The full phased as-built is in [the registry tracker](../registry/README.md).+Cross-worker case verified without spend: parent + child + activity usage aggregates into one end-of-run cost report — `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py`, `test_mock_inference_temporal.py`, and the `temporal-e2e-validate` skill's Tier 8b. The full phased as-built is in [the registry tracker](../history/registry/README.md).---diff --git a/wip/distributed-execution/tracing-cost-reporting.md b/wip/distributed-execution/tracing-cost-reporting.mdindex b20147189..08c52f859 100644--- a/wip/distributed-execution/tracing-cost-reporting.md+++ b/wip/distributed-execution/tracing-cost-reporting.md@@ -2,7 +2,7 @@> **Status**: Shipped — the current tracing & cost-reporting implementation (supersedes an earlier distributed-tracing design, now retired). T1 **and** T2 are now fixed; cross-worker cost reporting works end to end.> **Last updated**: 2026-06-07-> **Related**: [the distributed-execution plan](README.md), [the registry overview](../registry/cost-reporting-overview.html), and [the registry feature](../registry/README.md).+> **Related**: [the distributed-execution plan](README.md), [the registry overview](../history/registry/cost-reporting-overview.html), and [the registry feature](../history/registry/README.md).This file documents what actually shipped, plus the known gaps that the plan addresses.@@ -54,7 +54,7 @@ The known retry-related over-counting case (R2) is documented and pinned by `tes**Status**: Resolved. Usage now rides on `PipeOutput` exactly like the graph spec, and the submitter renders the cost report from that field — so a cross-worker run produces a single, complete report.-> **Design note (as resolved):** T2/P1 was the same lifecycle as the `UsageRegistry` success-path leak — the leak was the missing *close*, T2 was the missing *replay-populate*, of one per-run cost-aggregation buffer. **Option B (locked) resolved both by removal:** usage is assembled from the trace-event stream at the end of the run and rides back on `PipeOutput.tokens_usages`; with nothing populating a submitter-side registry, the registry was deleted and the leak became structurally impossible. The unified model and the locked decision are explained in [the registry overview](../registry/cost-reporting-overview.html); the feature index is [`../registry/README.md`](../registry/README.md).+> **Design note (as resolved):** T2/P1 was the same lifecycle as the `UsageRegistry` success-path leak — the leak was the missing *close*, T2 was the missing *replay-populate*, of one per-run cost-aggregation buffer. **Option B (locked) resolved both by removal:** usage is assembled from the trace-event stream at the end of the run and rides back on `PipeOutput.tokens_usages`; with nothing populating a submitter-side registry, the registry was deleted and the leak became structurally impossible. The unified model and the locked decision are explained in [the registry overview](../history/registry/cost-reporting-overview.html); the feature index is [`../history/registry/README.md`](../history/registry/README.md).**As built:**@@ -79,7 +79,7 @@ Net effect: usage events emitted by runner/worker processes are now aggregated i- T1 was the **top priority** in the [distributed-execution plan](README.md) — resolved.- T2 is **resolved** — usage rides on `PipeOutput` (assembled from the same event read as the graph spec) and the submitter renders one cross-worker report. The wiring chosen was *not* `read events → inject_tokens_usages → generate_report` but the leaner Option B: `read events → UsageAggregator → PipeOutput.tokens_usages → CostRegistry.generate_report(tokens_usages=...)`, which let the submitter-side registry be deleted outright.-- T3 is the architectural shape; the T1 fix mitigated the immediate impact and T2's removal of the submitter-side registry shrank the singleton's surface further. The deeper "request-scoped tracing state instead of process-singleton" refactor remains the open follow-up (see Deferred / [the registry tracker](../registry/README.md)).+- T3 is the architectural shape; the T1 fix mitigated the immediate impact and T2's removal of the submitter-side registry shrank the singleton's surface further. The deeper "request-scoped tracing state instead of process-singleton" refactor remains the open follow-up (see Deferred / [the registry tracker](../history/registry/README.md)).---diff --git a/wip/dry-run-refactor/README.md b/wip/dry-run-refactor/README.mdindex e43b0fe45..f40e56c55 100644--- a/wip/dry-run-refactor/README.md+++ b/wip/dry-run-refactor/README.md@@ -6,7 +6,7 @@ The work is framed as three parts (D-plan **A/B/C**). **Part A — the in-proces- **What exists now** → [`consolidation-as-built.md`](./consolidation-as-built.md) (the as-built architecture + the decisions that hold).- **Why it's shaped this way + the full Part B/C design** → [`D-plan.md`](./D-plan.md) (the design source).-- **Rendered PR recap** → [`PR-bundle-validator.html`](./PR-bundle-validator.html) (a point-in-time snapshot of the consolidation PR).+- **Rendered PR recap** → [`../history/PR-bundle-validator.html`](../history/PR-bundle-validator.html) (a point-in-time snapshot of the consolidation PR).---diff --git a/wip/dry-run-refactor/design-unified-dry-run.md b/wip/dry-run-refactor/design-unified-dry-run.mdindex 3c5a6f61b..b64326e87 100644--- a/wip/dry-run-refactor/design-unified-dry-run.md+++ b/wip/dry-run-refactor/design-unified-dry-run.md@@ -1,6 +1,6 @@# Design — Unified dry run (retire `is_mock_inference` as a mode; add internal `is_mock_usage` flag)-> **Status: IMPLEMENTED (2026-06-10) — see [`plan-unified-dry-run.md`](./plan-unified-dry-run.md) for the plan and as-built record.** Design agreed with the user (2026-06-10). This design **supersedes eng-review decision D8** of [`followup-leaf-run-mode-mock.md`](./followup-leaf-run-mode-mock.md) ("is_mock_inference KEPT as thin reportable-mock"): the *mode* is retired; the *capability* (non-zero synthetic usage) survives as a secondary flag on dry run. It also resolves the "fate of `is_mock_inference`" item tracked in `wip/registry/deferred-followups.md`.+> **Status: IMPLEMENTED (2026-06-10) — see [`plan-unified-dry-run.md`](./plan-unified-dry-run.md) for the plan and as-built record.** Design agreed with the user (2026-06-10). This design **supersedes eng-review decision D8** of [`followup-leaf-run-mode-mock.md`](./followup-leaf-run-mode-mock.md) ("is_mock_inference KEPT as thin reportable-mock"): the *mode* is retired; the *capability* (non-zero synthetic usage) survives as a secondary flag on dry run. It also resolves the "fate of `is_mock_inference`" item tracked in [`../history/registry/deferred-followups.md`](../history/registry/deferred-followups.md).>> **Baseline:** the as-built state of `feature/Mock-activities` (PR #983, Part B complete through Checkpoint E) + the Part C validation activity (`feature/Dry-run-as-temporal-activity`). Read [`followup-leaf-run-mode-mock.md`](./followup-leaf-run-mode-mock.md) and [`followup-temporal-validation-activity.md`](./followup-temporal-validation-activity.md) for how that baseline works.diff --git a/wip/dry-run-refactor/followup-leaf-run-mode-mock.md b/wip/dry-run-refactor/followup-leaf-run-mode-mock.mdindex dbb057f38..a862a4587 100644--- a/wip/dry-run-refactor/followup-leaf-run-mode-mock.md+++ b/wip/dry-run-refactor/followup-leaf-run-mode-mock.md@@ -10,7 +10,7 @@>> **Relationship to the in-memory activity follow-up (corrected 2026-06-09):** this follow-up (req 1) is **orthogonal** to [`followup-temporal-validation-activity.md`](./followup-temporal-validation-activity.md) (req 2), **not** a prerequisite for it — see "Still relevant — a distinct dry-run mode" below.>-> **⚠️ Coordinate with the registry branch's Phase 5 (`fix/For-API-update`, decided 2026-06-06).** That branch ships `--mock-inference` / `is_mock_inference` as an *interim* trigger, deliberately built **leaf-first so it lands B1's core ahead of time**: a shared `cogt/content_generation/dry_mock.py` + a per-leaf dry branch keyed on a per-run flag carried on `JobMetadata`. So when this follow-up runs, **B1 collapses to "re-key that helper from `is_mock_inference` → `run_mode`"** (carrier + helper already exist — verify before building from scratch), and **B2 settles the fate of `is_mock_inference`** (retire vs keep a thin reportable-mock — see B2). One distinction to preserve when re-keying: `--mock-inference` emits *non-zero* synthetic usage so a cost report renders; `--dry-run` stays zero-token and its report is *suppressed*. See the registry feature's [`../registry/deferred-followups.md`](../registry/deferred-followups.md) (`--mock-inference` coverage + the `is_mock_inference` fate decision).+> **⚠️ Coordinate with the registry branch's Phase 5 (`fix/For-API-update`, decided 2026-06-06).** That branch ships `--mock-inference` / `is_mock_inference` as an *interim* trigger, deliberately built **leaf-first so it lands B1's core ahead of time**: a shared `cogt/content_generation/dry_mock.py` + a per-leaf dry branch keyed on a per-run flag carried on `JobMetadata`. So when this follow-up runs, **B1 collapses to "re-key that helper from `is_mock_inference` → `run_mode`"** (carrier + helper already exist — verify before building from scratch), and **B2 settles the fate of `is_mock_inference`** (retire vs keep a thin reportable-mock — see B2). One distinction to preserve when re-keying: `--mock-inference` emits *non-zero* synthetic usage so a cost report renders; `--dry-run` stays zero-token and its report is *suppressed*. See the registry feature's [`../history/registry/deferred-followups.md`](../history/registry/deferred-followups.md) (`--mock-inference` coverage + the `is_mock_inference` fate decision).Goal: move the LIVE/DRY decision **down to the cogt leaf** so DRY honors the configured backend — DRY-on-Temporal dispatches `act_llm_gen_*` and mocks **inside** the activity, retiring the "DRY → local in-process" shortcut. Separable cogt/operator refactor (§4.8). Pre-flight items are decided; eng-review decisions (2026-06-10, D2–D11) are folded into the phase checklists below.@@ -61,7 +61,7 @@ Status legend: ☐ not started · ◐ in progress · ☑ done.> **B1's core LANDED on the registry branch's Phase 5 (`fix/For-API-update`).** Already built: `JobMetadata.is_mock_inference`, the shared `cogt/content_generation/dry_mock.py` (synthetic-job reporting parameterized zero-vs-non-zero, plus the leaf mocks + `build_mock_object`), and the per-leaf branch in `llm_generate.py` keyed on `is_mock_inference`. So B1 reduces to: (1) carry `run_mode` on `JobMetadata` alongside `is_mock_inference` (same single-writer, `prepare_pipe_job`), and (2) re-key the leaf branch from `is_mock_inference` → `run_mode==DRY`. **Don't rebuild the helper.** Two caveats to finish what Phase 5 deliberately scoped out: it covers the **LLM leaf only** — `img_gen_*` / `extract_gen_pages` / `templating_gen_text` leaf branches are still TODO here (Phase 5 deferred them because their output is stored above the leaf; see that branch's §7); and `ContentGeneratorDry` still owns its method bodies (only its *reporting* delegates to `dry_mock`), so B2's collapse is still real work.-> **Interim hard guard already landed (F1, registry branch).** `img_gen_single_image` / `img_gen_image_list` / `extract_gen_pages`, plus the search leaf, now **raise `MockInferenceUnsupportedError`** under `is_mock_inference` instead of silently calling the real provider. So when B1 adds the real synthetic-output leaf branch for img-gen/extract/search here, it is **replacing a fail-loud guard, not patching a silent-spend path** — delete the guard at that leaf as you add the DRY branch (under decision 8B the guard's `is_mock_inference` arm stays wherever no reportable-mock is built). See `wip/registry/deferred-followups.md` (`--mock-inference` coverage).+> **Interim hard guard already landed (F1, registry branch).** `img_gen_single_image` / `img_gen_image_list` / `extract_gen_pages`, plus the search leaf, now **raise `MockInferenceUnsupportedError`** under `is_mock_inference` instead of silently calling the real provider. So when B1 adds the real synthetic-output leaf branch for img-gen/extract/search here, it is **replacing a fail-loud guard, not patching a silent-spend path** — delete the guard at that leaf as you add the DRY branch (under decision 8B the guard's `is_mock_inference` arm stays wherever no reportable-mock is built). See [`../history/registry/deferred-followups.md`](../history/registry/deferred-followups.md) (`--mock-inference` coverage).>> **Stale-premise correction (eng review D5, 2026-06-10): search HAS a cogt leaf now.** `search_generate.py` landed as a framework-agnostic leaf (sibling of `llm_generate`, with `act_search_gen_sourced_answer` / `act_search_gen_structured` activities), so the old "web search has no `content_generation` leaf" claim is outdated. **Decision: full uniform treatment** — the search leaf and the `render_page_views` leaf both get `run_mode` DRY branches in B1 (lift `make_search_sourced_answer` / `make_search_structured` / `make_render_page_views` mock bodies from `ContentGeneratorDry:299-319,222-244` into `dry_mock.py`), `PipeSearch` joins B2's swap-removal list (`pipe_search.py:177`), and Tier 17 extends to the search activities.>diff --git a/wip/dry-run-refactor/plan-unified-dry-run.md b/wip/dry-run-refactor/plan-unified-dry-run.mdindex 68a040418..bf3b7e63b 100644--- a/wip/dry-run-refactor/plan-unified-dry-run.md+++ b/wip/dry-run-refactor/plan-unified-dry-run.md@@ -62,7 +62,7 @@ The design deferred these to plan time; resolved here, taking the design's propo- [x] `docs/building-methods/pipes/run-modes-and-backends.md`: matrix collapses to one mode axis × two backends; mock inference disappears as a user-facing concept.- [x] Purge `--mock-inference` from `docs/features/validation-dry-run.md`, `docs/under-the-hood/dry-run-mock-generation.md`, `docs/building-methods/pipes/executing-pipelines.md`; error pages already regenerated in Phase 3.- [x] CHANGELOG `[Unreleased]`: breaking — `--mock-inference` removed; `CogtRunParams.is_mock_inference` → internal `is_mock_usage` DRY sub-flag.-- [x] wip docs: this plan's checkboxes updated; `wip/registry/deferred-followups.md` "fate of is_mock_inference" item closed; `README.md` updated.+- [x] wip docs: this plan's checkboxes updated; `wip/history/registry/deferred-followups.md` "fate of is_mock_inference" item closed; `README.md` updated.### Phase 7 — Final verificationdiff --git a/wip/executive.md b/wip/executive.mdnew file mode 100644index 000000000..728462a05--- /dev/null+++ b/wip/executive.md@@ -0,0 +1,39 @@+# Executive Priorities++This is the top-level decision sheet for the current `wip/` tree. It intentionally favors what to do next over full historical context.++## Strategic Priorities++1. **Finish the plugin/orchestrator architecture.**+ The plugin track is the highest-leverage architecture work: it removes core vendor coupling, gives Temporal and MISTRAL_NATIVE a proper seam, and makes installed integrations discoverable instead of hard-coded. Close the execution-mode/delivery split, version-gating semantics, Temporal extraction, and downstream MISTRAL_NATIVE reconciliation before expanding the plugin surface further.++2. **Productionize distributed execution.**+ P0/P1 tracing and cross-worker cost reporting shipped, so the remaining value is operational: local cross-package dependencies in the crate, remote dependencies from GitHub, nondeterminism decisions, request-scoped tracing state, and the split-worker test coverage gaps. This is what makes worker pools stateless enough to scale.++3. **Close the API/error-handling security tail.**+ Webhook body signing is the clearest security item. After that, finish the structured error long tail: class-level metadata for remaining errors, request ids on delivery failures, and the parked Temporal fail-safe review backlog when Temporal productionization resumes.++4. **Make batch execution harder to overwhelm.**+ The concurrency work is not urgent until batch-at-scale pain returns, but the diagnosis is solid: fan-out scheduling and partial failure should be decided together; rate limiting is separate and needs mode-specific design for direct vs Temporal.++5. **Improve validation and graph ergonomics for tools.**+ The next useful tooling lifts are explicit validation graph targets, registry source paths in `GraphSpec`, parse-level source attribution for malformed TOML, and eventually stuffs as first-class `NodeSpec`s.++## Quick Wins++- **Add `pipelex init --yes`.** The handoff is scoped and mostly plumbing: short-circuit existing prompts to defaults, avoid silently accepting Gateway terms, and unblock downstream CI without vendored `.pipelex/`.+- **Thread `request_id` into delivery failure logs.** Small error-handling tail item; closes an observability asymmetry on webhook/storage failure paths.+- **Categorize missing pipe `type`.** Add `union_tag_not_found` beside `union_tag_invalid` in structured validation error categorization and test a `[pipe.foo]` block without `type`.+- **Add parse-level source attribution test/fix.** More involved than the previous item, but contained and important for editor diagnostics on multi-file validation.+- **Clean up additive multi-file polish.** The recursivity review notes are P3-only but cheap when nearby: soften an overclaiming docstring, comment the `or ""` coercion, and add one populated `LibraryLoadingError` forwarding test if touching validation.+- **Fix/retire runtime-bridge small leftovers.** Decide whether to consume or remove unused execution-mode property helpers; fix the dev helper that glob-selects the latest cost CSV instead of the current run.+- **Tidy plugin follow-ups.** Drop the dead `bedrock` model-lister key with its exact-set test update, and make plugin API version gating use a literal built-against version plus a semver compatibility rule.+- **Patch `temporal-e2e-validate` stale notes.** Remove the vestigial `act_jinja2_gen_text` reference and stale Mode 1 known-xfail text.+- **Add optional `doctor --plain` only if needed.** Current ANSI behavior is standard; a flag is a small ergonomics win for captured diagnostics if this bites again.++## Lower Priority / Parked++- CSV `.xlsx`, formula escaping, delimiter/encoding config, and remote tabular URLs are all feature expansion, not active debt.+- Structured logging is worth doing after the error-handling stack stops moving.+- `stuffs-as-nodespec`, blueprint elaboration directives, and the pathlib workflow are future-shaping tracks; pick them up only with a concrete product/tooling need.+- Historical records live in [`history/`](history/). Do not promote them back into active `wip/` unless they contain a concrete unowned follow-up.diff --git a/wip/dry-run-refactor/PR-bundle-validator.html b/wip/history/PR-bundle-validator.htmlsimilarity index 100%rename from wip/dry-run-refactor/PR-bundle-validator.htmlrename to wip/history/PR-bundle-validator.htmldiff --git a/wip/history/README.md b/wip/history/README.mdnew file mode 100644index 000000000..6f12f2cbb--- /dev/null+++ b/wip/history/README.md@@ -0,0 +1,16 @@+# `wip/history/`++This folder holds shipped project records, old audits, and point-in-time recaps that are useful for archaeology but should not compete with active `wip/` priorities.++The active priority view is [`../executive.md`](../executive.md). If a historical doc still contains a real pickup item, surface that item in `executive.md` instead of moving the whole record back to the active tree.++## Contents++- [`archive/`](archive/) - former `wip/archive/` records.+- [`csv-support/`](csv-support/) - shipped CSV input/output feature notes and deferred expansion items.+- [`keyword-only-arguments/`](keyword-only-arguments/) - completed keyword-only refactor, audits, and downstream notes.+- [`registry/`](registry/) - shipped cost-reporting/usage-registry work and remaining deferred design decisions.+- [`signature-based-validation/`](signature-based-validation/) - completed signature validation feature record.+- [`tests/`](tests/) - completed test-grind notes.+- [`recursivity/`](recursivity/) - completed additive multi-file/recursive-design handoffs.+- Top-level HTML files - rendered PR or design recaps kept as static snapshots.diff --git a/wip/archive/plugin-system-implementation-tracker.md b/wip/history/archive/plugin-system-implementation-tracker.mdsimilarity index 92%rename from wip/archive/plugin-system-implementation-tracker.mdrename to wip/history/archive/plugin-system-implementation-tracker.mdindex 080247d5e..22f200f44 100644--- a/wip/archive/plugin-system-implementation-tracker.md+++ b/wip/history/archive/plugin-system-implementation-tracker.md@@ -1,12 +1,12 @@-> **ARCHIVED 2026-06-21.** This tracked the in-`pipelex` plugin-system work (Phases 0–5: invert every core↔integration seam, then externalize Temporal to the private `pipelex-temporal` plugin). Phases 0–4 are complete and committed; Phase 5's local cut-over is done, with only the publish/release-gated downstream pin-flips outstanding. The active tracker is now [`../../TODOS.md`](../../TODOS.md) — the **consumer-side** migration (orchestrator-agnostic `pipelex-api` base + deployment flavors). Kept here for the as-built history and the decision log (D1–D9).+> **ARCHIVED 2026-06-21.** This tracked the in-`pipelex` plugin-system work (Phases 0–5: invert every core↔integration seam, then externalize Temporal to the private `pipelex-temporal` plugin). Phases 0–4 are complete and committed; Phase 5's local cut-over is done, with only the publish/release-gated downstream pin-flips outstanding. The active tracker is now [`../../../TODOS.md`](../../../TODOS.md) — the **consumer-side** migration (orchestrator-agnostic `pipelex-api` base + deployment flavors). Kept here for the as-built history and the decision log (D1–D9).# Pipelex plugin system — implementation TODOS-**Branch:** `refactor/Plugins-2` (worktree `_plugins`) · **Status:** Phases 0–3 complete + **Option A landed** (post-Phase-3). Phase 3 (orchestrators through the seam) = `5f61db323`. **Option A** — drop the CLI-command harvest entirely; Temporal `worker`/`setup-namespace` → standalone `pipelex-temporal` console script — = commit **`989c9beed`**; all gates green (`make agent-check`, `make tb`, `make agent-test` "All tests passed", Temporal suite **156 passed / 4 xpassed**, both `--help` smokes). The former **D3 is superseded** (see D1–D7). Full as-built + open follow-ups: [`wip/plugins/option-a-drop-cli-command-seam.md`](wip/plugins/option-a-drop-cli-command-seam.md) and the **Option A — as-built** note in the log below. **Phase 4 done** (model_lists, the 5th seam, per D6 — full record in `### Phase 4 — as-built` below; all gates green, committing at this checkpoint). With it, **core names no integration across every enumerated seam**; three pre-existing *unenumerated* core→vendor couplings remain, dispositioned in [`wip/plugins/phase-4-residual-core-vendor-couplings.md`](wip/plugins/phase-4-residual-core-vendor-couplings.md). **Phase 5 Step 0b (C6) DONE** — the Temporal config *schema* relocated out of `pipelex.temporal` into core (`pipelex/system/configuration/config_temporal.py` + its two exceptions in `…/exceptions.py`); `configs.py` no longer imports `pipelex.temporal` (**the last hard core→temporal import is gone**). In-`pipelex`, behavior-neutral (byte-equivalent exception semantics), zero cross-repo blast radius; all gates green (`make tb` · `make agent-check` · `make agent-test` "All tests passed"). Record in `### Phase 5 — Step 0b (C6) as-built` below. **Phase 5 LOCAL cut-over DONE = 2026-06-20** (user go/no-go for the reversible local work only): `pipelex-temporal` scaffolded + populated (top-level `pipelex_temporal`, D8) + **green** (`agent-check` 0/0, `agent-test` "All tests passed"); **core green without temporal** (`agent-check` clean, `tb` green, full `agent-test` 7678 passed); Option-A config-loader dead code removed; docs hygiene (install instructions → `pipelex-temporal`). Downstream pin flips **DEFERRED — publish/release-gated** (cut-list in the `### Phase 5 — cross-repo cut-over as-built` note). Local commits both repos, **NOT pushed**. **Next = downstream wiring** — **CORRECTION 2026-06-21: `pipelex-temporal` is PRIVATE / not-open-source → NOT PyPI.** It's distributed by a pinned `git+ssh` ref (precedent: `pipelex-shared @ git+ssh://…/infra-python-tools.git@<ref>` in `pipelex-platform`). Forced split: public MIT consumers (`pipelex-api`, `pipelex-mistralai-workflows`) **DROP** the `temporal` extra; only **private** infra pins `pipelex-temporal` via git+ssh: `pipelex-worker` **and `pipelex-api-hosted`** (confirmed 2026-06-21 — the hosted runner enqueues Temporal, so its child image needs the client too). Core `pipelex` stays public → normal release. Gated on the **hosted-Temporal rollout**; **user chose to DEFER all wiring (docs-only)** 2026-06-21. **Finalize-local pass (session 2, 2026-06-20):** core cleaned of the moved Temporal dev-tooling (both `temporal-e2e-validate` *and* the not-previously-listed `temporal-test-crate` skills relocated to `pipelex-temporal`; dead Makefile temporal targets removed), `pipelex-temporal` additions-side `/code-review` → **SHIP/clean**, review NITs triaged (stray `.pipelex/traces` untracked+gitignored; `test_extras→tests` back-import deferred), all gates green both repos; **local, uncommitted, still paused before publish.** Record: [`wip/plugins/phase-5-cutover-review-followups.md`](wip/plugins/phase-5-cutover-review-followups.md) → *Finalize-local pass*.+**Branch:** `refactor/Plugins-2` (worktree `_plugins`) · **Status:** Phases 0–3 complete + **Option A landed** (post-Phase-3). Phase 3 (orchestrators through the seam) = `5f61db323`. **Option A** — drop the CLI-command harvest entirely; Temporal `worker`/`setup-namespace` → standalone `pipelex-temporal` console script — = commit **`989c9beed`**; all gates green (`make agent-check`, `make tb`, `make agent-test` "All tests passed", Temporal suite **156 passed / 4 xpassed**, both `--help` smokes). The former **D3 is superseded** (see D1–D7). Full as-built + open follow-ups: [`../../plugins/option-a-drop-cli-command-seam.md`](../../plugins/option-a-drop-cli-command-seam.md) and the **Option A — as-built** note in the log below. **Phase 4 done** (model_lists, the 5th seam, per D6 — full record in `### Phase 4 — as-built` below; all gates green, committing at this checkpoint). With it, **core names no integration across every enumerated seam**; three pre-existing *unenumerated* core→vendor couplings remain, dispositioned in [`../../plugins/phase-4-residual-core-vendor-couplings.md`](../../plugins/phase-4-residual-core-vendor-couplings.md). **Phase 5 Step 0b (C6) DONE** — the Temporal config *schema* relocated out of `pipelex.temporal` into core (`pipelex/system/configuration/config_temporal.py` + its two exceptions in `…/exceptions.py`); `configs.py` no longer imports `pipelex.temporal` (**the last hard core→temporal import is gone**). In-`pipelex`, behavior-neutral (byte-equivalent exception semantics), zero cross-repo blast radius; all gates green (`make tb` · `make agent-check` · `make agent-test` "All tests passed"). Record in `### Phase 5 — Step 0b (C6) as-built` below. **Phase 5 LOCAL cut-over DONE = 2026-06-20** (user go/no-go for the reversible local work only): `pipelex-temporal` scaffolded + populated (top-level `pipelex_temporal`, D8) + **green** (`agent-check` 0/0, `agent-test` "All tests passed"); **core green without temporal** (`agent-check` clean, `tb` green, full `agent-test` 7678 passed); Option-A config-loader dead code removed; docs hygiene (install instructions → `pipelex-temporal`). Downstream pin flips **DEFERRED — publish/release-gated** (cut-list in the `### Phase 5 — cross-repo cut-over as-built` note). Local commits both repos, **NOT pushed**. **Next = downstream wiring** — **CORRECTION 2026-06-21: `pipelex-temporal` is PRIVATE / not-open-source → NOT PyPI.** It's distributed by a pinned `git+ssh` ref (precedent: `pipelex-shared @ git+ssh://…/infra-python-tools.git@<ref>` in `pipelex-platform`). Forced split: public MIT consumers (`pipelex-api`, `pipelex-mistralai-workflows`) **DROP** the `temporal` extra; only **private** infra pins `pipelex-temporal` via git+ssh: `pipelex-worker` **and `pipelex-api-hosted`** (confirmed 2026-06-21 — the hosted runner enqueues Temporal, so its child image needs the client too). Core `pipelex` stays public → normal release. Gated on the **hosted-Temporal rollout**; **user chose to DEFER all wiring (docs-only)** 2026-06-21. **Finalize-local pass (session 2, 2026-06-20):** core cleaned of the moved Temporal dev-tooling (both `temporal-e2e-validate` *and* the not-previously-listed `temporal-test-crate` skills relocated to `pipelex-temporal`; dead Makefile temporal targets removed), `pipelex-temporal` additions-side `/code-review` → **SHIP/clean**, review NITs triaged (stray `.pipelex/traces` untracked+gitignored; `test_extras→tests` back-import deferred), all gates green both repos; **local, uncommitted, still paused before publish.** Record: [`../../plugins/phase-5-cutover-review-followups.md`](../../plugins/phase-5-cutover-review-followups.md) → *Finalize-local pass*.> **Delivery model for this branch.** Per the driving goal, all phases land on `refactor/Plugins` as **one commit per checkpoint** (not one PR per phase), and a **single PR to `dev`** opens once the tracker is done. Each phase's "PR: …" box below is satisfied by its checkpoint commit; the standalone-PR-per-phase wording in the original plan is superseded.-This is the **execution tracker**. The *why* and *how* live in [`wip/plugins/implementation-plan.md`](wip/plugins/implementation-plan.md) (the reviewed, decision-locked plan), built from [`wip/plugins/design.md`](wip/plugins/design.md) (the single decided design). **Read the implementation-plan before starting any phase** — this file tracks progress against it, it does not replace it. Background assessment: [`wip/plugins/README.md`](wip/plugins/README.md), plus the per-area notes (`inference-backends-as-plugins.md`, `orchestrators-as-plugins.md`, `temporal-as-plugin.md`).+This is the **execution tracker**. The *why* and *how* live in [`../../plugins/implementation-plan.md`](../../plugins/implementation-plan.md) (the reviewed, decision-locked plan), built from [`../../plugins/design.md`](../../plugins/design.md) (the single decided design). **Read the implementation-plan before starting any phase** — this file tracks progress against it, it does not replace it. Background assessment: [`../../plugins/README.md`](../../plugins/README.md), plus the per-area notes (`inference-backends-as-plugins.md`, `orchestrators-as-plugins.md`, `temporal-as-plugin.md`).> **How to use this file.** Tick boxes as you land work. **Do not skip a `🛑 CHECKPOINT`** — each one is a hard stop with three mandatory actions (verify · capture cold-start context · fan-out `/code-review`). The plan is one PR per phase; each phase lands green on its own.@@ -25,14 +25,14 @@ This is the **execution tracker**. The *why* and *how* live in [`wip/plugins/imp| Orchestrator dispatch | `runtime_bridge/bridge.py` (`match` ~`:147`, `_run_mistral_native` `:408`, `_run_direct` `:270`, `_run_temporal_*` `:297/:330`) | `match execution_mode:` → hard Mistral import + lazy Temporal + per-mode install messages || Boot/teardown hub swap | `pipelex.py` (~`:377-479`) | four `if get_config().temporal.is_enabled:` blocks + inlined teardown || ~~Config~~ | `system/configuration/configs.py:14` | **RELOCATED — Phase 5 Step 0b (C6).** Schema → `pipelex/system/configuration/config_temporal.py`; its two exceptions (`TemporalConfigError`, `WorkerTaskQueueUnknownError`) → `pipelex/system/configuration/exceptions.py` (re-based on `PipelexError`, byte-equivalent). `configs.py` imports from core — the one hard `pipelex.temporal` import in core config is gone. |-| ~~CLI~~ | `pipelex/temporal/temporal_cli.py` | **REMOVED — Option A.** No CLI-command seam/harvest at all; Temporal's `worker` + `setup-namespace` ship as the standalone `pipelex-temporal` console script ([doc](wip/plugins/option-a-drop-cli-command-seam.md)). |+| ~~CLI~~ | `pipelex/temporal/temporal_cli.py` | **REMOVED — Option A.** No CLI-command seam/harvest at all; Temporal's `worker` + `setup-namespace` ship as the standalone `pipelex-temporal` console script ([doc](../../plugins/option-a-drop-cli-command-seam.md)). || Naming overload | `plugins/{plugin,plugin_manager,plugin_sdk_registry,plugin_factory_abstract}.py`, `hub.py` `"PluginManager2 is not initialized"` | three-way "plugin" overload to kill |**Locked decisions (D1–D7)** — do not re-litigate, see plan for full text:- **D1** — inference factory = a typed callable `MakeWorkerFn`, not a one-method Protocol object (kills ~30 classes).- **D2** — Phase 1 PR = seam machinery **merged** with the LLM family (contract meets a real backend before locking).-- **D3** — ~~plugin CLI commands harvested by running the pure `build_registrar` at CLI-build~~ **SUPERSEDED → Option A** ([`wip/plugins/option-a-drop-cli-command-seam.md`](wip/plugins/option-a-drop-cli-command-seam.md), landed post-Phase-3): the CLI-command *contribution path* was **removed**, not hardened. Temporal's `worker` + `setup-namespace` are now a standalone `pipelex-temporal` console script (`[project.scripts]`), so `pipelex --help` no longer loads config or scans entry points and a broken/colliding plugin can't brick the host CLI. The inference-backend / orchestrator / boot-slot seams and `pipelex plugins list` are **unchanged**; `add_cli_command` / `CliCommand` are gone from the registrar. Downstream `pipelex-worker` Dockerfile/Makefile flip is release-gated (see the plan's cross-repo section).+- **D3** — ~~plugin CLI commands harvested by running the pure `build_registrar` at CLI-build~~ **SUPERSEDED → Option A** ([`../../plugins/option-a-drop-cli-command-seam.md`](../../plugins/option-a-drop-cli-command-seam.md), landed post-Phase-3): the CLI-command *contribution path* was **removed**, not hardened. Temporal's `worker` + `setup-namespace` are now a standalone `pipelex-temporal` console script (`[project.scripts]`), so `pipelex --help` no longer loads config or scans entry points and a broken/colliding plugin can't brick the host CLI. The inference-backend / orchestrator / boot-slot seams and `pipelex plugins list` are **unchanged**; `add_cli_command` / `CliCommand` are gone from the registrar. Downstream `pipelex-worker` Dockerfile/Makefile flip is release-gated (see the plan's cross-repo section).- **D4** — Phase 0 keeps `SdkClientManager` a **pure rename**; collapsing it into the registry is a **P3 follow-up commit**, not bundled.- **D5** — hub slot claims are **deferred thunks** (`claim_*(factory: Callable[[], Impl])`), invoked only at the setup apply-point → `register` stays import-light (never imports `temporalio`).- **D6** — the 5th seam (`model_lists.py`) is **inverted too**, as Phase 4, via a model-listing capability on the inference contract.@@ -266,9 +266,9 @@ This is the **execution tracker**. The *why* and *how* live in [`wip/plugins/imp### 🛑 CHECKPOINT 4 — hard stop ("core names no integration" holds without an asterisk)-- [x] **Verify:** `make agent-check` clean (pyright 0 over 2243 files / mypy 0 / keyword-only pass) · `make agent-test` green ("All tests passed.") · targeted plugins+cogt suite 715 passed. `model_lists.py` names no integration; the final sweep returns only **pre-existing, out-of-scope** vendor refs (`config_cogt.py` typed config = by-design D7; `img_gen_args_factory.py` + `backend_factory.py` = genuine but unenumerated couplings) — captured in [`wip/plugins/phase-4-residual-core-vendor-couplings.md`](wip/plugins/phase-4-residual-core-vendor-couplings.md). No dispatch-path leak remains.+- [x] **Verify:** `make agent-check` clean (pyright 0 over 2243 files / mypy 0 / keyword-only pass) · `make agent-test` green ("All tests passed.") · targeted plugins+cogt suite 715 passed. `model_lists.py` names no integration; the final sweep returns only **pre-existing, out-of-scope** vendor refs (`config_cogt.py` typed config = by-design D7; `img_gen_args_factory.py` + `backend_factory.py` = genuine but unenumerated couplings) — captured in [`../../plugins/phase-4-residual-core-vendor-couplings.md`](../../plugins/phase-4-residual-core-vendor-couplings.md). No dispatch-path leak remains.- [x] **Capture cold-start context:** `### Phase 4 — as-built` note below.-- [x] **Fan-out `/code-review`:** `pr-review-toolkit:code-reviewer` reviewed the Phase 4 working-tree diff against HEAD. **Verdict: byte-equivalent and clean — no BLOCKER / no SHOULD-FIX.** It walked all five correctness questions against `git show HEAD:…model_lists.py` and confirmed: each lister's kwargs match its old `match` arm (mistral's no-`backend` + sync `# noqa: RUF029`, bedrock sync, the rest async); the deleted `find_spec` guards survive **byte-for-byte** inside each `list_*_models` fn (same lib/extra/message; openai has none in old or new); the anthropic `AnthropicSDKUnsupportedError`→`ModelListingUnsupportedError` translation is correct and core imports no anthropic symbol; `any_listed` threads identically (not set on the unsupported `continue`); the registered sdk keys are exactly the old arms' set. Plus import-light, `get_optional`-vs-`lookup`, keyword-only, and the Case-2 boundary (with `except PipelexCLIError: raise` ordering preserved so internal auth `PipelexCLIError`s aren't re-wrapped). One **NIT** (doc recommended `require_sdk` while the built-in listers reuse their `list_*_models` inline `find_spec` guard) — **applied**: the "Listing models" doc section now tells one story (recommends `require_sdk`, notes the built-ins reuse the existing inline guard). The wip residual-couplings doc was confirmed accurate. A follow-up **xhigh workflow `/code-review`** (10 finder angles → adversarial verify) re-confirmed byte-equivalence and surfaced reuse/altitude follow-ups: the two cheap ones were **applied** (a shared `PluginRegistrar._add` helper mirroring `_claim`; the hardcoded item-counts removed from this as-built), the four design-tradeoffs **deferred** — all recorded in [`wip/plugins/phase-4-review-followups.md`](wip/plugins/phase-4-review-followups.md).+- [x] **Fan-out `/code-review`:** `pr-review-toolkit:code-reviewer` reviewed the Phase 4 working-tree diff against HEAD. **Verdict: byte-equivalent and clean — no BLOCKER / no SHOULD-FIX.** It walked all five correctness questions against `git show HEAD:…model_lists.py` and confirmed: each lister's kwargs match its old `match` arm (mistral's no-`backend` + sync `# noqa: RUF029`, bedrock sync, the rest async); the deleted `find_spec` guards survive **byte-for-byte** inside each `list_*_models` fn (same lib/extra/message; openai has none in old or new); the anthropic `AnthropicSDKUnsupportedError`→`ModelListingUnsupportedError` translation is correct and core imports no anthropic symbol; `any_listed` threads identically (not set on the unsupported `continue`); the registered sdk keys are exactly the old arms' set. Plus import-light, `get_optional`-vs-`lookup`, keyword-only, and the Case-2 boundary (with `except PipelexCLIError: raise` ordering preserved so internal auth `PipelexCLIError`s aren't re-wrapped). One **NIT** (doc recommended `require_sdk` while the built-in listers reuse their `list_*_models` inline `find_spec` guard) — **applied**: the "Listing models" doc section now tells one story (recommends `require_sdk`, notes the built-ins reuse the existing inline guard). The wip residual-couplings doc was confirmed accurate. A follow-up **xhigh workflow `/code-review`** (10 finder angles → adversarial verify) re-confirmed byte-equivalence and surfaced reuse/altitude follow-ups: the two cheap ones were **applied** (a shared `PluginRegistrar._add` helper mirroring `_claim`; the hardcoded item-counts removed from this as-built), the four design-tradeoffs **deferred** — all recorded in [`../../plugins/phase-4-review-followups.md`](../../plugins/phase-4-review-followups.md).- [x] **PR:** checkpoint commit on `refactor/Plugins-2` (one-commit-per-checkpoint). Phases 0–4 complete — the in-`pipelex` work is done.---@@ -305,7 +305,7 @@ This is the **execution tracker**. The *why* and *how* live in [`wip/plugins/imp- [ ] **Verify:** Temporal is an external plugin; core has no `temporal` extra; downstream pins flipped; consumer suites green.- [ ] **Capture cold-start context:** `### Phase 5 — as-built` note — the published `pipelex-temporal` version, the pins flipped in each downstream repo, and the consumer-suite green evidence.-- [ ] **Fan-out `/code-review`:** core *deletion* side reviewed (session 1, on `a8382d1a1`); `pipelex-temporal` *additions* side reviewed (session 2) → **SHIP/clean** (no BLOCKER/SHOULD-FIX; wheel built offline, pin-no-leak + import-light proven at runtime). 2 NITs triaged (traces fixed; `test_extras→tests` back-import deferred). Remaining: re-review downstream pin-flip diffs at publish. Triage: [`wip/plugins/phase-5-cutover-review-followups.md`](wip/plugins/phase-5-cutover-review-followups.md).+- [ ] **Fan-out `/code-review`:** core *deletion* side reviewed (session 1, on `a8382d1a1`); `pipelex-temporal` *additions* side reviewed (session 2) → **SHIP/clean** (no BLOCKER/SHOULD-FIX; wheel built offline, pin-no-leak + import-light proven at runtime). 2 NITs triaged (traces fixed; `test_extras→tests` back-import deferred). Remaining: re-review downstream pin-flip diffs at publish. Triage: [`../../plugins/phase-5-cutover-review-followups.md`](../../plugins/phase-5-cutover-review-followups.md).- [ ] **Ship:** coordinate the cross-repo release. Effort complete.---@@ -436,7 +436,7 @@ Beyond the per-phase CP reviews above, an **xhigh** whole-PR pass ran (10 finder- **Import-light blocklist (supersedes "BLOCKED grew docling+linkup"):** added `openai`, `portkey_ai`, `pypdfium2` — the migrated plugins' deferred SDKs the guard wasn't covering. (The review said "openrouter," but that closure rides the `openai` SDK; verified by probe that none of the three are imported at registration time, so the invariant holds.) The guard docstring now says "any backend SDK (optional extra **or** heavy core dep)."- **Multi-spec `require_sdk`:** on a partial miss it named ALL specs; now collects + names only the absent one(s) (so a user with `boto3` but not `aioboto3` isn't told to reinstall `boto3`). New `test_require_sdk` multi-spec case.-**Deferred follow-ups → `wip/plugins/phase-2-review-deferred.md`** (latent footguns reachable only via external entry-point plugins / future callers + quality cleanups). **Two bear on Phase 3 — read that doc before starting:**+**Deferred follow-ups → `../../plugins/phase-2-review-deferred.md`** (latent footguns reachable only via external entry-point plugins / future callers + quality cleanups). **Two bear on Phase 3 — read that doc before starting:**- `build_registrar` accumulates `cli_commands` / `slot_claims` / `teardown_callbacks` but boot only consumes `inference_backends` + `orchestrators` — i.e. those three menus are **wired for the first time in Phase 3** (CLI collapse / Boot-teardown collapse). The doc frames the current state as a teardown-leak footgun for *external* plugins; closing it is literally Phase 3 work. Until then, an external plugin contributing those is silently inert.- search `reporting_delegate` defaults to `None` (the C9 normalization above) — fine for the one real caller, but a future Temporal search-activity path that omits it gets silent zero-reporting. Relevant when Phase 3/5 routes search through a worker.@@ -475,8 +475,8 @@ Beyond the per-phase CP reviews above, an **xhigh** whole-PR pass ran (10 finder**Post-checkpoint xhigh `/code-review` follow-ups (separate from the CHECKPOINT-3 reviewer pass above).** A later xhigh `/code-review` over the Phase 3 commit surfaced a dominant correctness cluster plus medium/low items, captured for triage:-- 🔴 **Critical — read before Phase 5 / before externalizing any plugin:** [`wip/plugins/phase-3-critical-cli-harvest-fragility.md`](wip/plugins/phase-3-critical-cli-harvest-fragility.md). The import-time CLI plugin-command harvest (D3) is an unguarded surface: a broken/incompatible/colliding **external** plugin or an unreadable user config can brick *every* `pipelex` command — including the `--help`/`doctor`/`plugins`/`init` recovery commands — and `add_cli_command` has no collision guard, so a plugin can silently shadow a core command (`run`, …). Latent for in-tree-only installs (suite green), live the moment Phase 5 ships an external dist. **Cold-start problem statement only — solution to be explored in a fresh session.**-- 🟡 **Medium/low deferred items → [`wip/plugins/phase-3-review-deferred.md`](wip/plugins/phase-3-review-deferred.md):** the misleading `MISTRAL_NATIVE` "install a package you already have" hint (dead mode until the Mistral plugin lands), the bridge dropping its orchestrator error-wrap (external-orchestrator contract), `teardown()` with no `try`/`finally`, `_teardown_temporal` re-fetching from the global hub, the wrong SPI doc about Temporal entry-point discovery, an enum identity comparison, double-discovery/import-time cost (coupled to the critical fix), a dead `serialize_pipe_output` re-export, and a hardcoded slot count.+- 🔴 **Critical — read before Phase 5 / before externalizing any plugin:** [`../../plugins/phase-3-critical-cli-harvest-fragility.md`](../../plugins/phase-3-critical-cli-harvest-fragility.md). The import-time CLI plugin-command harvest (D3) is an unguarded surface: a broken/incompatible/colliding **external** plugin or an unreadable user config can brick *every* `pipelex` command — including the `--help`/`doctor`/`plugins`/`init` recovery commands — and `add_cli_command` has no collision guard, so a plugin can silently shadow a core command (`run`, …). Latent for in-tree-only installs (suite green), live the moment Phase 5 ships an external dist. **Cold-start problem statement only — solution to be explored in a fresh session.**+- 🟡 **Medium/low deferred items → [`../../plugins/phase-3-review-deferred.md`](../../plugins/phase-3-review-deferred.md):** the misleading `MISTRAL_NATIVE` "install a package you already have" hint (dead mode until the Mistral plugin lands), the bridge dropping its orchestrator error-wrap (external-orchestrator contract), `teardown()` with no `try`/`finally`, `_teardown_temporal` re-fetching from the global hub, the wrong SPI doc about Temporal entry-point discovery, an enum identity comparison, double-discovery/import-time cost (coupled to the critical fix), a dead `serialize_pipe_output` re-export, and a hardcoded slot count.#### CHECKPOINT-3 `/code-review` (pr-review-toolkit:code-reviewer, on the Phase 3 working-tree diff)@@ -486,7 +486,7 @@ Applied: **S1** (the one should-fix) — added `test_harvest_config_falls_back_t### Option A — as-built (post-Phase-3, commit `989c9beed`)-**Status:** done. `make agent-check` clean (pyright 0 / mypy 0 over 2240 files / keyword-only) · `make tb` green · `make agent-test` "All tests passed." · `pytest tests/integration/pipelex/temporal/` → **156 passed, 4 xpassed** (the 4 xpassed = pre-existing xdist class-registration flakiness markers, matching the Phase-3 baseline) · both `--help` smokes pass. Full record + rationale: [`wip/plugins/option-a-drop-cli-command-seam.md`](wip/plugins/option-a-drop-cli-command-seam.md).+**Status:** done. `make agent-check` clean (pyright 0 / mypy 0 over 2240 files / keyword-only) · `make tb` green · `make agent-test` "All tests passed." · `pytest tests/integration/pipelex/temporal/` → **156 passed, 4 xpassed** (the 4 xpassed = pre-existing xdist class-registration flakiness markers, matching the Phase-3 baseline) · both `--help` smokes pass. Full record + rationale: [`../../plugins/option-a-drop-cli-command-seam.md`](../../plugins/option-a-drop-cli-command-seam.md).**Why.** The post-Phase-3 xhigh review found a critical fragility: the Phase-3 CLI-command harvest (the former D3) ran `build_registrar` at *import* of `pipelex/cli/_cli.py` on **every** `pipelex` invocation, so a broken/colliding external plugin or an unreadable user config could brick every command — including the `--help`/`doctor`/`plugins`/`init` recovery commands — and `add_cli_command` had no collision guard, so a plugin could silently shadow a core command. **Option A resolves it by removing the surface, not hardening it.** CLI commands are not a plugin contribution type any more.@@ -500,7 +500,7 @@ Applied: **S1** (the one should-fix) — added `test_harvest_config_falls_back_t**Untouched (deliberately out of scope — do NOT unwind in later phases):** the four inference-family registry lookups, the bridge → `OrchestratorRegistry` dispatch, the `temporal.is_enabled` boot-slot claims + LIFO teardown, `build_registrar` / `BUILTIN_PLUGINS` / the `pipelex.plugins` entry-point group for *runtime* contributions, `pipelex plugins list`, the denylist.-**Decision lineage:** the former **D3** (harvest at CLI-build) is **superseded** by Option A (see the D1–D7 list). [`phase-3-critical-cli-harvest-fragility.md`](wip/plugins/phase-3-critical-cli-harvest-fragility.md) → RESOLVED-BY-REMOVAL; two items in [`phase-3-review-deferred.md`](wip/plugins/phase-3-review-deferred.md) (double-discovery/import-time cost; factually-wrong SPI doc) → resolved.+**Decision lineage:** the former **D3** (harvest at CLI-build) is **superseded** by Option A (see the D1–D7 list). [`phase-3-critical-cli-harvest-fragility.md`](../../plugins/phase-3-critical-cli-harvest-fragility.md) → RESOLVED-BY-REMOVAL; two items in [`phase-3-review-deferred.md`](../../plugins/phase-3-review-deferred.md) (double-discovery/import-time cost; factually-wrong SPI doc) → resolved.**Open follow-ups (NOT done):**@@ -539,7 +539,7 @@ Applied: **S1** (the one should-fix) — added `test_harvest_config_falls_back_t**Docs:** `docs/under-the-hood/inference-backend-plugins.md` gained a "Listing models — an optional capability" section (the `add_model_lister` call, the `ListModelsFn` shape, import-light/fail-at-use rules, the `ModelListingUnsupportedError` soft-signal); SPI table += `ListModelsFn` / `ModelListingUnsupportedError`; fail-loud table += `DuplicateModelListerError` (and fixed the adjacent stale `NotImplementedError` row → `InferenceBackendNotFoundError`).-**CHECKPOINT-4 sweep result — "core names no integration" now holds for every enumerated seam.** The broad grep surfaces three **pre-existing, unchanged** `pipelex.plugins.<vendor>` refs that were never in the Phase 0–4 seam list: `cogt/config_cogt.py` (vendor typed-config models — **by design**, design D7), `cogt/img_gen/img_gen_args_factory.py` (`OpenAIImgGenFactory`) and `cogt/model_backends/backend_factory.py` (`VertexAIFactory`, lazy, vertexai auth) — the latter two genuine but **unenumerated** couplings (each would need its own contract capability to invert). Recorded with disposition in [`wip/plugins/phase-4-residual-core-vendor-couplings.md`](wip/plugins/phase-4-residual-core-vendor-couplings.md). **No dispatch-path integration remains.**+**CHECKPOINT-4 sweep result — "core names no integration" now holds for every enumerated seam.** The broad grep surfaces three **pre-existing, unchanged** `pipelex.plugins.<vendor>` refs that were never in the Phase 0–4 seam list: `cogt/config_cogt.py` (vendor typed-config models — **by design**, design D7), `cogt/img_gen/img_gen_args_factory.py` (`OpenAIImgGenFactory`) and `cogt/model_backends/backend_factory.py` (`VertexAIFactory`, lazy, vertexai auth) — the latter two genuine but **unenumerated** couplings (each would need its own contract capability to invert). Recorded with disposition in [`../../plugins/phase-4-residual-core-vendor-couplings.md`](../../plugins/phase-4-residual-core-vendor-couplings.md). **No dispatch-path integration remains.****Notes for Phase 5:** Phase 4 is independent of the Temporal externalization. No new cross-repo surface. The model-lister registry is a pure additive capability — an external backend plugin can now contribute a lister via the same `register` it uses for `add_inference_backend`.@@ -592,5 +592,5 @@ Applied: **S1** (the one should-fix) — added `test_harvest_config_falls_back_t- Deeper `docs/under-the-hood/` internal-path references (`temporal-integration.md`, `orchestrator-plugins.md`, `distributed-content-generation.md`, `pipe-routing-and-execution.md`, `error-model.md`) still say `pipelex.temporal` in prose — accurate-keeping pass deferred (the system behaves identically; coupled to the docs-deploy story). `orchestrator-plugins.md` should eventually present temporal as the worked **external** plugin example.- Cross-repo `error_handling/test_data.py` parity constants are now duplicated in core + pipelex-temporal (can drift; inherent to externalization — no shared-file enforcement across repos).- Local commits made on both sides (NOT pushed): `_plugins` = Phase 5 checkpoint commit on `refactor/Plugins-2`; `pipelex-temporal` = initial commit on `main`.-- **Post-local-cut-over `/code-review` triage (2026-06-20)** → [`wip/plugins/phase-5-cutover-review-followups.md`](wip/plugins/phase-5-cutover-review-followups.md). xhigh review of the core-side cut-over commit. **Fixed this session** (reachable/core-hygiene that stays in core): kit `commands.md` temporal-test section removed + `CLAUDE.md` regen; `uv.lock` temporal-extra drop; `bridge.py` + `test_config_temporal_optional_dep` docstrings; 5 plugin/cogt test stubs (dropped vestigial `temporal` stub field); **restored two core-coverage tests** — `test_trace_context_contract::test_non_direct_mode_nulls_host_trace_context` (core-side guard for the bridge's non-DIRECT trace_context nulling — distinct from the temporal-mode test that moved to pipelex-temporal) + `test_dispatch_options_no_temporalio.py` (DispatchOptions constructible without temporalio — the `RetryPolicy = Any` forward-ref contract the AST scan can't catch). **Still deferred** (in the wip doc): skill `temporal-e2e-validate` relocation, Makefile temporal targets (`tw`/`ttm`/…, CI-isolated), `debugging-hanging-pytest-runs.md`, boot eager-validation design call, `non_retryable_error_types` cross-repo class-name desync, dead `cv_batch_screening_inputs.json` mirror.+- **Post-local-cut-over `/code-review` triage (2026-06-20)** → [`../../plugins/phase-5-cutover-review-followups.md`](../../plugins/phase-5-cutover-review-followups.md). xhigh review of the core-side cut-over commit. **Fixed this session** (reachable/core-hygiene that stays in core): kit `commands.md` temporal-test section removed + `CLAUDE.md` regen; `uv.lock` temporal-extra drop; `bridge.py` + `test_config_temporal_optional_dep` docstrings; 5 plugin/cogt test stubs (dropped vestigial `temporal` stub field); **restored two core-coverage tests** — `test_trace_context_contract::test_non_direct_mode_nulls_host_trace_context` (core-side guard for the bridge's non-DIRECT trace_context nulling — distinct from the temporal-mode test that moved to pipelex-temporal) + `test_dispatch_options_no_temporalio.py` (DispatchOptions constructible without temporalio — the `RetryPolicy = Any` forward-ref contract the AST scan can't catch). **Still deferred** (in the wip doc): skill `temporal-e2e-validate` relocation, Makefile temporal targets (`tw`/`ttm`/…, CI-isolated), `debugging-hanging-pytest-runs.md`, boot eager-validation design call, `non_retryable_error_types` cross-repo class-name desync, dead `cv_batch_screening_inputs.json` mirror.- **Finalize-local pass (session 2, 2026-06-20)** → same wip doc, *Finalize-local pass* section. Closed two of the prior bullet's "Still deferred" items: **both** Temporal skills relocated to `pipelex-temporal` (`temporal-e2e-validate` *and* `temporal-test-crate` — the latter was never on the list, also dead in core) + removed from core, and the **core** Makefile temporal targets deleted (help + `.PHONY` + `test-temporal`/`ttm` + `temporal-server`/`-stop`/`-worker`/`-run`; the `pipelex-temporal` Makefile *add* stays open — unverifiable without a running server). Plus the `pipelex-temporal` *additions*-side `/code-review` → **SHIP/clean**; NITs: stray `.pipelex/traces/*.ndjson` untracked+gitignored, shipped `test_extras→tests` back-import deferred (pre-existing/dormant). Gates: core `make tb` + full `make agent-test` green (HEAD `27da150a5`); pipelex-temporal `make agent-check` clean. **Local, uncommitted; still paused before publish.**diff --git a/wip/archive/signature-based-validation-tdd-plan.md b/wip/history/archive/signature-based-validation-tdd-plan.mdsimilarity index 99%rename from wip/archive/signature-based-validation-tdd-plan.mdrename to wip/history/archive/signature-based-validation-tdd-plan.mdindex 20e6d8e22..8a3b617ce 100644--- a/wip/archive/signature-based-validation-tdd-plan.md+++ b/wip/history/archive/signature-based-validation-tdd-plan.md@@ -1,6 +1,6 @@# Signature-Based Validation — TDD implementation plan-> **Superseded as the live tracker.** The current-state reference and reviewer verification map now live at [`../signature-based-validation.md`](../signature-based-validation.md). This file is kept as the phase-by-phase TDD build record (historical); where it disagrees with the live tracker on present behavior, the live tracker wins. Internal references to "TODOS.md" below mean *this* file under its original name.+> **Superseded as the live tracker.** The current-state reference and reviewer verification map now live at [`../signature-based-validation/signature-based-validation.md`](../signature-based-validation/signature-based-validation.md). This file is kept as the phase-by-phase TDD build record (historical); where it disagrees with the live tracker on present behavior, the live tracker wins. Internal references to "TODOS.md" below mean *this* file under its original name.Status: Phases 1–7.3 landed (plus Phase 5.2 lenient-summary polish) (2026-05-14); Phase 7.4 open and tracked as a merge-gate. **The branch is in a consistent, reviewable state** — the runtime accepts `type = "PipeSignature"`, and `.pipelex/plxt.toml` declares the matching schema source of truth (`derived/mthds_schema.json`) via a `[[rule]] / [rule.schema] path = ...` block scoped to `**/*.mthds`. That block is the intended configuration on this branch, not a workaround: the bundled `plxt` schema doesn't yet describe `PipeSignature`, so the local schema is the only correct one to validate against here. At merge time, once `vscode-pipelex` ships an updated bundled schema, the `[[rule]]` block is removed in the same commit and the bundled schema takes over again — that swap is the Phase 7.4 merge-gate item. Docs (new `signature-pipes.md` page + nav + cross-links + CLI reference + tightened spec docstring) and CHANGELOG (`[Unreleased]` Added/Changed) are in. `make agent-check` and `make agent-test` are green on this branch. Reviewers: please treat the `[[rule]]` block in `.pipelex/plxt.toml` as load-bearing for the branch — not as a smell to fix.diff --git a/wip/csv-support/README.md b/wip/history/csv-support/README.mdsimilarity index 98%rename from wip/csv-support/README.mdrename to wip/history/csv-support/README.mdindex 95d3083b2..b8dbc46ed 100644--- a/wip/csv-support/README.md+++ b/wip/history/csv-support/README.md@@ -15,7 +15,7 @@ A CSV (or, behind a not-yet-built seam, an Excel `.xlsx`) file maps to a `ListCoThe headline acceptance test is a full round trip: `people.csv` → `PipeBatch` → `PipeSequence`(`PipeLLM` + `PipeCompose`) → `summaries.csv`, green in dry mode via both the in-process runner and a real CLI subprocess.-User-facing docs: [`docs/building-methods/pipes/csv-input-and-output.md`](../../docs/building-methods/pipes/csv-input-and-output.md) + `--save-csv` in [`docs/tools/cli/run.md`](../../docs/tools/cli/run.md); CHANGELOG `[Unreleased]`.+User-facing docs: [`docs/building-methods/pipes/csv-input-and-output.md`](../../../docs/building-methods/pipes/csv-input-and-output.md) + `--save-csv` in [`docs/tools/cli/run.md`](../../../docs/tools/cli/run.md); CHANGELOG `[Unreleased]`.---diff --git a/wip/csv-support/design.md b/wip/history/csv-support/design.mdsimilarity index 100%rename from wip/csv-support/design.mdrename to wip/history/csv-support/design.mddiff --git a/wip/csv-support/phase2-review-followups.md b/wip/history/csv-support/phase2-review-followups.mdsimilarity index 100%rename from wip/csv-support/phase2-review-followups.mdrename to wip/history/csv-support/phase2-review-followups.mddiff --git a/wip/csv-support/phase3-4-review-followups.md b/wip/history/csv-support/phase3-4-review-followups.mdsimilarity index 100%rename from wip/csv-support/phase3-4-review-followups.mdrename to wip/history/csv-support/phase3-4-review-followups.mddiff --git a/wip/csv-support/security-followups.md b/wip/history/csv-support/security-followups.mdsimilarity index 100%rename from wip/csv-support/security-followups.mdrename to wip/history/csv-support/security-followups.mddiff --git a/wip/keyword-only-arguments/README.md b/wip/history/keyword-only-arguments/README.mdsimilarity index 85%rename from wip/keyword-only-arguments/README.mdrename to wip/history/keyword-only-arguments/README.mdindex 36d58558c..5ad8f5b94 100644--- a/wip/keyword-only-arguments/README.md+++ b/wip/history/keyword-only-arguments/README.md@@ -4,7 +4,7 @@ Track record for the **keyword-only arguments refactor** on `refactor/Function-c## Status-The pipelex-internal refactor is **complete and landed on the branch** — all waves done, the guard hard-blocks on any violation, and the convention is promoted to the canonical contributor doc at [`docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md) (in the mkdocs nav). The downstream consumers were updated in lockstep (PRs #19 / #55 / #75 / #153, plus pipelex-worker #23) and **pushed**, all pinned to the branch git rev `0e32c8c0` and green on their test suites. (`pipelex-mistralai-workflows` is the one genuine out-of-scope consumer — it's on its own mistralai-2x hold track.)+The pipelex-internal refactor is **complete and landed on the branch** — all waves done, the guard hard-blocks on any violation, and the convention is promoted to the canonical contributor doc at [`docs/contribute/keyword-only-arguments.md`](../../../docs/contribute/keyword-only-arguments.md) (in the mkdocs nav). The downstream consumers were updated in lockstep (PRs #19 / #55 / #75 / #153, plus pipelex-worker #23) and **pushed**, all pinned to the branch git rev `0e32c8c0` and green on their test suites. (`pipelex-mistralai-workflows` is the one genuine out-of-scope consumer — it's on its own mistralai-2x hold track.)**One open item:** at pipelex release, swap each consumer's temporary `[tool.uv.sources]` git pin back to the released `pipelex` version. Tracked in the checklist of [`downstream-consumer-breakage.md`](downstream-consumer-breakage.md).diff --git a/wip/keyword-only-arguments/audit/findings/base_exceptions.md b/wip/history/keyword-only-arguments/audit/findings/base_exceptions.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/base_exceptions.mdrename to wip/history/keyword-only-arguments/audit/findings/base_exceptions.mddiff --git a/wip/keyword-only-arguments/audit/findings/builder.md b/wip/history/keyword-only-arguments/audit/findings/builder.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/builder.mdrename to wip/history/keyword-only-arguments/audit/findings/builder.mddiff --git a/wip/keyword-only-arguments/audit/findings/cli.md b/wip/history/keyword-only-arguments/audit/findings/cli.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/cli.mdrename to wip/history/keyword-only-arguments/audit/findings/cli.mddiff --git a/wip/keyword-only-arguments/audit/findings/cogt.md b/wip/history/keyword-only-arguments/audit/findings/cogt.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/cogt.mdrename to wip/history/keyword-only-arguments/audit/findings/cogt.mddiff --git a/wip/keyword-only-arguments/audit/findings/core.md b/wip/history/keyword-only-arguments/audit/findings/core.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/core.mdrename to wip/history/keyword-only-arguments/audit/findings/core.mddiff --git a/wip/keyword-only-arguments/audit/findings/errors.md b/wip/history/keyword-only-arguments/audit/findings/errors.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/errors.mdrename to wip/history/keyword-only-arguments/audit/findings/errors.mddiff --git a/wip/keyword-only-arguments/audit/findings/graph.md b/wip/history/keyword-only-arguments/audit/findings/graph.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/graph.mdrename to wip/history/keyword-only-arguments/audit/findings/graph.mddiff --git a/wip/keyword-only-arguments/audit/findings/hub.md b/wip/history/keyword-only-arguments/audit/findings/hub.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/hub.mdrename to wip/history/keyword-only-arguments/audit/findings/hub.mddiff --git a/wip/keyword-only-arguments/audit/findings/kit.md b/wip/history/keyword-only-arguments/audit/findings/kit.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/kit.mdrename to wip/history/keyword-only-arguments/audit/findings/kit.mddiff --git a/wip/keyword-only-arguments/audit/findings/language.md b/wip/history/keyword-only-arguments/audit/findings/language.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/language.mdrename to wip/history/keyword-only-arguments/audit/findings/language.mddiff --git a/wip/keyword-only-arguments/audit/findings/libraries.md b/wip/history/keyword-only-arguments/audit/findings/libraries.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/libraries.mdrename to wip/history/keyword-only-arguments/audit/findings/libraries.mddiff --git a/wip/keyword-only-arguments/audit/findings/observer.md b/wip/history/keyword-only-arguments/audit/findings/observer.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/observer.mdrename to wip/history/keyword-only-arguments/audit/findings/observer.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipe_controllers.md b/wip/history/keyword-only-arguments/audit/findings/pipe_controllers.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipe_controllers.mdrename to wip/history/keyword-only-arguments/audit/findings/pipe_controllers.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipe_operators.md b/wip/history/keyword-only-arguments/audit/findings/pipe_operators.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipe_operators.mdrename to wip/history/keyword-only-arguments/audit/findings/pipe_operators.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipe_run.md b/wip/history/keyword-only-arguments/audit/findings/pipe_run.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipe_run.mdrename to wip/history/keyword-only-arguments/audit/findings/pipe_run.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipe_signature.md b/wip/history/keyword-only-arguments/audit/findings/pipe_signature.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipe_signature.mdrename to wip/history/keyword-only-arguments/audit/findings/pipe_signature.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipelex.md b/wip/history/keyword-only-arguments/audit/findings/pipelex.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipelex.mdrename to wip/history/keyword-only-arguments/audit/findings/pipelex.mddiff --git a/wip/keyword-only-arguments/audit/findings/pipeline.md b/wip/history/keyword-only-arguments/audit/findings/pipeline.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/pipeline.mdrename to wip/history/keyword-only-arguments/audit/findings/pipeline.mddiff --git a/wip/keyword-only-arguments/audit/findings/plugins.md b/wip/history/keyword-only-arguments/audit/findings/plugins.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/plugins.mdrename to wip/history/keyword-only-arguments/audit/findings/plugins.mddiff --git a/wip/keyword-only-arguments/audit/findings/reporting.md b/wip/history/keyword-only-arguments/audit/findings/reporting.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/reporting.mdrename to wip/history/keyword-only-arguments/audit/findings/reporting.mddiff --git a/wip/keyword-only-arguments/audit/findings/runtime_bridge.md b/wip/history/keyword-only-arguments/audit/findings/runtime_bridge.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/runtime_bridge.mdrename to wip/history/keyword-only-arguments/audit/findings/runtime_bridge.mddiff --git a/wip/keyword-only-arguments/audit/findings/system.md b/wip/history/keyword-only-arguments/audit/findings/system.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/system.mdrename to wip/history/keyword-only-arguments/audit/findings/system.mddiff --git a/wip/keyword-only-arguments/audit/findings/temporal.md b/wip/history/keyword-only-arguments/audit/findings/temporal.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/temporal.mdrename to wip/history/keyword-only-arguments/audit/findings/temporal.mddiff --git a/wip/keyword-only-arguments/audit/findings/tools.md b/wip/history/keyword-only-arguments/audit/findings/tools.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/tools.mdrename to wip/history/keyword-only-arguments/audit/findings/tools.mddiff --git a/wip/keyword-only-arguments/audit/findings/tracing.md b/wip/history/keyword-only-arguments/audit/findings/tracing.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/findings/tracing.mdrename to wip/history/keyword-only-arguments/audit/findings/tracing.mddiff --git a/wip/keyword-only-arguments/audit/positional-subject-audit.md b/wip/history/keyword-only-arguments/audit/positional-subject-audit.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/positional-subject-audit.mdrename to wip/history/keyword-only-arguments/audit/positional-subject-audit.mddiff --git a/wip/keyword-only-arguments/audit/review-prompt.md b/wip/history/keyword-only-arguments/audit/review-prompt.mdsimilarity index 100%rename from wip/keyword-only-arguments/audit/review-prompt.mdrename to wip/history/keyword-only-arguments/audit/review-prompt.mddiff --git a/wip/keyword-only-arguments/autofix-review-followups.md b/wip/history/keyword-only-arguments/autofix-review-followups.mdsimilarity index 100%rename from wip/keyword-only-arguments/autofix-review-followups.mdrename to wip/history/keyword-only-arguments/autofix-review-followups.mddiff --git a/wip/keyword-only-arguments/downstream-consumer-breakage.md b/wip/history/keyword-only-arguments/downstream-consumer-breakage.mdsimilarity index 98%rename from wip/keyword-only-arguments/downstream-consumer-breakage.mdrename to wip/history/keyword-only-arguments/downstream-consumer-breakage.mdindex 3a359bf43..240618dc8 100644--- a/wip/keyword-only-arguments/downstream-consumer-breakage.md+++ b/wip/history/keyword-only-arguments/downstream-consumer-breakage.md@@ -17,7 +17,7 @@>> **Follow-up (2026-06-15e) — pipelex-worker brought into scope:** previously marked out of scope only because it pinned `pipelex` via a PyPI version (`pipelex[dynamodb,s3,temporal]==0.33.0`), not a git rev. Now aligned with the others on a new `chore/keyword-only-pipelex-rev` branch off `dev`: the PyPI pin is overridden with the `0e32c8c0` git rev via `[tool.uv.sources]` and relocked (`uv lock`: registry → git source). The worker has **no `pipelex` imports in its own source** (it just runs the installed `pipelex worker` process), so there is **no keyword-only call-site break**. Its `pipelex doctor` config-health smoke tests then failed on a *pre-existing* brittleness, not a config regression: `pipelex doctor` renders through rich and emits ANSI style/reset codes even when piped (`NO_COLOR` only drops colors, not the bold/reset), and a `\x1b[0m` between `Configuration Files` and the `✓` defeated the section regex — fixed by stripping ANSI before matching. The merged config is valid against 0.33.0 (no `ConfigValidationError`); the only residual is the expected soft `Model Deck installed for 0.32.1, current 0.33.0` warning, which the test ignores by design and does not break the worker. All three env smoke tests green. Commit `af8572a`, pushed, **[PR #23](https://github.com/Pipelex/pipelex-worker/pull/23)** opened against `dev`. `pipelex-mistralai-workflows` remains genuinely out of scope — its own mistralai-2x hold track, editable-pinned to the `../_workflows` pipelex worktree, gated until instructor #2298.-> Original release-time checklist below (the pipelex-internal keyword-only refactor is **complete** — all waves landed, guard hard-blocks; see [`../../TODOS.md`](../../TODOS.md)). Companion to the convention itself at [`../../docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md).+> Original release-time checklist below (the pipelex-internal keyword-only refactor is **complete** — all waves landed, guard hard-blocks; see [`../../../TODOS.md`](../../../TODOS.md)). Companion to the convention itself at [`../../../docs/contribute/keyword-only-arguments.md`](../../../docs/contribute/keyword-only-arguments.md).The keyword-only refactor intentionally turns multi-arg public helpers keyword-only (e.g. `save_text_to_path(text, *, path, create_directory=False)`, and on the public surface `Pipelex.make()` / `Pipelex.setup()` / `PipelexHub.setup_config()` — every argument after the first is now keyword-only). This is a deliberate breaking change, documented in the runtime `CHANGELOG.md`. Breaking changes are allowed in this workspace, but consumers must be updated in lockstep — otherwise the official examples ship broken.diff --git a/wip/keyword-only-arguments/keyword-only-arguments.html b/wip/history/keyword-only-arguments/keyword-only-arguments.htmlsimilarity index 100%rename from wip/keyword-only-arguments/keyword-only-arguments.htmlrename to wip/history/keyword-only-arguments/keyword-only-arguments.htmldiff --git a/wip/keyword-only-arguments/positional-subject-suspects.md b/wip/history/keyword-only-arguments/positional-subject-suspects.mdsimilarity index 100%rename from wip/keyword-only-arguments/positional-subject-suspects.mdrename to wip/history/keyword-only-arguments/positional-subject-suspects.mddiff --git a/wip/plugins/plugin-system-overview.html b/wip/history/plugin-system-overview.htmlsimilarity index 100%rename from wip/plugins/plugin-system-overview.htmlrename to wip/history/plugin-system-overview.htmldiff --git a/wip/pydantic-before-validator-typing.md b/wip/history/pydantic-before-validator-typing.mdsimilarity index 100%rename from wip/pydantic-before-validator-typing.mdrename to wip/history/pydantic-before-validator-typing.mddiff --git a/wip/recursivity/domain-metadata-merge.md b/wip/history/recursivity/domain-metadata-merge.mdsimilarity index 100%rename from wip/recursivity/domain-metadata-merge.mdrename to wip/history/recursivity/domain-metadata-merge.mddiff --git a/wip/recursivity/protocol-validate-pending-signatures.md b/wip/history/recursivity/protocol-validate-pending-signatures.mdsimilarity index 100%rename from wip/recursivity/protocol-validate-pending-signatures.mdrename to wip/history/recursivity/protocol-validate-pending-signatures.mddiff --git a/wip/recursivity/recursive-followups.md b/wip/history/recursivity/recursive-followups.mdsimilarity index 100%rename from wip/recursivity/recursive-followups.mdrename to wip/history/recursivity/recursive-followups.mddiff --git a/wip/recursivity/signature-taxonomy-refactor.md b/wip/history/recursivity/signature-taxonomy-refactor.mdsimilarity index 100%rename from wip/recursivity/signature-taxonomy-refactor.mdrename to wip/history/recursivity/signature-taxonomy-refactor.mddiff --git a/wip/registry/README.md b/wip/history/registry/README.mdsimilarity index 86%rename from wip/registry/README.mdrename to wip/history/registry/README.mdindex 6b7af21a8..a64ab8cb7 100644--- a/wip/registry/README.md+++ b/wip/history/registry/README.md@@ -1,6 +1,6 @@# `UsageRegistry` leak fix + distributed cost reporting-Cost reporting was reworked from a leaky per-run, in-process `UsageRegistry` buffer into an **event-sourced artifact that rides back on `PipeOutput`**. The success-path registry leak is gone by removal; a multi-worker (Temporal) run now aggregates usage from every worker into a single end-of-run cost report. A default-on `--costs` switch decouples cost collection from `--graph` over a shared event-log transport, and a cheap deterministic mock validates the distributed path (originally `--mock-inference`; since the unified dry run it is the internal `--dry-run --mock-usage` trigger — see `../dry-run-refactor/plan-unified-dry-run.md`).+Cost reporting was reworked from a leaky per-run, in-process `UsageRegistry` buffer into an **event-sourced artifact that rides back on `PipeOutput`**. The success-path registry leak is gone by removal; a multi-worker (Temporal) run now aggregates usage from every worker into a single end-of-run cost report. A default-on `--costs` switch decouples cost collection from `--graph` over a shared event-log transport, and a cheap deterministic mock validates the distributed path (originally `--mock-inference`; since the unified dry run it is the internal `--dry-run --mock-usage` trigger — see `../../dry-run-refactor/plan-unified-dry-run.md`).Shipped in **PR #967** on `fix/For-API-update`, with the companion rename **#968** (`GraphContext → TraceContext`, `is_generate_costs → is_generate_usage`).@@ -24,5 +24,5 @@ Shipped in **PR #967** on `fix/For-API-update`, with the companion rename **#968The cost-reporting half mirrors graph-spec assembly, documented in the distributed-execution feature:-- [`../distributed-execution/tracing-cost-reporting.md`](../distributed-execution/tracing-cost-reporting.md) — as-built tracing & cost reporting (T2 cross-worker cost-report assembly = **FIXED** by this work).-- [`../distributed-execution/README.md`](../distributed-execution/README.md) — the priority plan (P0.1 `--mock-inference` and P1 cost-report assembly both **shipped** here).+- [`../../distributed-execution/tracing-cost-reporting.md`](../../distributed-execution/tracing-cost-reporting.md) — as-built tracing & cost reporting (T2 cross-worker cost-report assembly = **FIXED** by this work).+- [`../../distributed-execution/README.md`](../../distributed-execution/README.md) — the priority plan (P0.1 `--mock-inference` and P1 cost-report assembly both **shipped** here).diff --git a/wip/registry/cost-report-deferred-decisions.md b/wip/history/registry/cost-report-deferred-decisions.mdsimilarity index 100%rename from wip/registry/cost-report-deferred-decisions.mdrename to wip/history/registry/cost-report-deferred-decisions.mddiff --git a/wip/registry/cost-report-submitter-helper-handoff.md b/wip/history/registry/cost-report-submitter-helper-handoff.mdsimilarity index 100%rename from wip/registry/cost-report-submitter-helper-handoff.mdrename to wip/history/registry/cost-report-submitter-helper-handoff.mddiff --git a/wip/registry/cost-reporting-overview.html b/wip/history/registry/cost-reporting-overview.htmlsimilarity index 100%rename from wip/registry/cost-reporting-overview.htmlrename to wip/history/registry/cost-reporting-overview.htmldiff --git a/wip/registry/deferred-followups.md b/wip/history/registry/deferred-followups.mdsimilarity index 94%rename from wip/registry/deferred-followups.mdrename to wip/history/registry/deferred-followups.mdindex 113c89165..1e8eb45ac 100644--- a/wip/registry/deferred-followups.md+++ b/wip/history/registry/deferred-followups.md@@ -18,7 +18,7 @@ Two further deferred items — both *design decisions* rather than follow-up wor- **Review item T5 — `wf_pipe_router.py` setup-failure `except` doesn't restore `job_metadata.trace_context`.** On a tracer-setup failure the pipe can run with a `tracer_key` pointing at a closed tracer. Pre-existing latent issue (not introduced by this work; Temporal is unshipped — see [[project_temporal_not_shipped]]). Flag-and-fix candidate, parked.-- **T3 — request-scoped tracing state instead of the process-singleton `ReportingManager`.** The deeper refactor in the distributed-execution track ([`../distributed-execution/tracing-cost-reporting.md`](../distributed-execution/tracing-cost-reporting.md) T3). Removing the submitter-side `UsageRegistry` shrank the singleton's surface, but the per-context `_event_log_contexts` dict on a process-global manager remains. Open follow-up.+- **T3 — request-scoped tracing state instead of the process-singleton `ReportingManager`.** The deeper refactor in the distributed-execution track ([`../../distributed-execution/tracing-cost-reporting.md`](../../distributed-execution/tracing-cost-reporting.md) T3). Removing the submitter-side `UsageRegistry` shrank the singleton's surface, but the per-context `_event_log_contexts` dict on a process-global manager remains. Open follow-up.**Facet flagged on PR #967 (codex, P1) — activity usage writes can mutate a workflow-registered buffer.** In a *single-process* Temporal deployment (one worker hosting both `WfPipeRouter` workflows and the inference activities), the workflow registers its `BufferingEventLog` in the process-global `ReportingManager._event_log_contexts`. An inference activity in the same process then hits the fast path (`_emit_via_registered_context`) and appends to the workflow's in-memory buffer — an activity side effect that is **not** part of Temporal's deterministic replay (the activity *result* replays from history, but the buffer append does not), so on replay the later drain/flush can diverge or drop usage. **Why this is deferred, not patched on this PR:** (1) it is *pre-existing* — the fast path + per-context registration predate this work (the registry track kept the emit core unchanged; it only removed the submitter-side registry), so PR #967 neither introduced nor worsened it; (2) the **recommended split router+runner topology does not hit it** — activities run on the runner process, which never registered the workflow's buffer, so they correctly take the per-process activity-log fallback; (3) the clean fix is request-scoped tracing state (this T3 refactor) or making activities always bypass workflow-registered buffers — bolting Temporal-awareness (`activity.in_activity()`) into the generic, non-Temporal `ReportingManager` would be a layering violation; (4) Temporal is not shipped to prod. Pick this up with the T3 refactor.@@ -36,8 +36,8 @@ These were found by the gstack `/review` adversarial pass (Codex + Claude). They> **All items below are closed by the unified dry run** (`wip/dry-run-refactor/design-unified-dry-run.md` + `plan-unified-dry-run.md`): `--mock-inference` is removed as a mode; the reportable-usage capability is the internal `CogtRunParams.is_mock_usage` sub-flag of DRY; `MockInferenceUnsupportedError` and the per-leaf guards are deleted (dry run covers every leaf). Kept as the historical record.-- **LLM leaf only.** `--mock-inference` mocks the LLM inference leaf (`llm_gen_text`/`object`/`object_list`). Image-gen / extract / search **fail loud** with `MockInferenceUnsupportedError` (their output is stored *above* the leaf by `generated_content_factory`, so a leaf-level mock would push synthetic data through the storage path — whereas `ContentGeneratorDry` short-circuits storage). Full per-operator synthetic-output coverage comes via [`../dry-run-refactor/followup-leaf-run-mode-mock.md`](../dry-run-refactor/followup-leaf-run-mode-mock.md) B2, which replaces each hard guard with a real synthetic-output branch.+- **LLM leaf only.** `--mock-inference` mocks the LLM inference leaf (`llm_gen_text`/`object`/`object_list`). Image-gen / extract / search **fail loud** with `MockInferenceUnsupportedError` (their output is stored *above* the leaf by `generated_content_factory`, so a leaf-level mock would push synthetic data through the storage path — whereas `ContentGeneratorDry` short-circuits storage). Full per-operator synthetic-output coverage comes via [`../../dry-run-refactor/followup-leaf-run-mode-mock.md`](../../dry-run-refactor/followup-leaf-run-mode-mock.md) B2, which replaces each hard guard with a real synthetic-output branch.- **Main `run` subcommands only.** The flag is on `pipelex run pipe|method|bundle`, not the agent CLI. The mechanism (`JobMetadata.is_mock_inference` + leaf branch + `PipelexRunner`) is surface-agnostic, so the agent CLI can adopt it trivially when needed.-- **`is_mock_inference` fate after the dry-run-refactor follow-up — SETTLED 2026-06-10: fully retired as a mode, capability kept as the internal `is_mock_usage` DRY sub-flag (supersedes the interim D8 keep).** Original framing — decided 2026-06-06: build the interim flag now (Phase 5 is the follow-up's B1 core — a reusable leaf-level dry helper), settle retirement at B2. Open sub-decision: *fully retire* `--mock-inference` (DRY-on-Temporal covers cross-worker dispatch + `tokens_usages` assembly once it dispatches) vs *keep a thin reportable-mock* (DRY emits zero-token usage → suppressed report, so the cheap *rendered* cost-report validation — Tier 8b — is unique to a non-zero mock). Decide at B2 time. See [`../dry-run-refactor/followup-leaf-run-mode-mock.md`](../dry-run-refactor/followup-leaf-run-mode-mock.md).+- **`is_mock_inference` fate after the dry-run-refactor follow-up — SETTLED 2026-06-10: fully retired as a mode, capability kept as the internal `is_mock_usage` DRY sub-flag (supersedes the interim D8 keep).** Original framing — decided 2026-06-06: build the interim flag now (Phase 5 is the follow-up's B1 core — a reusable leaf-level dry helper), settle retirement at B2. Open sub-decision: *fully retire* `--mock-inference` (DRY-on-Temporal covers cross-worker dispatch + `tokens_usages` assembly once it dispatches) vs *keep a thin reportable-mock* (DRY emits zero-token usage → suppressed report, so the cheap *rendered* cost-report validation — Tier 8b — is unique to a non-zero mock). Decide at B2 time. See [`../../dry-run-refactor/followup-leaf-run-mode-mock.md`](../../dry-run-refactor/followup-leaf-run-mode-mock.md).diff --git a/wip/registry/usage-reporting-without-cost.md b/wip/history/registry/usage-reporting-without-cost.mdsimilarity index 100%rename from wip/registry/usage-reporting-without-cost.mdrename to wip/history/registry/usage-reporting-without-cost.mddiff --git a/wip/runtime-bridge/runtime-bridge.html b/wip/history/runtime-bridge.htmlsimilarity index 100%rename from wip/runtime-bridge/runtime-bridge.htmlrename to wip/history/runtime-bridge.htmldiff --git a/wip/signature-based-validation/signature-based-validation-pr-story.html b/wip/history/signature-based-validation/signature-based-validation-pr-story.htmlsimilarity index 100%rename from wip/signature-based-validation/signature-based-validation-pr-story.htmlrename to wip/history/signature-based-validation/signature-based-validation-pr-story.htmldiff --git a/wip/signature-based-validation/signature-based-validation.md b/wip/history/signature-based-validation/signature-based-validation.mdsimilarity index 100%rename from wip/signature-based-validation/signature-based-validation.mdrename to wip/history/signature-based-validation/signature-based-validation.mddiff --git a/wip/recursivity/signature-taxonomy-refactor.html b/wip/history/signature-taxonomy-refactor.htmlsimilarity index 100%rename from wip/recursivity/signature-taxonomy-refactor.htmlrename to wip/history/signature-taxonomy-refactor.htmldiff --git a/wip/tests/add-tests-branch-overview.html b/wip/history/tests/add-tests-branch-overview.htmlsimilarity index 100%rename from wip/tests/add-tests-branch-overview.htmlrename to wip/history/tests/add-tests-branch-overview.htmldiff --git a/wip/tests/deferred-source-bugs-pinned-by-tests.md b/wip/history/tests/deferred-source-bugs-pinned-by-tests.mdsimilarity index 100%rename from wip/tests/deferred-source-bugs-pinned-by-tests.mdrename to wip/history/tests/deferred-source-bugs-pinned-by-tests.mddiff --git a/wip/tests/missing-tests-menu.md b/wip/history/tests/missing-tests-menu.mdsimilarity index 100%rename from wip/tests/missing-tests-menu.mdrename to wip/history/tests/missing-tests-menu.mddiff --git a/wip/runtime-bridge/distributed-cost-reporting-test-coverage.md b/wip/runtime-bridge/distributed-cost-reporting-test-coverage.mdindex 9f11e526b..619d532eb 100644--- a/wip/runtime-bridge/distributed-cost-reporting-test-coverage.md+++ b/wip/runtime-bridge/distributed-cost-reporting-test-coverage.md@@ -210,5 +210,5 @@ The aggregator and renderer themselves are lossless — all risk lives in the ca- [`cost-reporting-validation-prompts.md`](cost-reporting-validation-prompts.md) — operator cheat-sheet of `/temporal-e2e-validate` prompts that drive the Tier 8b arms this audit motivated.- `../observer-and-telemetry/` — sibling tracing/telemetry follow-ups.-- `docs/.../tracing-cost-reporting.md` (R2 documentation) and the `wip/registry/cost-report-deferred-decisions.md` deferred items (e.g. `tracing_config.is_enabled=false` + `--costs` → silent no-report).+- `docs/.../tracing-cost-reporting.md` (R2 documentation) and the [`wip/history/registry/cost-report-deferred-decisions.md`](../history/registry/cost-report-deferred-decisions.md) deferred items (e.g. `tracing_config.is_enabled=false` + `--costs` -> silent no-report).- This audit was produced cross-checking three independent code sweeps (emission, aggregation, test inventory); the file:line anchors above are the load-bearing evidence — re-verify any that look stale before building on them.