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.
Autofix (#1027)
Louis Choquel95cfe0859631
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex be38746cd..649daac2b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,6 +1,13 @@# Changelog+## [Unreleased]+### Added++- **Agent bundle fixer:** Added `pipelex-agent fix bundle`, a deterministic in-place fixer over the shared validation fix loop. The command supports `--format`/`--error-format`, repeatable `--select`/`--ignore` fix-rule filters, `--allow-signatures`, `--max-iterations`, and the same bundle-file or directory resolution as `pipelex-agent validate bundle`. Successful fix results report `pending_signatures` and `is_runnable`; by default the command exits non-zero when a fixed bundle remains valid-but-not-runnable.+- **Human bundle fixer:** Added `pipelex fix bundle`, the human counterpart of the agent fixer over the same fix loop, with Rich-rendered output naming every change made (fix descriptions, files written, iteration count), the same `--select`/`--ignore`/`--allow-signatures`/`--max-iterations` options, and the same bundle-file or directory resolution as `pipelex validate bundle`. A new `--diff` flag previews the changes as a unified diff without writing anything — the real fix loop runs against a temp-copy sandbox, and exit codes keep the verdict semantics so `--diff` answers "would it converge?".+- **Suggested fixes surfaced in `pipelex validate`:** When a validation error has a deterministic safe fix, the human error output now shows a per-error `💡 Suggested fix:` line and ends with an actionable footer naming the exact `pipelex fix bundle` command (echoing the invocation's `-L` dirs) in place of the generic tip.+- **`suggested_fix` field in `/validate` payloads:** Each validation error that has a deterministic safe fix now carries an additive structured `suggested_fix` object — `fix_code` (the kebab-case rule id), `description` (the author-facing 💡 text), `safety` (`safe`/`unsafe`), optional `source` file, and `ops` (the semantic patch operations) — on every `validation_errors[]` item, both in the `pipelex-agent validate`/`fix` JSON envelopes and in the API `/validate` response body. This is the machine-actionable counterpart of the 💡 line, letting a software consumer apply the fix directly from the structured payload.- **Smart Inputs (signature-driven input shaping):** Inputs are now interpreted top-down against the pipe's declared input signature rather than bottom-up from their shape alone.- Bare values (strings, numbers, booleans, dicts, lists) are automatically shaped into the declared concept (e.g., a bare string becomes a `legal.Question`, not a generic `native.Text`).- Lists shape element-wise into the declared item concept; single values auto-wrap into lists where required, and empty lists are now legal.@@ -12,6 +19,11 @@- **CLI `--explicit` flag:** Added `--explicit` to `pipelex build inputs` and `pipelex-agent inputs` to generate the legacy `{"concept", "content"}` envelope templates.### Changed++- **Human validation error rendering routed through the shared structured items:** `pipelex validate`'s error details now render from the same `ValidationErrorItem`s the agent CLI and API emit, which surfaces information the old renderer silently dropped: pipe-factory errors (e.g. an unknown concept) get their own section, a parse-level failure (e.g. a TOML syntax error) now shows its message instead of no detail at all, and pipe validation errors name their source file. The dry-run message remains visible alongside categorized errors.+- **Validation error messages now speak MTHDS author syntax:** Pipe validation errors state the problem and the fix the way an author writes them — a sequence output-multiplicity mismatch now reads "declares its output as 'StoryIdea', but its last step yields 'StoryIdea[]'. Update the sequence's output to 'StoryIdea[]'", and an input-type mismatch reads "input 'dish' is declared as 'Number' but its step needs 'Text'. Update the input to 'Text'" — instead of leaking Python internals (`multiplicity=None`, `Concept(...)`/`PresenceMarker` reprs). The misleading `(required: […], provided: …)` suffix is suppressed for multiplicity errors (where both sides are identical by definition) and rendered as joined author-syntax refs — never Python list-repr brackets — elsewhere.+- **Agent `validate` / `fix` output renders prose, not a JSON dump:** `pipelex-agent validate bundle` and `pipelex-agent fix bundle` markdown output now renders validation errors as category-grouped prose (a humanized title, identity fields, the message, and a `💡 Suggested fix:` line) followed by a fix-aware footer naming the exact `pipelex-agent fix bundle` command when a safe fix exists — mirroring the human panel. The machine-facing JSON stream (`--format json`) is unchanged, so software consumers keep branching on the same structured fields.+- **Clean validation summary message on every surface:** The top-level error `message` (agent JSON, the API `/validate` body) is now a clean, author-facing summary derived from the structured errors, instead of the raw pydantic dump (`Validation error(s): … Value errors: '<field>': Value error, …`). The API's opt-in invalid-verdict `rendered_markdown` now carries the same per-error `💡 Suggested fix` prose as the CLI. A still-invalid fix that stops with no progress now names the re-proposed fix in author terms rather than dumping an internal fingerprint string.- (Breaking) **Input templates default to "light" shape:** `pipelex build inputs` and `pipelex-agent inputs` now generate light templates by default, outputting the bare values expected by the signature rather than the verbose `{"concept", "content"}` envelopes. TOML templates include the declared concept as a `# concept: ...` comment.- (Breaking) **Structure-field `type = "date"` behavior:** A `date` field now generates a `datetime.date` (JSON schema `format: date`), preventing LLMs from hallucinating times for calendar dates. A new `type = "datetime"` field handles full timestamps (`format: date-time`), and default-value validation now rejects a `datetime` default on a `date` field.- (Breaking) **Strict input validation:** Undeclared input names are now a hard error (previously silently ignored), and top-level `null` values are rejected—absence must be expressed by omitting the key.@@ -20,6 +32,9 @@- **Documentation overhaul:** Updated `provide-inputs.md`, `executing-pipelines.md`, and `native-concepts.md` for the Smart Inputs paradigm, leading with the bare-value approach and demoting the envelope format to an escape hatch.### Fixed++- **Human CLI `~` expansion:** `pipelex validate bundle` (and the new `pipelex fix bundle`) now expand `~` in the bundle path and `-L/--library-dir` values, matching the agent CLI.+- **Validate telemetry label:** the `CLI_COMMAND` telemetry tag for `pipelex validate` subcommands no longer double-suffixes (previously "validate bundle bundle").- **Silent mistyping of inputs:** Providing a bare string for a refined text concept (e.g., `legal.Question`) no longer silently degrades the type to a generic `native.Text`; the declared concept type is now retained.- **TOML inline table formatting:** Light templates now use inline tables for structured values, preventing trailing scalars from being swallowed into `[sections]`.diff --git a/docs/errors/execution-and-runtime.md b/docs/errors/execution-and-runtime.mdindex 047664dd9..36c48e4c4 100644--- a/docs/errors/execution-and-runtime.md+++ b/docs/errors/execution-and-runtime.md@@ -26,6 +26,8 @@ own page. Classes are grouped by subsystem.## Pipeline execution+- [`FixTransactionError`](fix-transaction-error.md) — Fix transaction+- [`FixWriteConflictError`](fix-write-conflict-error.md) — Fix write conflict- [`JobMetadataError`](job-metadata-error.md) — Job metadata- [`PipeExecutionError`](pipe-execution-error.md) — Pipe execution- [`PipeIOContractError`](pipe-io-contract-error.md) — Pipe IO contractdiff --git a/docs/errors/fix-transaction-error.md b/docs/errors/fix-transaction-error.mdnew file mode 100644index 000000000..9b7f8f9a0--- /dev/null+++ b/docs/errors/fix-transaction-error.md@@ -0,0 +1,21 @@+---+title: "Fix transaction"+description: "Reference for the `FixTransactionError` Pipelex error class."+---++<!-- pipelex:generated -->++# Fix transaction++An autofix multi-file commit failed and could not be fully rolled back.++| Field | Value |+|---|---|+| `error_type` | `FixTransactionError` |+| `title` | Fix transaction |+| `type_uri` | `https://docs.pipelex.com/latest/errors/fix-transaction-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.pipeline.exceptions` |+| Parent class | [`PipelexUnexpectedError`](pipelex-unexpected-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/fix-write-conflict-error.md b/docs/errors/fix-write-conflict-error.mdnew file mode 100644index 000000000..718ceaffb--- /dev/null+++ b/docs/errors/fix-write-conflict-error.md@@ -0,0 +1,21 @@+---+title: "Fix write conflict"+description: "Reference for the `FixWriteConflictError` Pipelex error class."+---++<!-- pipelex:generated -->++# Fix write conflict++A bundle changed after autofix read it but before the atomic commit.++| Field | Value |+|---|---|+| `error_type` | `FixWriteConflictError` |+| `title` | Fix write conflict |+| `type_uri` | `https://docs.pipelex.com/latest/errors/fix-write-conflict-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.pipeline.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/features/cli.md b/docs/features/cli.mdindex 4902e910d..82fad1f44 100644--- a/docs/features/cli.md+++ b/docs/features/cli.md@@ -21,6 +21,7 @@ The `pipelex` CLI is the primary tool for working with Pipelex methods. It cover| **`pipelex doctor`** | Check configuration health and suggest fixes || **`pipelex build`** | AI-powered method generation from natural language requirements || **`pipelex validate`** | Check pipeline syntax, structure, and run dry-run validation |+| **`pipelex fix`** | Apply deterministic safe fixes to a bundle and re-validate (with `--diff` preview) || **`pipelex run`** | Execute pipelines from bundle files or libraries || **`pipelex graph`** | Generate and render execution graphs || **`pipelex show`** | Display configuration, pipes, and list AI models |@@ -49,6 +50,7 @@ The `pipelex-agent` CLI is a machine-first interface designed for automated envi| `init` | Non-interactive configuration setup (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) || `run` | Execute a pipeline (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) || `validate` | Validate pipes, bundles, or methods (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |+| `fix` | Apply deterministic safe fixes to a bundle in place and re-validate (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) || `fmt` | Format `.mthds`, `.toml`, or `.plx` files in-place || `lint` | Lint files for errors || `inputs` | Generate example input JSON for a pipe |diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex f68c41527..764a19bbb 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -18,7 +18,7 @@ It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which its## Commands Overview-The agent CLI mirrors the main CLI's subcommand structure for `run`, `validate`, and `inputs`, each with `pipe`, `bundle`, and `method` subcommands.+The agent CLI mirrors the main CLI's subcommand structure for `run`, `validate`, and `inputs`, each with `pipe`, `bundle`, and `method` subcommands. It also provides `fix bundle` for deterministic in-place repairs.### Run@@ -79,6 +79,26 @@ For `bundle`, additional options are available:!!! note "Advisory warnings on validate"Whole-bundle validate surfaces (`validate bundle`, `validate method`) also carry a `warnings` array — advisory optionality lints on a VALID bundle that never flip the verdict or the exit code. Each entry has the **same shape as a validation error item** (`category`, `error_type`, `pipe_code`, `domain_code`, `variable_names`, `message`) — this is a different shape from the `init`/`doctor` setup `warnings` (`{type, message}`) documented under Output Contract below. The first occupant is the useless-`!` lint (`optional_force_redundant`): a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report; single-pipe `validate pipe` omits it (no flow context to lint in).+### Fix++Apply deterministic safe fixes to a bundle, re-validating after each round until the bundle is valid, no applicable fix remains, or the iteration limit is reached.++```bash+pipelex-agent fix bundle <PATH> [OPTIONS]+```++**Options:**++- `--library-dir`, `-L` - Additional library directory; files in explicitly supplied directories may be fixed when an error identifies them as the source+- `--allow-signatures` - Accept `PipeSignature` placeholders during validation+- `--max-iterations` - Limit the number of validate/apply rounds+- `--select` - Apply only the named fix rule; repeat for multiple rules+- `--ignore` - Skip the named fix rule; repeat for multiple rules (`--select` and `--ignore` are mutually exclusive)+- `--format` - Success output format: `markdown` (default) or `json`+- `--error-format` - Error output format: `markdown` or `json` (defaults to `--format`'s value)++The result reports `iterations`, `fixes_applied`, `files_written`, and any `remaining_errors`. A fully valid result exits 0; a completed fix attempt that remains invalid exits 1; argument, setup, or unexpected failures exit 2.+### InputsGenerate an example inputs template for a pipe, bundle, or method. By default the template is the **light** signature-driven shape (bare values matching the pipe's declared concepts), which is exactly what `run` accepts; `--explicit` emits the ceremonial `{concept, content}` envelope form instead.@@ -120,7 +140,7 @@ These commands do not have subcommands:Commands use different stdout formats depending on their purpose:-- **Markdown or JSON**: `run`, `validate`, `init`, `models`, `check-model`, `doctor` — markdown by default, JSON with `--format json`. Error format follows `--error-format` (defaults to `--format`'s value, so `--format json` flips both).+- **Markdown or JSON**: `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor` — markdown by default, JSON with `--format json`. Error format follows `--error-format` (defaults to `--format`'s value, so `--format json` flips both).- **JSON or raw TOML**: `inputs` — structured JSON via `agent_success()` by default (`--format json`), or the raw TOML template printed directly to stdout with `--format toml`- **Raw TOML**: `concept`, `pipe` — TOML text printed directly to stdout- **Passthrough**: `fmt`, `lint` — raw `plxt` outputdiff --git a/docs/tools/cli/fix.md b/docs/tools/cli/fix.mdnew file mode 100644index 000000000..65fa46b06--- /dev/null+++ b/docs/tools/cli/fix.md@@ -0,0 +1,67 @@+---+description: "Automatically fix validation errors in your .mthds bundles with deterministic, safe fixes — preview with --diff or apply in place."+---++# Fix Commands++Apply deterministic, safe fixes to a bundle and re-validate until it is valid.++```bash+pipelex fix bundle ... # Fix a bundle file or directory in place+```++When `pipelex validate` reports errors that have a deterministic fix, each one carries a `💡 Suggested fix:` line and the output ends with the exact `pipelex fix bundle` command to run. The fix command runs a validate → apply safe fixes → re-validate loop until the bundle is valid, out of fixes, or the iteration cap is reached — and names every change it makes.++## Fix Bundle++```bash+pipelex fix bundle <PATH>+```++Fixes a bundle file (`.mthds`) or a pipeline directory in place. When a directory is given, the bundle file is auto-detected inside it — exactly the same resolution as `pipelex validate bundle`, so fix patches exactly what validate judged.++**Arguments:**++- `PATH` - Path to a `.mthds` bundle file or a directory containing one++**Options:**++- `--library-dir`, `-L` - Directory to search for additional pipe definitions. Can be specified multiple times. Files under these directories are inside the fix write scope; files loaded any other way are never written.+- `--diff` - Preview: show the changes as a unified diff without writing any file. Exit codes keep the same verdict semantics, so `--diff` answers "would it converge?"+- `--select` - Only apply the named fix rule code (repeatable)+- `--ignore` - Skip the named fix rule code (repeatable; mutually exclusive with `--select`)+- `--max-iterations` - Maximum fix-apply rounds before reporting non-convergence+- `--allow-signatures` - Accept `PipeSignature` placeholders in the dependency graph (lenient mode). See [Signature Pipes](../../building-methods/pipes/signature-pipes.md).++**Examples:**++```bash+# Fix a bundle file in place+pipelex fix bundle my_pipeline.mthds++# Preview the changes without writing anything+pipelex fix bundle my_pipeline.mthds --diff++# Fix a pipeline directory (auto-detects the bundle file)+pipelex fix bundle pipelines/invoice_processor/++# Fix with additional library directories (also widens the write scope)+pipelex fix bundle my_bundle.mthds -L ./shared_pipes++# Only apply one fix rule+pipelex fix bundle my_bundle.mthds --select match-sequence-output+```++## Exit Codes++- `0` - The bundle is valid after the run (fixed, or already valid)+- `1` - Negative verdict: the bundle is still invalid, or valid but not runnable (pending `PipeSignature` placeholders without `--allow-signatures`)+- `2` - No verdict: bad path, ambiguous bundle directory, invalid rule filter, or an unexpected failure++## What Gets Fixed++Only fixes classified as SAFE are applied — deterministic corrections derived from the structured validation errors, never from guesswork. Errors without a safe deterministic fix are left in place and reported as remaining errors. The available fix rule codes (for `--select`/`--ignore`) are listed in the error message when you pass an unknown code.++## Related Documentation++- [Validate Commands](validate.md) - Where suggested fixes are surfaceddiff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex 13e473e13..fbc0870dc 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -16,6 +16,7 @@ The Pipelex CLI is organized into several command groups:| [**init**](init.md) | Initialize Pipelex configuration || [**update**](update.md) | Refresh the model deck to match the installed pipelex version || [**validate**](validate.md) | Validate configuration and pipelines |+| [**fix**](fix.md) | Apply deterministic safe fixes to a bundle and re-validate || [**show**](show.md) | Inspect configuration, pipes, and AI models || [**run**](run.md) | Execute pipelines || [**build**](build/index.md) | Generate pipelines, runners, and structures |@@ -44,6 +45,7 @@ Package manifest management currently lives in the `mthds` CLI:- Write or generate pipelines in `.mthds` files- Validate with `pipelex validate pipe your_pipe_code` or `pipelex validate bundle your_bundle.mthds` during development+ - When validation errors carry a `💡 Suggested fix:` line, apply them automatically with `pipelex fix bundle your_bundle.mthds`- Run `pipelex validate pipe --all` before committing changes3. **Running Pipelines**diff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.mdindex 8eb8a8811..8335f538f 100644--- a/docs/tools/cli/validate.md+++ b/docs/tools/cli/validate.md@@ -122,6 +122,16 @@ pipelex validate method invoice_extractorpipelex validate method invoice_extractor --pipe extract_amounts```+## Suggested Fixes++When a validation error has a deterministic safe fix, the error output includes a `💡 Suggested fix:` line describing the change, and the report ends with the exact command to apply every suggested fix automatically:++```text+💡 1 of these errors can be fixed automatically — run: pipelex fix bundle my_pipeline.mthds+```++See [Fix Commands](fix.md) for `pipelex fix bundle`, including the `--diff` preview.+## What Validation ChecksAll validation commands check:diff --git a/mkdocs.yml b/mkdocs.ymlindex 9e74b74f9..c7ced8fff 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -271,6 +271,7 @@ plugins:- tools/cli/init.md: "CLI Init"- tools/cli/update.md: "CLI Update"- tools/cli/validate.md: "CLI Validate"+ - tools/cli/fix.md: "CLI Fix"- tools/cli/run.md: "CLI Run"- tools/cli/show.md: "CLI Show"- tools/cli/pkg.md: "CLI Pkg"@@ -492,6 +493,7 @@ nav:- Init: tools/cli/init.md- Update: tools/cli/update.md- Validate: tools/cli/validate.md+ - Fix: tools/cli/fix.md- Run: tools/cli/run.md- Show: tools/cli/show.md- Pkg: tools/cli/pkg.mddiff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.pyindex 55503142d..016ec53de 100644--- a/pipelex/base_exceptions.py+++ b/pipelex/base_exceptions.py@@ -5,6 +5,7 @@ from typing import Any, ClassVarfrom pydantic import BaseModel, ConfigDict, Fieldfrom pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction+from pipelex.suggested_fix import SuggestedFixfrom pipelex.tools.misc.string_utils import pascal_case_to_kebab, pascal_case_to_sentencefrom pipelex.urls import URLs@@ -264,6 +265,14 @@ class ValidationErrorCategory(StrEnum):PIPE_VALIDATION = "pipe_validation"DRY_RUN = "dry_run"+ @property+ def is_dry_run(self) -> bool:+ match self:+ case ValidationErrorCategory.DRY_RUN:+ return True+ case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:+ return False+class ValidationErrorItem(BaseModel):"""One structured bundle-validation error, projected onto the error wire.@@ -303,6 +312,10 @@ class ValidationErrorItem(BaseModel):missing_concept_code: str | None = Nonemissing_pipe_code: str | None = Nonedeclared_concepts: list[str] | None = None+ # Structured, deterministic fix for this error, when the fix planner derived one from the+ # enriched error data. Optional and additive: non-fixable items serialize unchanged under+ # ``exclude_none``.+ suggested_fix: SuggestedFix | None = Noneclass ErrorReport(BaseModel):diff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.pyindex 8bb560002..9786aa925 100644--- a/pipelex/cli/_cli.py+++ b/pipelex/cli/_cli.py@@ -7,6 +7,7 @@ from typing_extensions import overridefrom pipelex.cli.commands.build.app import build_appfrom pipelex.cli.commands.doctor_cmd import doctor_cmd+from pipelex.cli.commands.fix.app import fix_appfrom pipelex.cli.commands.graph_cmd import graph_appfrom pipelex.cli.commands.init.command import init_cmdfrom pipelex.cli.commands.init.ui.types import InitFocus@@ -31,6 +32,7 @@ _CORE_COMMAND_ORDER: list[str] = ["update","build","validate",+ "fix","run","graph","show",@@ -227,6 +229,11 @@ app.add_typer(name="validate",help="Validate a method or pipe: static validation for syntax and dependencies, dry-run execution for logic and consistency",)+app.add_typer(+ fix_app,+ name="fix",+ help="Apply deterministic safe fixes to a bundle (.mthds) and re-validate until valid",+)app.add_typer(run_app, name="run", help="Run a method or pipe, optionally providing a specific bundle file (.mthds)")app.add_typer(graph_app, name="graph", help="Generate and render execution graphs")app.add_typer(show_app, name="show", help="Show configuration, pipes, and list AI models")diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex 8fcfc826c..28f3c9b70 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -6,7 +6,7 @@ Machine-first CLI for running and validating Pipelex method bundles (`.mthds` fiTwo independent options control the two output streams:-- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `init`, `models`, `check-model`, `doctor`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.+- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.- `--error-format markdown|json` — **error reporting** (stderr). Optional. When omitted, **inherits the value of `--format`**, so `--format json` still flips both as it did historically. Accepted by the same commands as `--format`.Only the error format is backed by a module-level `ContextVar` in `agent_output.py` (`_agent_cli_error_format`). The reason: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, log-level/runner validation in the app callback, and any future site in shared library/runtime code. The ContextVar lets all of them honor `--error-format` (or `--format`'s inherited value) for free. JSON is the default so errors raised before any command opts in stay machine-parseable.@@ -19,6 +19,7 @@ Markdown structure per command:- `run`: `# Pipeline run complete`, a `## Result` section (the rendered `main_stuff` markdown with `--with-memory`, otherwise the concept JSON in a fenced block), and output / graph file paths. Cost is machine-first: on the local runner, when costs are on (`--costs`, the default) and the run did reportable work (any tokens or any cost), a best-effort `cost_report` object (`{total_cost, by_model: [...]}`, real USD) rides the JSON `--with-memory` envelope — there is **no** Rich cost table on stderr (unlike the human `pipelex run` CLI). The markdown renderer ignores the `cost_report` key, so it is JSON-only. A free/zero-price model still reports its token usage (with `total_cost` 0). The `cost_report` is **absent** when the run did no reportable work (dry runs), when `--no-costs` is passed, on the API-runner path (which does not assemble local usage), or if cost-summary aggregation fails (caught and skipped so it never fails an otherwise-successful run) — so consumers must treat it as optional.- `validate`: `# Validation passed`, the bundle path when relevant, and a list of validated pipes with their status. Every entry in `validated_pipes` (markdown and JSON) identifies its pipe by the namespaced `pipe_ref` (`domain.code`) — the same unambiguous identity across `validate all`, `validate bundle`, and `validate pipe`, so the same pipe is never reported under two identifiers. `validate bundle`, `validate method`, and `validate all` carry `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), namespaced by `pipe_ref` — rendered as a "Pending signatures" section in markdown. They also carry a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown adds an explicit plain-English runnability verdict on those surfaces: a complete bundle/library states it is runnable, while one with pending signatures states it is NOT yet runnable immediately above the verbatim "Pending signatures" heading. These whole-bundle/whole-library surfaces are **strict by default**: they exit non-zero on `not is_runnable` unless `--allow-signatures` is passed (which both tolerates the placeholders for the exit code and mock-runs the signature pipes in the sweep). Single-pipe surfaces make no library-wide runnability claim and never gate the exit code on it: bare `validate pipe <code>` omits the key and emits no verdict, while `validate bundle`/`validate method` with `--pipe` still surface the library-wide `pending_signatures` for information but do not gate on it (the requested slice can be fully implemented even when unrelated placeholders remain elsewhere).+- `fix`: `# Fix applied - bundle is valid` after one or more fixes, `# Bundle already valid` when the loop had nothing to apply, or `# Bundle valid but not runnable` when pending `PipeSignature` placeholders remain. The JSON success envelope carries `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written`, `remaining_errors`, and, on successful validation, `pending_signatures` plus `is_runnable`. Whole-bundle fix runs are strict by default: they emit the success envelope but exit 1 on `not is_runnable` unless `--allow-signatures` is passed. A still-invalid verdict exits 1 via `FixBundleError` on stderr with the same structured result fields plus any `bail_reason`.- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.@@ -56,6 +57,9 @@ commands/bundle_cmd.py # validate bundle — validate bundle file/directory (+ --graph)method_cmd.py # validate method — validate installed method_validate_core.py # Shared validation logic+ fix/ # fix — deterministic in-place bundle fixes+ app.py # fix_app Typer, subcommand registration+ bundle_cmd.py # fix bundle — run validate/fix/re-validate loopinputs/ # inputs — generate example input JSONapp.py # inputs_app Typer, subcommand registrationpipe_cmd.py # inputs pipe — inputs for a pipe by code@@ -80,6 +84,7 @@ commands/| `init` | Initializes Pipelex configuration (non-interactive). Defaults to project `.pipelex/` at detected project root. Use `--global`/`-g` to target `~/.pipelex/`. Accepts `--config`/`-c` with inline JSON or file path for backends, routing, telemetry, and gateway terms. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). || `run` | Executes a pipeline (pipe\|bundle\|method subcommands), returns main_stuff + working_memory. Graph visualizations on by default (`--no-graph` to disable). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). || `validate` | Dry-runs pipes/bundles/methods (pipe\|bundle\|method subcommands), returns validation status per pipe. Bundle subcommand supports `--graph` for graph visualization (with `--graph-format` for the graph renderer). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |+| `fix` | Applies deterministic safe fixes to a bundle file or directory (`fix bundle`) and re-validates until valid, out of fixes, or max iterations. Supports `--allow-signatures`, `--select`, `--ignore`, `--max-iterations`, and `-L/--library-dir`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). || `fmt` | Formats a .mthds/.toml/.plx file in-place (delegates to plxt) || `lint` | Lints a .mthds/.toml/.plx file for errors (delegates to plxt) || `inputs` | Generates an example inputs template for a pipe/bundle/method (pipe\|bundle\|method subcommands). `--format json\|toml` (template serialization, default: json — NOT the markdown\|json pair); `toml` prints raw TOML to stdout |@@ -91,7 +96,7 @@ commands/## Key Patterns-- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `_format_init_markdown` (`init_cmd.py`).+- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).- **Error classification**: Each error type maps to a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. See `AGENT_ERROR_HINTS` dict in `agent_output.py`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py`.- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.- **Async core**: Run and validate are async — commands use `asyncio.run()`.diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.pyindex bd8d7b0a5..9e11a6305 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -14,6 +14,7 @@ from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_efrom pipelex.cli.agent_cli.commands.check_model_cmd import agent_check_model_cmdfrom pipelex.cli.agent_cli.commands.concept_cmd import concept_cmdfrom pipelex.cli.agent_cli.commands.doctor_cmd import agent_doctor_cmd+from pipelex.cli.agent_cli.commands.fix.app import fix_appfrom pipelex.cli.agent_cli.commands.fmt_cmd import fmt_cmdfrom pipelex.cli.agent_cli.commands.init_cmd import agent_init_cmdfrom pipelex.cli.agent_cli.commands.inputs.app import inputs_app@@ -35,6 +36,7 @@ class PipelexAgentCLI(TyperGroup):"init","run","validate",+ "fix","fmt","lint","inputs",@@ -133,6 +135,7 @@ def app_callback(app.command(name="init", help="Initialize Pipelex configuration (non-interactive)")(agent_init_cmd)app.add_typer(run_app, name="run", help="Execute a pipeline and output JSON results")app.add_typer(validate_app, name="validate", help="Validate a pipe, bundle, or all pipes and output JSON results")+app.add_typer(fix_app, name="fix", help="Fix a bundle file or pipeline directory in place")app.command(name="fmt", help="Format a .mthds, .toml, or .plx file in-place")(fmt_cmd)app.command(name="lint", help="Lint a .mthds, .toml, or .plx file")(lint_cmd)app.add_typer(inputs_app, name="inputs", help="Generate example input JSON for a pipe")diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex a8d1c66e4..12e8cc5b4 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -23,13 +23,15 @@ import tracebackfrom collections.abc import Callablefrom contextvars import ContextVarfrom enum import StrEnum+from pathlib import Pathfrom typing import Any, NoReturn, castimport typer-from pipelex.base_exceptions import PipelexError, iter_cause_chain+from pipelex.base_exceptions import PipelexError, ValidationErrorItem, iter_cause_chainfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.validation_errors import build_validation_error_items+from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, format_validation_error_items_markdownfrom pipelex.tools.misc.json_utils import clean_json_dumps# Module-level capture for setup-time warnings (currently used by RemoteConfigStaleWarning).@@ -107,6 +109,7 @@ AGENT_ERROR_HINTS: dict[str, str] = {),# Validation errors"PipeValidationError": "Check pipe inputs, outputs, and concept references for consistency",+ "FixBundleError": "Inspect remaining_errors and bail_reason, adjust the bundle, then run fix or validate again",# Execution errors"PipeExecutionError": "A pipe input validation failed during pipeline execution. Check the error message for the failing model and field.",# File/input errors@@ -158,6 +161,7 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {# input = agent can fix (bad .mthds, wrong args, bad JSON)"ModelChoiceNotFoundError": "input","PipeValidationError": "input",+ "FixBundleError": "input","FileNotFoundError": "input","JSONDecodeError": "input","JsonTypeError": "input",@@ -441,3 +445,74 @@ def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:fallback_message=exc.message,)return [item.model_dump(mode="json", exclude_none=True) for item in items]+++def _render_validate_bundle_markdown(+ items: list[ValidationErrorItem],+ *,+ bundle_path: Path,+ library_dirs: list[Path] | None,+ allow_signatures: bool,+) -> str:+ """Compose the agent ``validate`` failure markdown: heading, bundle, prose items, fix-aware footer.++ Mirrors the human ``handle_validate_bundle_error`` panel: the structured items become prose+ (via the shared :func:`format_validation_error_items_markdown`) rather than a JSON dump, and+ the footer either names the exact ``pipelex-agent fix bundle`` command when items carry a+ suggested fix, or points at the messages above when nothing is auto-fixable. Doc/Discord+ links are deliberately dropped — they are noise for an LLM fixing a ``.mthds`` file.+ """+ lines: list[str] = ["# Bundle validation failed", "", f"**Bundle:** `{bundle_path}`", "", format_validation_error_items_markdown(items)]++ # A hint needs an action behind it (disease E): when items carry a suggested fix, name the exact+ # fix command — same predicate and command shape as the human footer — instead of the boilerplate+ # "check the validation_errors array" hint that the JSON envelope keeps.+ fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs)+ if fixable_count:+ fix_command = build_fix_command("pipelex-agent", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)+ lines += ["", f"💡 {fixable_count} of these errors can be fixed automatically — run: `{fix_command}`"]+ else:+ lines += ["", "💡 These errors have no automatic fix — review the messages above and edit the bundle."]+ return "\n".join(lines)+++def agent_error_validate_bundle(+ exc: ValidateBundleError,+ *,+ bundle_path: Path,+ library_dirs: list[Path] | None = None,+ allow_signatures: bool = False,+) -> NoReturn:+ """Emit an agent-CLI bundle-validation failure to stderr, format-aware, and exit 1.++ The dedicated dispatcher for the ``validate`` invalid verdict (the sibling of+ :func:`agent_error` for this one error type). It keeps the two streams honest to the+ workspace's "format follows consumer" doctrine:++ - **markdown** renders the structured items as prose with per-item ``💡 Suggested fix`` lines+ and a fix-aware footer, mirroring the human ``handle_validate_bundle_error`` panel;+ - **JSON** emits the *exact same* structured envelope as before — ``is_valid`` / ``bundle_path``+ / ``validation_errors`` — because software consumers (hooks pin ``--format json``) branch on+ those structured fields; the machine contract must not change.++ Args:+ exc: The bundle-validation failure to report.+ bundle_path: The bundle file / pipeline directory that failed validation.+ library_dirs: The ``-L/--library-dir`` values, echoed into the markdown fix-command footer.+ allow_signatures: Whether the invocation accepted ``PipeSignature`` placeholders; echoed into+ the markdown fix-command footer so the suggested fix keeps the same leniency.+ """+ match get_agent_cli_error_format():+ case CliOutputFormat.JSON:+ _agent_error_json(+ exc.message,+ error_type="ValidateBundleError",+ cause=exc,+ extra={"is_valid": False, "bundle_path": str(bundle_path), "validation_errors": extract_validation_errors(exc)},+ exit_code=1,+ )+ case CliOutputFormat.MARKDOWN:+ items = list(exc.to_error_report().validation_errors or [])+ markdown = _render_validate_bundle_markdown(items, bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)+ print(markdown, file=sys.stderr)+ raise typer.Exit(1) from excdiff --git a/pipelex/cli/agent_cli/commands/bundle_path_resolver.py b/pipelex/cli/agent_cli/commands/bundle_path_resolver.pynew file mode 100644index 000000000..30339c5d9--- /dev/null+++ b/pipelex/cli/agent_cli/commands/bundle_path_resolver.py@@ -0,0 +1,77 @@+"""Path-to-bundle resolution for agent CLI bundle commands.++``validate bundle`` and ``fix bundle`` must resolve the user's ``path`` argument identically —+fix must patch exactly the file validate judged. The shared core owns the filesystem+decision-making; this wrapper owns agent error envelopes.+"""++from pathlib import Path+from typing import NoReturn++from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.cli.agent_cli.commands.agent_output import agent_error+from pipelex.cli.bundle_target_resolution import (+ BundleTargetResolutionError,+ BundleTargetResolutionErrorKind,+ BundleTargetResolutionSuccess,+ resolve_bundle_target_core,+)+++def _stringify_library_dirs(library_dirs: list[Path] | None) -> list[str] | None:+ if library_dirs is None:+ return None+ return [str(library_dir) for library_dir in library_dirs]+++def _handle_resolution_error(error: BundleTargetResolutionError) -> NoReturn:+ match error.kind:+ case BundleTargetResolutionErrorKind.NO_MTHDS_FILE:+ agent_error(f"No .mthds bundle file found in directory '{error.input_path}'", error_type="FileNotFoundError", exit_code=2)+ case BundleTargetResolutionErrorKind.AMBIGUOUS_MTHDS_FILES:+ mthds_names = ", ".join(mthds_file.name for mthds_file in error.candidate_files)+ agent_error(+ f"Multiple .mthds files found in '{error.input_path}' ({mthds_names}) and no '{DEFAULT_BUNDLE_FILE_NAME}'. "+ f"Pass the .mthds file directly instead.",+ error_type="ArgumentError",+ exit_code=2,+ )+ case BundleTargetResolutionErrorKind.UNSAFE_AUTO_DETECTED_SYMLINK:+ agent_error(+ f"Refusing to auto-detect symlinked bundle '{error.candidate_files[0]}'. Pass a regular .mthds file inside the directory.",+ error_type="ArgumentError",+ exit_code=2,+ )+ case BundleTargetResolutionErrorKind.NOT_BUNDLE_TARGET:+ agent_error(+ f"'{error.input_path}' is not a .mthds file or directory. "+ f"Use 'validate pipe <code>' for pipe codes, or 'validate bundle <path>' for .mthds files/directories.",+ error_type="ArgumentError",+ exit_code=2,+ )+++def resolve_bundle_target(path: str, *, library_dir: list[str] | None) -> tuple[str, list[str] | None]:+ """Resolve a ``path`` CLI argument into ``(bundle_path, library_dir)``.++ Directory mode auto-detects the bundle file — ``DEFAULT_BUNDLE_FILE_NAME`` if present, else+ a single ``*.mthds`` — and prepends the directory itself to ``library_dir`` so sibling+ files load (and, being user-passed, fall inside the fix write scope). No file / multiple+ ambiguous files / not-a-``.mthds`` path exit 2 via ``agent_error`` (no verdict produced).++ Both ``path`` and each ``library_dir`` entry have ``~`` expanded before resolution, so+ home-relative inputs behave like every other CLI path argument.++ Args:+ path: The user's ``path`` argument (a ``.mthds`` file or a bundle directory).+ library_dir: The ``-L/--library-dir`` values as passed, or ``None``.++ Returns:+ ``(bundle_path, library_dir)`` — the resolved bundle file path, and the possibly+ directory-augmented library dirs (``None`` when none apply).+ """+ result = resolve_bundle_target_core(path, library_dir=library_dir)+ if isinstance(result, BundleTargetResolutionSuccess):+ return str(result.bundle_path), _stringify_library_dirs(result.library_dirs)++ _handle_resolution_error(result)diff --git a/pipelex/cli/agent_cli/commands/fix/__init__.py b/pipelex/cli/agent_cli/commands/fix/__init__.pynew file mode 100644index 000000000..65662c86f--- /dev/null+++ b/pipelex/cli/agent_cli/commands/fix/__init__.py@@ -0,0 +1 @@+"""Agent CLI fix command group."""diff --git a/pipelex/cli/agent_cli/commands/fix/app.py b/pipelex/cli/agent_cli/commands/fix/app.pynew file mode 100644index 000000000..e6190d9bd--- /dev/null+++ b/pipelex/cli/agent_cli/commands/fix/app.py@@ -0,0 +1,12 @@+"""Agent CLI fix subcommand group."""++import typer++from pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmd++fix_app = typer.Typer(+ add_completion=False,+ no_args_is_help=True,+)++fix_app.command(name="bundle", help="Fix a bundle file (.mthds) or pipeline directory")(fix_bundle_cmd)diff --git a/pipelex/cli/agent_cli/commands/fix/bundle_cmd.py b/pipelex/cli/agent_cli/commands/fix/bundle_cmd.pynew file mode 100644index 000000000..aa2328eb9--- /dev/null+++ b/pipelex/cli/agent_cli/commands/fix/bundle_cmd.py@@ -0,0 +1,186 @@+"""Agent CLI fix bundle command."""++import asyncio+import sys+from pathlib import Path+from typing import Annotated, Any++import typer++from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli+from pipelex.cli.agent_cli.commands.agent_output import (+ CliOutputFormat,+ agent_error,+ agent_success_formatted,+ get_agent_cli_error_format,+ set_agent_cli_error_format,+)+from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_target+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError+from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError+from pipelex.pipelex import Pipelex+from pipelex.pipeline.fixes.fix_loop import FixBundleResult, fix_bundle_file+from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_still_invalid_markdown+from pipelex.pipeline.fixes.planner import KNOWN_FIX_CODES+++def _normalize_rule_codes(codes: list[str] | None) -> tuple[str, ...] | None:+ if not codes:+ return None+ return tuple(codes)+++def _reject_invalid_rule_filters(*, select_codes: tuple[str, ...] | None, ignore_codes: tuple[str, ...] | None) -> None:+ if select_codes is not None and ignore_codes is not None:+ agent_error(+ "--select and --ignore are mutually exclusive",+ error_type="ArgumentError",+ exit_code=2,+ known_fix_codes=sorted(KNOWN_FIX_CODES),+ )++ requested_codes: set[str] = set()+ if select_codes is not None:+ requested_codes.update(select_codes)+ if ignore_codes is not None:+ requested_codes.update(ignore_codes)+ unknown_codes = sorted(requested_codes - KNOWN_FIX_CODES)+ if unknown_codes:+ known_codes = ", ".join(sorted(KNOWN_FIX_CODES))+ unknown = ", ".join(unknown_codes)+ agent_error(+ f"Unknown fix rule code(s): {unknown}. Known codes: {known_codes}",+ error_type="ArgumentError",+ exit_code=2,+ unknown_fix_codes=unknown_codes,+ known_fix_codes=sorted(KNOWN_FIX_CODES),+ )+++def _result_payload(result: FixBundleResult, *, bundle_path: str) -> dict[str, Any]:+ return {+ "bundle_path": str(Path(bundle_path).resolve()),+ **result.model_dump(mode="json", exclude_none=True),+ }+++def _failure_message(result: FixBundleResult) -> str:+ message = (+ f"Fix loop stopped after {result.iterations} iteration(s): "+ f"{len(result.fixes_applied)} fix(es) applied, {len(result.remaining_errors)} error(s) remaining"+ )+ if result.bail_reason is not None:+ message = f"{message}; {result.bail_reason}"+ return message+++def fix_bundle_cmd(+ path: Annotated[+ str,+ typer.Argument(help="Path to a .mthds bundle file or a pipeline directory"),+ ],+ library_dir: Annotated[+ list[str] | None,+ typer.Option("--library-dir", "-L", help="Directory to search for pipe definitions (.mthds files)"),+ ] = None,+ allow_signatures: Annotated[+ bool,+ typer.Option(+ "--allow-signatures",+ help="Accept PipeSignature placeholders in the dependency graph (lenient mode).",+ ),+ ] = False,+ max_iterations: Annotated[+ int | None,+ typer.Option("--max-iterations", min=1, help="Maximum fix-apply rounds before reporting non-convergence"),+ ] = None,+ select_codes_raw: Annotated[+ list[str] | None,+ typer.Option("--select", help="Only apply the named fix rule code. Can be specified multiple times."),+ ] = None,+ ignore_codes_raw: Annotated[+ list[str] | None,+ typer.Option("--ignore", help="Skip the named fix rule code. Can be specified multiple times."),+ ] = None,+ output_format: Annotated[+ CliOutputFormat,+ typer.Option("--format", help="Success output format: markdown (default) or json (structured)"),+ ] = CliOutputFormat.MARKDOWN,+ error_format: Annotated[+ CliOutputFormat | None,+ typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ ] = None,+) -> None:+ """Fix a bundle file (.mthds) or pipeline directory in place."""+ set_agent_cli_error_format(error_format or output_format)++ select_codes = _normalize_rule_codes(select_codes_raw)+ ignore_codes = _normalize_rule_codes(ignore_codes_raw)+ _reject_invalid_rule_filters(select_codes=select_codes, ignore_codes=ignore_codes)++ bundle_path, library_dir = resolve_bundle_target(path, library_dir=library_dir)+ library_dirs = [Path(lib_dir) for lib_dir in library_dir] if library_dir else None++ try:+ make_pipelex_for_agent_cli(library_dirs=library_dirs, needs_inference=False, needs_model_specs=True)+ result = asyncio.run(+ fix_bundle_file(+ Path(bundle_path),+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ max_iterations=max_iterations,+ select_codes=select_codes,+ ignore_codes=ignore_codes,+ )+ )+ payload = _result_payload(result, bundle_path=bundle_path)+ if result.is_valid:+ agent_success_formatted({"success": True, **payload}, markdown_renderer=format_fix_markdown, output_format=output_format)+ if not allow_signatures and result.is_runnable is False:+ raise typer.Exit(1)+ return++ # Still-invalid verdict: format-aware. JSON keeps the exact FixBundleError envelope (the result+ # fields + bail_reason via **payload); markdown renders the remaining errors as prose with their+ # 💡 lines (mirroring the human still-invalid panel) instead of a raw JSON dump of the details.+ match get_agent_cli_error_format():+ case CliOutputFormat.JSON:+ agent_error(_failure_message(result), error_type="FixBundleError", exit_code=1, **payload)+ case CliOutputFormat.MARKDOWN:+ print(format_fix_still_invalid_markdown(result, bundle_path=str(payload["bundle_path"])), file=sys.stderr)+ raise typer.Exit(1)++ except FileNotFoundError as exc:+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)++ except PipeOperatorModelChoiceError as exc:+ agent_error(+ exc.message,+ error_type="PipeOperatorModelChoiceError",+ cause=exc,+ exit_code=2,+ pipe_code=exc.pipe_code,+ model_type=str(exc.model_type),+ model_choice=str(exc.model_choice),+ )++ except PipeOperatorModelAvailabilityError as exc:+ availability_extra: dict[str, Any] = {+ "pipe_code": exc.pipe_code,+ "model_handle": exc.model_handle,+ }+ if exc.fallback_list:+ availability_extra["fallback_list"] = exc.fallback_list+ if exc.pipe_stack:+ availability_extra["pipe_stack"] = exc.pipe_stack+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, exit_code=2, **availability_extra)++ except typer.Exit:+ raise++ except Exception as exc: # noqa: BLE001+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)++ finally:+ Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.pyindex d29be12ca..31b5210e5 100644--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py@@ -6,21 +6,20 @@ from typing import Annotated, Anyimport typer-from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAMEfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,+ agent_error_validate_bundle,agent_success_formatted,- extract_validation_errors,set_agent_cli_error_format,)+from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_targetfrom pipelex.cli.agent_cli.commands.validate._validate_core import (validate_bundle_core,validate_pipe_in_bundle_core,)from pipelex.core.interpreter.exceptions import PipelexInterpreterError-from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_filefrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom pipelex.graph.graph_rendering import GraphFormat, generate_graph_for_bundle, generate_view_for_bundlefrom pipelex.libraries.pipe.exceptions import PipeNotFoundError@@ -91,44 +90,7 @@ def validate_bundle_cmd("""set_agent_cli_error_format(error_format or output_format)- bundle_path: str | None = None- target_path = Path(path)-- if target_path.is_dir():- # Directory mode: auto-detect bundle file- bundle_file = target_path / DEFAULT_BUNDLE_FILE_NAME- if bundle_file.is_file():- bundle_path = str(bundle_file)- else:- mthds_files = list(target_path.glob(f"*{MTHDS_EXTENSION}"))- if len(mthds_files) == 0:- agent_error(f"No .mthds bundle file found in directory '{path}'", error_type="FileNotFoundError", exit_code=2)- if len(mthds_files) > 1:- mthds_names = ", ".join(mthds_file.name for mthds_file in mthds_files)- agent_error(- f"Multiple .mthds files found in '{path}' ({mthds_names}) and no '{DEFAULT_BUNDLE_FILE_NAME}'. "- f"Pass the .mthds file directly instead.",- error_type="ArgumentError",- exit_code=2,- )- bundle_path = str(mthds_files[0])-- # Add directory as library dir- target_dir_str = str(target_path)- if library_dir is None:- library_dir = [target_dir_str]- elif target_dir_str not in library_dir:- library_dir = [target_dir_str, *library_dir]-- elif is_pipelex_file(target_path):- bundle_path = path- else:- agent_error(- f"'{path}' is not a .mthds file or directory. "- f"Use 'validate pipe <code>' for pipe codes, or 'validate bundle <path>' for .mthds files/directories.",- error_type="ArgumentError",- exit_code=2,- )+ bundle_path, library_dir = resolve_bundle_target(path, library_dir=library_dir)library_dirs = [Path(lib_dir) for lib_dir in library_dir] if library_dir else None@@ -143,20 +105,18 @@ def validate_bundle_cmd(result = asyncio.run(validate_pipe_in_bundle_core(bundle_path=Path(bundle_path), pipe_code=pipe, library_dirs=library_dirs, allow_signatures=allow_signatures- ) # type: ignore[arg-type]+ ))else:# Validate the entire bundle- result = asyncio.run(- validate_bundle_core(bundle_path=Path(bundle_path), library_dirs=library_dirs, allow_signatures=allow_signatures) # type: ignore[arg-type]- )+ result = asyncio.run(validate_bundle_core(bundle_path=Path(bundle_path), library_dirs=library_dirs, allow_signatures=allow_signatures))# Generate graph if requested and validation succeededif graph:try:graph_result = asyncio.run(generate_graph_for_bundle(- bundle_path=Path(bundle_path), # type: ignore[arg-type]+ bundle_path=Path(bundle_path),graph_format=graph_format,library_dirs=library_dir_strings,pipe_code=pipe,@@ -186,7 +146,7 @@ def validate_bundle_cmd(try:view_result = asyncio.run(generate_view_for_bundle(- bundle_path=Path(bundle_path), # type: ignore[arg-type]+ bundle_path=Path(bundle_path),library_dirs=library_dir_strings,pipe_code=pipe,direction=direction,@@ -232,18 +192,11 @@ def validate_bundle_cmd(agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)except ValidateBundleError as exc:- # Invalid verdict: emit the structured failure envelope. validation_errors[] is the shared- # builder's output — non-empty on every invalid verdict (a residual dry-run failure rides one- # dry_run item, not a separate field). is_valid:false is the discriminant mirroring the success- # envelope; signatures never reach here (they are a runnability fact, gated above).- agent_error(- exc.message,- error_type="ValidateBundleError",- cause=exc,- is_valid=False,- bundle_path=str(bundle_path),- validation_errors=extract_validation_errors(exc),- )+ # Invalid verdict: emit the format-aware failure surface. JSON keeps the exact structured+ # envelope (is_valid:false discriminant + validation_errors[], the shared builder's output,+ # non-empty on every invalid verdict); markdown renders those items as prose with a fix-aware+ # footer. Signatures never reach here (they are a runnability fact, gated above).+ agent_error_validate_bundle(exc, bundle_path=Path(bundle_path), library_dirs=library_dirs, allow_signatures=allow_signatures)except PipeOperatorModelChoiceError as exc:agent_error(diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.pyindex b4b1eb8f2..24ddeef22 100644--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py@@ -12,8 +12,8 @@ from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agfrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,+ agent_error_validate_bundle,agent_success_formatted,- extract_validation_errors,set_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.validate._validate_core import (@@ -117,16 +117,9 @@ def validate_method_cmd(agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)except ValidateBundleError as exc:- # Invalid verdict (see bundle_cmd): structured failure envelope; validation_errors[] is the- # shared builder's output (a residual dry-run failure rides one dry_run item).- agent_error(- exc.message,- error_type="ValidateBundleError",- cause=exc,- is_valid=False,- bundle_path=str(bundle_path),- validation_errors=extract_validation_errors(exc),- )+ # Invalid verdict (see bundle_cmd): format-aware failure surface. JSON keeps the exact+ # structured envelope; markdown renders the items as prose with a fix-aware footer.+ agent_error_validate_bundle(exc, bundle_path=bundle_path, library_dirs=library_dirs_paths, allow_signatures=allow_signatures)except PipeOperatorModelChoiceError as exc:agent_error(diff --git a/pipelex/cli/bundle_target_resolution.py b/pipelex/cli/bundle_target_resolution.pynew file mode 100644index 000000000..32ee80e4b--- /dev/null+++ b/pipelex/cli/bundle_target_resolution.py@@ -0,0 +1,105 @@+"""Shared bundle target resolution for human and agent CLI wrappers."""++from enum import StrEnum+from pathlib import Path+from typing import NamedTuple++from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_file+++class BundleTargetResolutionErrorKind(StrEnum):+ """Failure kinds for resolving a CLI bundle target."""++ NO_MTHDS_FILE = "no_mthds_file"+ AMBIGUOUS_MTHDS_FILES = "ambiguous_mthds_files"+ UNSAFE_AUTO_DETECTED_SYMLINK = "unsafe_auto_detected_symlink"+ NOT_BUNDLE_TARGET = "not_bundle_target"+++class BundleTargetResolutionSuccess(NamedTuple):+ """Successful bundle target resolution."""++ bundle_path: Path+ library_dirs: list[Path] | None+ auto_detected: bool+++class BundleTargetResolutionError(NamedTuple):+ """Typed resolution failure for CLI-specific rendering."""++ kind: BundleTargetResolutionErrorKind+ input_path: str+ target_path: Path+ candidate_files: list[Path]+++def resolve_bundle_target_core(+ path: str,+ *,+ library_dir: list[str] | None,+) -> BundleTargetResolutionSuccess | BundleTargetResolutionError:+ """Resolve a CLI path argument without deciding how errors are rendered."""+ library_dirs = [Path(library_dir_item).expanduser() for library_dir_item in library_dir] if library_dir else None+ target_path = Path(path).expanduser()++ if target_path.is_dir():+ default_bundle_path = target_path / DEFAULT_BUNDLE_FILE_NAME+ if default_bundle_path.is_symlink():+ return BundleTargetResolutionError(+ kind=BundleTargetResolutionErrorKind.UNSAFE_AUTO_DETECTED_SYMLINK,+ input_path=path,+ target_path=target_path,+ candidate_files=[default_bundle_path],+ )+ if default_bundle_path.is_file():+ bundle_path = default_bundle_path+ else:+ mthds_files = sorted(target_path.glob(f"*{MTHDS_EXTENSION}"), key=lambda file_path: file_path.name)+ if len(mthds_files) == 0:+ return BundleTargetResolutionError(+ kind=BundleTargetResolutionErrorKind.NO_MTHDS_FILE,+ input_path=path,+ target_path=target_path,+ candidate_files=[],+ )+ if len(mthds_files) == 1 and mthds_files[0].is_symlink():+ return BundleTargetResolutionError(+ kind=BundleTargetResolutionErrorKind.UNSAFE_AUTO_DETECTED_SYMLINK,+ input_path=path,+ target_path=target_path,+ candidate_files=mthds_files,+ )+ if len(mthds_files) > 1:+ return BundleTargetResolutionError(+ kind=BundleTargetResolutionErrorKind.AMBIGUOUS_MTHDS_FILES,+ input_path=path,+ target_path=target_path,+ candidate_files=mthds_files,+ )+ bundle_path = mthds_files[0]++ if library_dirs is None:+ library_dirs = [target_path]+ elif target_path not in library_dirs:+ library_dirs = [target_path, *library_dirs]++ return BundleTargetResolutionSuccess(+ bundle_path=bundle_path,+ library_dirs=library_dirs,+ auto_detected=True,+ )++ if is_pipelex_file(target_path):+ return BundleTargetResolutionSuccess(+ bundle_path=target_path,+ library_dirs=library_dirs,+ auto_detected=False,+ )++ return BundleTargetResolutionError(+ kind=BundleTargetResolutionErrorKind.NOT_BUNDLE_TARGET,+ input_path=path,+ target_path=target_path,+ candidate_files=[],+ )diff --git a/pipelex/cli/commands/bundle_path_resolver.py b/pipelex/cli/commands/bundle_path_resolver.pynew file mode 100644index 000000000..60c6a2994--- /dev/null+++ b/pipelex/cli/commands/bundle_path_resolver.py@@ -0,0 +1,107 @@+"""Path-to-bundle resolution for human CLI bundle commands.++``pipelex validate bundle`` and ``pipelex fix bundle`` must resolve the user's ``path``+argument identically: fix must patch exactly the file validate judged. The shared core owns+the filesystem decision-making; this wrapper owns human text-stream errors.+"""++from pathlib import Path+from typing import NoReturn++import typer++from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.cli.bundle_target_resolution import (+ BundleTargetResolutionError,+ BundleTargetResolutionErrorKind,+ BundleTargetResolutionSuccess,+ resolve_bundle_target_core,+)+++def _stringify_library_dirs(library_dirs: list[Path] | None) -> list[str] | None:+ if library_dirs is None:+ return None+ return [str(library_dir) for library_dir in library_dirs]+++def _handle_resolution_error(+ error: BundleTargetResolutionError,+ *,+ command: str,+ not_a_bundle_hint: str,+) -> NoReturn:+ match error.kind:+ case BundleTargetResolutionErrorKind.NO_MTHDS_FILE:+ typer.secho(+ f"Failed to {command}: no .mthds bundle file found in directory '{error.input_path}'",+ fg=typer.colors.RED,+ err=True,+ )+ raise typer.Exit(2)+ case BundleTargetResolutionErrorKind.AMBIGUOUS_MTHDS_FILES:+ mthds_names = ", ".join(mthds_file.name for mthds_file in error.candidate_files)+ example_target = error.target_path / error.candidate_files[0].name+ typer.secho(+ f"Failed to {command}: multiple .mthds files found in '{error.input_path}' ({mthds_names}) "+ f"and no '{DEFAULT_BUNDLE_FILE_NAME}'. "+ f"Pass the .mthds file directly, e.g.: pipelex {command} bundle {example_target}",+ fg=typer.colors.RED,+ err=True,+ )+ raise typer.Exit(2)+ case BundleTargetResolutionErrorKind.UNSAFE_AUTO_DETECTED_SYMLINK:+ typer.secho(+ f"Failed to {command}: refusing to auto-detect symlinked bundle '{error.candidate_files[0]}'. "+ "Pass a regular .mthds file inside the directory.",+ fg=typer.colors.RED,+ err=True,+ )+ raise typer.Exit(2)+ case BundleTargetResolutionErrorKind.NOT_BUNDLE_TARGET:+ typer.secho(+ f"Failed to {command}: '{error.input_path}' is not a .mthds file or directory.\n{not_a_bundle_hint}",+ fg=typer.colors.RED,+ err=True,+ )+ raise typer.Exit(2)+++def resolve_bundle_target(+ path: str,+ *,+ library_dir: list[str] | None,+ command: str,+ not_a_bundle_hint: str,+) -> tuple[str, list[str] | None]:+ """Resolve a ``path`` CLI argument into ``(bundle_path, library_dir)``.++ Directory mode auto-detects the bundle file — ``DEFAULT_BUNDLE_FILE_NAME`` if present, else+ a single ``*.mthds`` — and prepends the directory itself to ``library_dir`` so sibling+ files load (and, being user-passed, fall inside the fix write scope). No file / multiple+ ambiguous files / not-a-``.mthds`` path exit 2 (no verdict produced) with a red message on+ stderr.++ Both ``path`` and each ``library_dir`` entry have ``~`` expanded before resolution, so+ home-relative inputs behave like every other CLI path argument.++ Args:+ path: The user's ``path`` argument (a ``.mthds`` file or a bundle directory).+ library_dir: The ``-L/--library-dir`` values as passed, or ``None``.+ command: The human command name (e.g. ``"validate"``, ``"fix"``), used in error+ messages (``Failed to {command}: ...``, ``pipelex {command} bundle ...``).+ not_a_bundle_hint: Command-specific usage hint appended when ``path`` is neither a+ ``.mthds`` file nor a directory.++ Returns:+ ``(bundle_path, library_dir)`` — the resolved bundle file path, and the possibly+ directory-augmented library dirs (``None`` when none apply).+ """+ result = resolve_bundle_target_core(path, library_dir=library_dir)+ if isinstance(result, BundleTargetResolutionSuccess):+ bundle_path = str(result.bundle_path)+ if result.auto_detected:+ typer.echo(f"Auto-detected bundle: {bundle_path}")+ return bundle_path, _stringify_library_dirs(result.library_dirs)++ _handle_resolution_error(result, command=command, not_a_bundle_hint=not_a_bundle_hint)diff --git a/pipelex/cli/commands/fix/__init__.py b/pipelex/cli/commands/fix/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/pipelex/cli/commands/fix/_diff_sandbox.py b/pipelex/cli/commands/fix/_diff_sandbox.pynew file mode 100644index 000000000..c9a899c68--- /dev/null+++ b/pipelex/cli/commands/fix/_diff_sandbox.py@@ -0,0 +1,156 @@+"""Temp-copy sandbox for the ``pipelex fix bundle --diff`` preview.++The fix loop has no no-write mode and re-validation loads from disk, so an honest preview+runs the REAL loop against copies. The effective load scope (explicit ``-L`` dirs or ambient+resolution) is canonicalized by resolved identity, mirrored once, and passed separately from+the writable subset. This keeps ambient libraries read-only while ensuring the entry and every+library declaration have the same identity in preview and write mode.++Layout subtlety: when the entry file lies under one of the explicit ``-L`` dirs (directory+mode always does this), the sandbox entry path must be the file *inside* the mirrored dir+copy — a separate entry copy would make the loop validate one copy while the library loads+another, declaring every pipe twice.+"""++import shutil+from collections.abc import Sequence+from pathlib import Path+from typing import NamedTuple++from pipelex.config import get_config+from pipelex.hub import resolve_library_dirs+++def _excluded_copy_entries( # kw-only: ignore - shutil.copytree invokes ignore callbacks positionally+ directory: str,+ names: list[str],+) -> set[str]:+ """Return directory entries excluded by the real library scanners.++ ``copytree`` otherwise mirrors virtualenvs, VCS data, caches, and result trees that the+ loader never reads. Symlink entries are not traversed here; ``copytree(symlinks=True)``+ preserves them as links instead of copying data from outside the requested root.+ """+ excluded_entries: set[str] = set()+ excluded_dirs = get_config().pipelex.scan_config.excluded_dirs+ current_dir = Path(directory)+ for name in names:+ candidate = current_dir / name+ if not candidate.is_dir():+ continue+ for excluded_dir in excluded_dirs:+ excluded_path = Path(excluded_dir)+ if excluded_path.is_absolute():+ if candidate.resolve().is_relative_to(excluded_path.resolve()):+ excluded_entries.add(name)+ break+ elif name == excluded_dir:+ excluded_entries.add(name)+ break+ return excluded_entries+++class PreviewSandbox(NamedTuple):+ """The mirrored bundle a ``--diff`` preview runs against, plus the copy→original mapping."""++ entry_path: Path+ """The sandbox path of the entry bundle file (resolved)."""+ library_dirs: list[Path]+ """The complete effective load scope remapped onto canonical sandbox copies."""+ writable_library_dirs: list[Path]+ """The subset of copied library dirs the real invocation authorized for writes."""+ dir_mappings: list[tuple[Path, Path]]+ """``(copy_root, original_root)`` per explicit ``-L`` dir, both resolved."""+ entry_mapping: tuple[Path, Path]+ """``(entry_copy, entry_original)``, both resolved."""++ def to_original(self, path_str: str) -> str:+ """Map a sandbox file path back to the original it mirrors.++ Paths outside the sandbox (ambient-resolved files) pass through resolved-as-is.+ """+ resolved = Path(path_str).resolve()+ entry_copy, entry_original = self.entry_mapping+ if resolved == entry_copy:+ return str(entry_original)+ for copy_root, original_root in self.dir_mappings:+ if resolved.is_relative_to(copy_root):+ return str(original_root / resolved.relative_to(copy_root))+ return str(resolved)+++def mirror_bundle_for_preview(+ entry_path: Path,+ *,+ library_dirs: Sequence[Path] | None,+ sandbox_root: Path,+) -> PreviewSandbox:+ """Mirror the entry file and each explicit ``-L`` dir into ``sandbox_root``.++ Each effective dir is copied with the loader's configured directory exclusions (the loader+ may read Python files as well as ``.mthds`` files), preserving its internal layout under+ ``sandbox_root/lib_<i>``. Symlinks are preserved rather than dereferenced. The entry file resolves to+ its in-copy location when it lives under one of the dirs, else to a standalone copy under+ ``sandbox_root/entry``. Equivalent and overlapping roots collapse to one canonical copy;+ ambient copies are part of load scope but excluded from ``writable_library_dirs``.+ """+ entry_resolved = entry_path.resolve()+ effective_dirs, _ = resolve_library_dirs(library_dirs)+ unique_roots: list[Path] = []+ for library_dir in effective_dirs:+ resolved_root = Path(library_dir).resolve()+ if resolved_root not in unique_roots:+ unique_roots.append(resolved_root)+ canonical_roots = [root for root in unique_roots if not any(root != other and root.is_relative_to(other) for other in unique_roots)]+ dir_mappings: list[tuple[Path, Path]] = []+ remapped_dirs: list[Path] = []+ entry_copy: Path | None = None++ for dir_index, original_root in enumerate(canonical_roots):+ copy_root = (sandbox_root / f"lib_{dir_index}").resolve()+ if original_root.exists():+ shutil.copytree(original_root, copy_root, symlinks=True, ignore=_excluded_copy_entries)+ else:+ # The real loader skips a missing -L dir (it contributes no files) while+ # keeping it in effective_dirs; mirror that as an empty copy so copytree does+ # not crash, is_single_file is preserved, and the preview verdict tracks the run.+ copy_root.mkdir(parents=True, exist_ok=True)+ dir_mappings.append((copy_root, original_root))+ remapped_dirs.append(copy_root)+ if entry_copy is None and entry_resolved.is_relative_to(original_root):+ entry_copy = copy_root / entry_resolved.relative_to(original_root)++ for copy_root, original_root in dir_mappings:+ if not original_root.exists():+ continue+ for original_link in original_root.rglob("*"):+ if not original_link.is_symlink():+ continue+ copied_link = copy_root / original_link.relative_to(original_root)+ resolved_target = original_link.resolve()+ copied_target: Path | None = None+ for target_copy_root, target_original_root in dir_mappings:+ if resolved_target.is_relative_to(target_original_root):+ copied_target = target_copy_root / resolved_target.relative_to(target_original_root)+ break+ if copied_target is None:+ continue+ copied_link.unlink()+ copied_link.symlink_to(copied_target, target_is_directory=resolved_target.is_dir())++ if entry_copy is None:+ entry_dir = sandbox_root / "entry"+ entry_dir.mkdir(parents=True, exist_ok=True)+ entry_copy = (entry_dir / entry_resolved.name).resolve()+ shutil.copy2(entry_resolved, entry_copy)+ elif entry_copy.is_symlink() and not entry_copy.resolve().is_relative_to(sandbox_root.resolve()):+ entry_copy.unlink()+ shutil.copy2(entry_resolved, entry_copy)++ return PreviewSandbox(+ entry_path=entry_copy,+ library_dirs=remapped_dirs,+ writable_library_dirs=remapped_dirs if library_dirs is not None else [],+ dir_mappings=dir_mappings,+ entry_mapping=(entry_copy, entry_resolved),+ )diff --git a/pipelex/cli/commands/fix/_fix_core.py b/pipelex/cli/commands/fix/_fix_core.pynew file mode 100644index 000000000..aa55d404f--- /dev/null+++ b/pipelex/cli/commands/fix/_fix_core.py@@ -0,0 +1,309 @@+from __future__ import annotations++import asyncio+import difflib+import tempfile+from pathlib import Path+from typing import TYPE_CHECKING++import typer+from posthog import tag+from rich.markup import escape++from pipelex.cli.cli_factory import make_pipelex_for_cli+from pipelex.cli.commands.fix._diff_sandbox import mirror_bundle_for_preview+from pipelex.cli.error_handlers import (+ ErrorContext,+ display_validation_error_items,+ handle_model_availability_error,+ handle_model_choice_error,+ print_traceback_if_requested,+)+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError+from pipelex.hub import get_console, get_telemetry_manager+from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError+from pipelex.pipelex import Pipelex+from pipelex.pipeline.fixes.fix_loop import fix_bundle_file+from pipelex.system.runtime import IntegrationMode+from pipelex.system.telemetry.events import EventProperty+from pipelex.tools.misc.package_utils import get_package_version+from pipelex.urls import URLs++if TYPE_CHECKING:+ from rich.console import Console++ from pipelex.base_exceptions import ValidationErrorItem+ from pipelex.cli.commands.fix._diff_sandbox import PreviewSandbox+ from pipelex.pipeline.fixes.fix_loop import FixBundleResult+ from pipelex.suggested_fix import SuggestedFix++COMMAND = "fix"+++def _print_applied_fixes(console: Console, *, fixes: list[SuggestedFix], bundle_path: Path) -> None:+ """Numbered list naming every change made — descriptions only, ops stay machine-facing."""+ entry_resolved = bundle_path.resolve()+ for fix_index, fix in enumerate(fixes, 1):+ line = f" {fix_index}. {escape(fix.description)} [dim]({escape(fix.fix_code)})[/dim]"+ if fix.source is not None and Path(fix.source).resolve() != entry_resolved:+ line += f" [dim]— {escape(fix.source)}[/dim]"+ console.print(line)+++def _print_work_done(console: Console, *, result: FixBundleResult, bundle_path: Path, preview: bool = False) -> None:+ """The applied fixes, files written, and iteration count of one fix run."""+ console.print(f"[bold cyan]{'Fixes that would be applied:' if preview else 'Applied fixes:'}[/bold cyan]")+ _print_applied_fixes(console, fixes=result.fixes_applied, bundle_path=bundle_path)+ if result.files_written:+ console.print(f"\n[bold cyan]{'Files that would be written:' if preview else 'Files written:'}[/bold cyan]")+ for file_path in result.files_written:+ console.print(f" - {escape(file_path)}")+ console.print(f"\n[bold cyan]Iterations:[/bold cyan] {result.iterations}")+++def _render_fix_result(console: Console, *, result: FixBundleResult, bundle_path: Path, allow_signatures: bool, preview: bool = False) -> None:+ """Render a ``FixBundleResult`` for humans and exit per the 0/1 verdict policy.++ Valid (fixed or already valid) exits 0; valid-but-not-runnable without+ ``--allow-signatures`` and still-invalid exit 1. No-verdict outcomes never reach here —+ they are handled by :func:`execute_fix`'s exception arms (exit 2). ``preview`` swaps the+ labels to would-be phrasing (``--diff`` writes nothing) while keeping the same verdicts+ and exit codes, so ``--diff`` answers "would it converge?".+ """+ if result.is_valid:+ console.print()+ if result.fixes_applied:+ if preview:+ console.print("[bold green]✅ Fix preview — these fixes would make the bundle valid[/bold green]\n")+ else:+ console.print("[bold green]✅ Bundle fixed — valid[/bold green]\n")+ else:+ console.print("[bold green]✅ Bundle already valid[/bold green]\n")+ console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{escape(str(bundle_path))}[/yellow]")+ if result.fixes_applied:+ console.print()+ _print_work_done(console, result=result, bundle_path=bundle_path, preview=preview)+ console.print()++ if result.pending_signatures:+ pending = ", ".join(result.pending_signatures)+ if allow_signatures:+ console.print(f"[dim]Pending PipeSignature placeholder(s): {escape(pending)}[/dim]\n")+ else:+ # Mirrors the validate/agent-fix runnability gate: valid is not runnable. Under+ # --diff nothing was written, so the phrasing stays conditional (would-be).+ if preview:+ console.print(+ f"[bold red]Fix preview — the bundle would be valid but still NOT runnable: "+ f"unimplemented PipeSignature placeholder(s): {escape(pending)}[/bold red]"+ )+ else:+ console.print(+ f"[bold red]Bundle is valid but NOT yet runnable — unimplemented PipeSignature placeholder(s): {escape(pending)}[/bold red]"+ )+ console.print("[bold green]💡 Tip:[/bold green] Implement them, or re-run with --allow-signatures to accept placeholders.\n")+ raise typer.Exit(1)+ return++ console.print()+ if preview:+ console.print("[bold red]❌ Fix preview — the bundle would still be invalid[/bold red]\n")+ else:+ console.print("[bold red]❌ Bundle could not be fully fixed[/bold red]\n")+ console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{escape(str(bundle_path))}[/yellow]\n")++ # Partial progress is normal: name what WAS applied before the remaining errors.+ if result.fixes_applied:+ _print_work_done(console, result=result, bundle_path=bundle_path, preview=preview)+ console.print()++ if result.bail_reason:+ console.print(f"[bold yellow]Stopped:[/bold yellow] {escape(result.bail_reason)}\n")++ if result.remaining_errors:+ console.print("[bold cyan]Remaining errors:[/bold cyan]\n")+ display_validation_error_items(console, items=result.remaining_errors)++ # A remaining error can still carry a 💡 suggested-fix line — dropped by --select/--ignore,+ # left outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix"+ # there contradicts the line just printed, so only say it when nothing fixable remains.+ if any(item.suggested_fix is not None for item in result.remaining_errors):+ console.print(+ "[bold green]💡 Tip:[/bold green] Some remaining errors above still show a suggested fix that was not applied — "+ "they were skipped by --select/--ignore, fell outside the write scope, or the loop stopped early (see the reason above). "+ "Adjust those flags (or pass -L) and re-run, or fix the rest manually."+ )+ else:+ console.print(+ "[bold green]💡 Tip:[/bold green] Review the remaining errors above — they have no deterministic safe fix, so they need a manual edit."+ )+ console.print(f"[dim]Learn more: {URLs.documentation}[/dim]")+ console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")+ raise typer.Exit(1)+++def _remap_validation_error_to_original(item: ValidationErrorItem, *, sandbox: PreviewSandbox) -> ValidationErrorItem:+ """Remap only the diagnostic values proven to carry mirrored filesystem paths."""+ updates: dict[str, object] = {}+ source = item.source+ remapped_source: str | None = None+ if source is not None:+ remapped_source = sandbox.to_original(source)+ updates["source"] = remapped_source+ if source and remapped_source != source and source in item.message:+ updates["message"] = item.message.replace(source, remapped_source)++ field_path = item.field_path+ if field_path is not None:+ if source is not None and field_path == source:+ updates["field_path"] = remapped_source+ elif Path(field_path).is_absolute():+ resolved_field_path = str(Path(field_path).resolve())+ remapped_field_path = sandbox.to_original(field_path)+ if remapped_field_path != resolved_field_path:+ updates["field_path"] = remapped_field_path++ return item.model_copy(update=updates) if updates else item+++def _remap_result_to_originals(result: FixBundleResult, *, sandbox: PreviewSandbox) -> FixBundleResult:+ """Rebuild a sandbox-run result with every file path mapped back to the original it mirrors."""+ return result.model_copy(+ update={+ "fixes_applied": [+ fix.model_copy(update={"source": sandbox.to_original(fix.source)}) if fix.source is not None else fix for fix in result.fixes_applied+ ],+ "files_written": [sandbox.to_original(file_path) for file_path in result.files_written],+ "remaining_errors": [_remap_validation_error_to_original(item, sandbox=sandbox) for item in result.remaining_errors],+ }+ )+++def _print_preview_diffs(console: Console, *, result: FixBundleResult, sandbox: PreviewSandbox) -> None:+ """Unified diff (original vs sandbox copy) per file the preview run wrote.++ Must run while the sandbox still exists — it reads the mutated copies off disk.+ """+ console.print("\n[bold cyan]Preview (--diff): no files were written. Proposed changes:[/bold cyan]\n")+ for written_path in result.files_written:+ original_path = Path(sandbox.to_original(written_path))+ original_lines = original_path.read_text(encoding="utf-8").splitlines()+ updated_lines = Path(written_path).read_text(encoding="utf-8").splitlines()+ diff_lines = difflib.unified_diff(+ original_lines,+ updated_lines,+ fromfile=str(original_path),+ tofile=f"{original_path} (fixed)",+ lineterm="",+ )+ for diff_line in diff_lines:+ if diff_line.startswith(("+++", "---")):+ console.print(f"[bold]{escape(diff_line)}[/bold]")+ elif diff_line.startswith("@@"):+ console.print(f"[cyan]{escape(diff_line)}[/cyan]")+ elif diff_line.startswith("+"):+ console.print(f"[green]{escape(diff_line)}[/green]")+ elif diff_line.startswith("-"):+ console.print(f"[red]{escape(diff_line)}[/red]")+ else:+ console.print(escape(diff_line))+ console.print()+++def _run_fix_preview(+ console: Console,+ *,+ bundle_path: Path,+ library_dirs: list[Path] | None,+ allow_signatures: bool,+ max_iterations: int | None,+ select_codes: tuple[str, ...] | None,+ ignore_codes: tuple[str, ...] | None,+) -> None:+ """Run the real loop against a temp-copy sandbox (D5.6), render diffs, keep the verdict."""+ with tempfile.TemporaryDirectory(prefix="pipelex-fix-preview-") as sandbox_root:+ sandbox = mirror_bundle_for_preview(bundle_path, library_dirs=library_dirs, sandbox_root=Path(sandbox_root))+ result = asyncio.run(+ fix_bundle_file(+ sandbox.entry_path,+ library_dirs=sandbox.library_dirs,+ writable_library_dirs=sandbox.writable_library_dirs,+ allow_signatures=allow_signatures,+ max_iterations=max_iterations,+ select_codes=select_codes,+ ignore_codes=ignore_codes,+ )+ )+ if result.files_written:+ _print_preview_diffs(console, result=result, sandbox=sandbox)+ display_result = _remap_result_to_originals(result, sandbox=sandbox)+ _render_fix_result(console, result=display_result, bundle_path=bundle_path, allow_signatures=allow_signatures, preview=True)+++def execute_fix(+ bundle_path: Path,+ *,+ library_dirs: list[Path] | None,+ allow_signatures: bool = False,+ max_iterations: int | None = None,+ select_codes: tuple[str, ...] | None = None,+ ignore_codes: tuple[str, ...] | None = None,+ diff: bool = False,+) -> None:+ """Synchronous entry point wrapping the fix loop with Pipelex setup/teardown.++ Boots with the same profile ``validate`` uses (no inference, real model specs), runs+ ``fix_bundle_file``, renders the verdict for humans, and tears down in ``finally``.+ Exit codes are presentation: 0 = valid, 1 = negative verdict (still invalid, or valid but+ not runnable without ``--allow-signatures``), 2 = no verdict (bad target, boot failure,+ unexpected exception). ``diff`` previews instead of writing: the same loop runs against a+ temp-copy sandbox and a unified diff is rendered per would-be-written file, with the same+ verdict semantics.+ """+ try:+ make_pipelex_for_cli(context=ErrorContext.FIX, needs_inference=False, needs_model_specs=True)+ with get_telemetry_manager().telemetry_context():+ tag(name=EventProperty.INTEGRATION, value=IntegrationMode.CLI)+ tag(name=EventProperty.PIPELEX_VERSION, value=get_package_version())+ tag(name=EventProperty.CLI_COMMAND, value=f"{COMMAND} bundle")++ if diff:+ _run_fix_preview(+ get_console(),+ bundle_path=bundle_path,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ max_iterations=max_iterations,+ select_codes=select_codes,+ ignore_codes=ignore_codes,+ )+ return++ result = asyncio.run(+ fix_bundle_file(+ bundle_path,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ max_iterations=max_iterations,+ select_codes=select_codes,+ ignore_codes=ignore_codes,+ )+ )+ _render_fix_result(get_console(), result=result, bundle_path=bundle_path, allow_signatures=allow_signatures)+ except FileNotFoundError as exc:+ print_traceback_if_requested(get_console())+ typer.secho(f"Failed to fix: bundle file not found: '{bundle_path}'", fg=typer.colors.RED, err=True)+ raise typer.Exit(2) from exc+ except PipeOperatorModelChoiceError as exc:+ handle_model_choice_error(exc, context=ErrorContext.FIX, exit_code=2)+ except PipeOperatorModelAvailabilityError as exc:+ handle_model_availability_error(exc, context=ErrorContext.FIX, exit_code=2)+ except typer.Exit:+ raise+ except Exception as exc:+ # Human CLI command boundary: an unexpected failure produced no verdict — exit 2.+ print_traceback_if_requested(get_console())+ typer.secho(f"Failed to fix: {exc}", fg=typer.colors.RED, err=True)+ raise typer.Exit(2) from exc+ finally:+ Pipelex.teardown_if_needed()diff --git a/pipelex/cli/commands/fix/app.py b/pipelex/cli/commands/fix/app.pynew file mode 100644index 000000000..6f019930e--- /dev/null+++ b/pipelex/cli/commands/fix/app.py@@ -0,0 +1,10 @@+import typer++from pipelex.cli.commands.fix.bundle_cmd import fix_bundle_cmd++fix_app = typer.Typer(+ help="Apply deterministic safe fixes to a bundle and re-validate until valid",+ no_args_is_help=True,+)++fix_app.command("bundle", help="Fix a bundle file (.mthds) or pipeline directory in place")(fix_bundle_cmd)diff --git a/pipelex/cli/commands/fix/bundle_cmd.py b/pipelex/cli/commands/fix/bundle_cmd.pynew file mode 100644index 000000000..427364cc4--- /dev/null+++ b/pipelex/cli/commands/fix/bundle_cmd.py@@ -0,0 +1,106 @@+from __future__ import annotations++from pathlib import Path+from typing import Annotated++import typer++from pipelex.cli.commands.bundle_path_resolver import resolve_bundle_target+from pipelex.cli.commands.fix._fix_core import COMMAND, execute_fix+from pipelex.pipeline.fixes.planner import KNOWN_FIX_CODES++_NOT_A_BUNDLE_HINT = " To fix a bundle, pass a .mthds file or directory: pipelex fix bundle <path>"+++def _reject_invalid_rule_filters(*, select_codes: tuple[str, ...] | None, ignore_codes: tuple[str, ...] | None) -> None:+ """Reject a contradictory or typo'd rule selection loudly (exit 2, no verdict).++ A typo'd filter selects *behavior*, so lenient-ignore is wrong — mirrors the agent CLI's+ check with human text-stream presentation.+ """+ if select_codes is not None and ignore_codes is not None:+ typer.secho("Failed to fix: --select and --ignore are mutually exclusive", fg=typer.colors.RED, err=True)+ raise typer.Exit(2)++ requested_codes: set[str] = set(select_codes or ()) | set(ignore_codes or ())+ unknown_codes = sorted(requested_codes - KNOWN_FIX_CODES)+ if unknown_codes:+ known = ", ".join(sorted(KNOWN_FIX_CODES))+ unknown = ", ".join(unknown_codes)+ typer.secho(f"Failed to fix: unknown fix rule code(s): {unknown}. Known codes: {known}", fg=typer.colors.RED, err=True)+ raise typer.Exit(2)+++def fix_bundle_cmd(+ path: Annotated[+ str,+ typer.Argument(help="Path to a .mthds bundle file or a pipeline directory"),+ ],+ library_dir: Annotated[+ list[str] | None,+ typer.Option(+ "--library-dir",+ "-L",+ help="Directory to search for pipe definitions (.mthds files). Can be specified multiple times. "+ "Files under these directories are inside the fix write scope.",+ ),+ ] = None,+ allow_signatures: Annotated[+ bool,+ typer.Option(+ "--allow-signatures",+ help="Accept PipeSignature placeholders in the dependency graph (lenient mode).",+ ),+ ] = False,+ max_iterations: Annotated[+ int | None,+ typer.Option("--max-iterations", min=1, help="Maximum fix-apply rounds before reporting non-convergence"),+ ] = None,+ select_codes_raw: Annotated[+ list[str] | None,+ typer.Option("--select", help="Only apply the named fix rule code. Can be specified multiple times."),+ ] = None,+ ignore_codes_raw: Annotated[+ list[str] | None,+ typer.Option("--ignore", help="Skip the named fix rule code. Can be specified multiple times."),+ ] = None,+ diff: Annotated[+ bool,+ typer.Option(+ "--diff",+ help="Preview: show the changes as a unified diff without writing any file. Exit codes keep the same verdict semantics.",+ ),+ ] = False,+) -> None:+ """Fix a bundle file (.mthds) or pipeline directory in place.++ Runs the validate → apply safe fixes → re-validate loop until the bundle is valid, out+ of fixes, or the iteration cap is reached, and names every change made.++ Examples:+ pipelex fix bundle my_bundle.mthds+ pipelex fix bundle pipeline_01/+ pipelex fix bundle my_bundle.mthds --select match-sequence-output+ pipelex fix bundle my_bundle.mthds --diff+ """+ select_codes = tuple(select_codes_raw) if select_codes_raw else None+ ignore_codes = tuple(ignore_codes_raw) if ignore_codes_raw else None+ _reject_invalid_rule_filters(select_codes=select_codes, ignore_codes=ignore_codes)++ bundle_path, library_dir = resolve_bundle_target(+ path,+ library_dir=library_dir,+ command=COMMAND,+ not_a_bundle_hint=_NOT_A_BUNDLE_HINT,+ )+ library_dirs = [Path(lib_dir) for lib_dir in library_dir] if library_dir else None++ execute_fix(+ Path(bundle_path),+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ max_iterations=max_iterations,+ select_codes=select_codes,+ ignore_codes=ignore_codes,+ diff=diff,+ )diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.pyindex 8e1bceb84..29531a805 100644--- a/pipelex/cli/commands/validate/_validate_core.py+++ b/pipelex/cli/commands/validate/_validate_core.py@@ -171,7 +171,7 @@ async def _validate_pipe_or_bundle()raise typer.Exit(2) from excexcept ValidateBundleError as bundle_error:- handle_validate_bundle_error(bundle_error, bundle_path=bundle_path)+ handle_validate_bundle_error(bundle_error, bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)elif pipe_code:library_manager = get_library_manager()library_id, _ = library_manager.open_library()@@ -228,10 +228,9 @@ def execute_validate(with get_telemetry_manager().telemetry_context():tag(name=EventProperty.INTEGRATION, value=IntegrationMode.CLI)tag(name=EventProperty.PIPELEX_VERSION, value=get_package_version())- if bundle_path:- tag(name=EventProperty.CLI_COMMAND, value=f"{telemetry_command_label} bundle")- else:- tag(name=EventProperty.CLI_COMMAND, value=f"{telemetry_command_label} pipe")+ # The label already carries the subcommand (each caller passes e.g. "validate bundle") —+ # tagging it verbatim fixes the historical double suffix ("validate bundle bundle").+ tag(name=EventProperty.CLI_COMMAND, value=telemetry_command_label)asyncio.run(_validate_pipe_or_bundle(diff --git a/pipelex/cli/commands/validate/bundle_cmd.py b/pipelex/cli/commands/validate/bundle_cmd.pyindex 791fb01ca..1fbf3e0cf 100644--- a/pipelex/cli/commands/validate/bundle_cmd.py+++ b/pipelex/cli/commands/validate/bundle_cmd.py@@ -5,9 +5,13 @@ from typing import Annotatedimport typer-from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.cli.commands.bundle_path_resolver import resolve_bundle_targetfrom pipelex.cli.commands.validate._validate_core import COMMAND, execute_validate-from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_file++_NOT_A_BUNDLE_HINT = (+ " To validate a pipe by code, use: pipelex validate pipe <code>\n"+ " To validate a bundle, pass a .mthds file or directory: pipelex validate bundle <path>"+)def validate_bundle_cmd(@@ -46,61 +50,17 @@ def validate_bundle_cmd(pipelex validate bundle pipeline_01/pipelex validate bundle my_bundle.mthds --allow-signatures"""- bundle_path: str | None = None- target_path = Path(path)-- if target_path.is_dir():- # Directory mode: auto-detect bundle file- bundle_file = target_path / DEFAULT_BUNDLE_FILE_NAME- if bundle_file.is_file():- bundle_path = str(bundle_file)- else:- mthds_files = list(target_path.glob(f"*{MTHDS_EXTENSION}"))- if len(mthds_files) == 0:- typer.secho(- f"Failed to validate: no .mthds bundle file found in directory '{path}'",- fg=typer.colors.RED,- err=True,- )- raise typer.Exit(2)- if len(mthds_files) > 1:- mthds_names = ", ".join(mthds_file.name for mthds_file in mthds_files)- typer.secho(- f"Failed to validate: multiple .mthds files found in '{path}' ({mthds_names}) "- f"and no '{DEFAULT_BUNDLE_FILE_NAME}'. "- f"Pass the .mthds file directly, e.g.: pipelex validate bundle {target_path / mthds_files[0].name}",- fg=typer.colors.RED,- err=True,- )- raise typer.Exit(2)- bundle_path = str(mthds_files[0])-- # Add directory as library dir- target_dir_str = str(target_path)- if library_dir is None:- library_dir = [target_dir_str]- elif target_dir_str not in library_dir:- library_dir = [target_dir_str, *library_dir]-- typer.echo(f"Auto-detected bundle: {bundle_path}")-- elif is_pipelex_file(target_path):- bundle_path = path- else:- typer.secho(- f"Failed to validate: '{path}' is not a .mthds file or directory.\n"- f" To validate a pipe by code, use: pipelex validate pipe <code>\n"- f" To validate a bundle, pass a .mthds file or directory: pipelex validate bundle <path>",- fg=typer.colors.RED,- err=True,- )- raise typer.Exit(2)-+ bundle_path, library_dir = resolve_bundle_target(+ path,+ library_dir=library_dir,+ command=COMMAND,+ not_a_bundle_hint=_NOT_A_BUNDLE_HINT,+ )library_dirs_paths = [Path(lib_dir) for lib_dir in library_dir] if library_dir else Noneexecute_validate(pipe_code=None,- bundle_path=Path(bundle_path) if bundle_path else None,+ bundle_path=Path(bundle_path),library_dirs=library_dirs_paths,telemetry_command_label=f"{COMMAND} bundle",allow_signatures=allow_signatures,diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex 6e4ef0c5d..2d454a392 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -9,11 +9,13 @@ from rich.console import Consolefrom rich.markup import escapefrom rich.traceback import Traceback+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetValidatonErrorfrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom pipelex.hub import get_consolefrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixesfrom pipelex.system.pipelex_service.exceptions import (GatewayApiKeyMissingError,GatewayDoNotTrackConflictError,@@ -32,6 +34,7 @@ class ErrorContext(StrEnum):PIPE_RUN = "Pipe run"VALIDATION = "Pipe validation"+ FIX = "Bundle fix"BUILD = "Pipe build"# Pre-validation contexts (for Pipelex.make() errors)@@ -248,86 +251,103 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, contexraise typer.Exit(1) from exc-def _display_validation_error_details(console: Console, *, exc: ValidateBundleError) -> None:- """Display the detailed validation error information from a ValidateBundleError.+def _validation_category_header(category: ValidationErrorCategory) -> str:+ match category:+ case ValidationErrorCategory.BLUEPRINT_VALIDATION:+ return "Blueprint Validation Errors:"+ case ValidationErrorCategory.PIPE_FACTORY:+ return "Pipe Factory Errors:"+ case ValidationErrorCategory.PIPE_VALIDATION:+ return "Pipe Validation Errors:"+ case ValidationErrorCategory.DRY_RUN:+ return "Dry Run Error:"+++def _display_validation_error_item(console: Console, *, item: ValidationErrorItem, error_index: int) -> None:+ """Render one structured validation-error item: title, identity fields, message, fix, locators."""+ error_type_display = item.error_type.replace("_", " ").title() if item.error_type else "Validation Error"+ console.print(f"[bold yellow]{error_index}. {error_type_display}[/bold yellow]")++ if item.pipe_code:+ console.print(f" [cyan]Pipe:[/cyan] [yellow]{escape(item.pipe_code)}[/yellow]")+ if item.concept_code:+ console.print(f" [cyan]Concept:[/cyan] [yellow]{escape(item.concept_code)}[/yellow]")+ if item.domain_code:+ console.print(f" [cyan]Domain:[/cyan] [green]{escape(item.domain_code)}[/green]")+ if item.field_name:+ console.print(f" [cyan]Field:[/cyan] [yellow]{escape(item.field_name)}[/yellow]")+ if item.missing_concept_code:+ console.print(f" [cyan]Missing Concept:[/cyan] [yellow]{escape(item.missing_concept_code)}[/yellow]")+ if item.missing_pipe_code:+ console.print(f" [cyan]Missing Pipe:[/cyan] [yellow]{escape(item.missing_pipe_code)}[/yellow]")+ if item.declared_concepts:+ declared_str = ", ".join([f"[yellow]{escape(concept_code)}[/yellow]" for concept_code in item.declared_concepts])+ console.print(f" [cyan]Declared Concepts:[/cyan] {declared_str}")+ if item.variable_names:+ variables_str = ", ".join([f"[yellow]{escape(variable_name)}[/yellow]" for variable_name in item.variable_names])+ console.print(f" [cyan]Variables:[/cyan] {variables_str}")++ console.print(f" [cyan]→[/cyan] {escape(item.message)}")++ if item.suggested_fix is not None:+ console.print(f" [green]💡 Suggested fix:[/green] {escape(item.suggested_fix.description)}")++ if item.field_path:+ console.print(f" [dim]└─ Path: {escape(item.field_path)}[/dim]")+ if item.source:+ console.print(f" [dim]└─ Source: {escape(item.source)}[/dim]")++ console.print()- Args:- console: Rich console instance to print to- exc: The bundle validation error exception- """- # Display blueprint validation errors (e.g., MISSING_INPUT_VARIABLE, EXTRANEOUS_INPUT_VARIABLE from blueprint validation)- if exc.pipelex_bundle_blueprint_validation_errors:- console.print("[bold cyan]Blueprint Validation Errors:[/bold cyan]\n")- for error_index, blueprint_error in enumerate(exc.pipelex_bundle_blueprint_validation_errors, 1):- error_type_display = blueprint_error.error_type.replace("_", " ").title() if blueprint_error.error_type else "Validation Error"- console.print(f"[bold yellow]{error_index}. {error_type_display}[/bold yellow]")-- # Display key identification info- if blueprint_error.pipe_code:- console.print(f" [cyan]Pipe:[/cyan] [yellow]{escape(blueprint_error.pipe_code)}[/yellow]")- if blueprint_error.domain_code:- console.print(f" [cyan]Domain:[/cyan] [green]{escape(blueprint_error.domain_code)}[/green]")-- # Variables- if blueprint_error.variable_names:- variables_str = ", ".join([f"[yellow]{escape(v)}[/yellow]" for v in blueprint_error.variable_names])- console.print(f" [cyan]Variables:[/cyan] {variables_str}")-- # Error message- console.print(f" [cyan]→[/cyan] {escape(blueprint_error.message)}")-- # Source file- if blueprint_error.source:- console.print(f" [dim]└─ Source: {escape(blueprint_error.source)}[/dim]")-- console.print()-- # Display pipe validation errors- if exc.pipe_validation_errors:- console.print("[bold cyan]Pipe Validation Errors:[/bold cyan]\n")- for pipe_index, pipe_error in enumerate(exc.pipe_validation_errors, 1):- console.print(f"[bold yellow]{pipe_index}. {pipe_error.error_type.replace('_', ' ').title()}[/bold yellow]")-- # Display key identification info- if pipe_error.pipe_code:- console.print(f" [cyan]Pipe:[/cyan] [yellow]{escape(pipe_error.pipe_code)}[/yellow]")- if pipe_error.concept_code:- console.print(f" [cyan]Concept:[/cyan] [yellow]{escape(pipe_error.concept_code)}[/yellow]")- if pipe_error.domain_code:- console.print(f" [cyan]Domain:[/cyan] [green]{escape(pipe_error.domain_code)}[/green]")-- # Field name if present- if pipe_error.field_name:- console.print(f" [cyan]Field:[/cyan] [yellow]{escape(pipe_error.field_name)}[/yellow]")-- # Variables- if pipe_error.variable_names:- variables_str = ", ".join([f"[yellow]{escape(v)}[/yellow]" for v in pipe_error.variable_names])- console.print(f" [cyan]Variables:[/cyan] {variables_str}")-- # Error message- console.print(f" [cyan]→[/cyan] {escape(pipe_error.message)}")-- # Field path as secondary info- if pipe_error.field_path:- console.print(f" [dim]└─ Path: {escape(pipe_error.field_path)}[/dim]")-- console.print()-- # Display dry run error message- if exc.dry_run_error_message:- console.print("[bold cyan]Dry Run Error:[/bold cyan]\n")- console.print(f"[yellow]{escape(exc.dry_run_error_message)}[/yellow]\n")+def display_validation_error_items(console: Console, *, items: list[ValidationErrorItem]) -> None:+ """Render structured validation-error items grouped by category, with per-item suggested fixes.-def handle_validate_bundle_error(exc: ValidateBundleError, *, bundle_path: Path | None = None) -> NoReturn:+ The single human renderer for bundle-validation diagnostics — used by ``pipelex validate``+ (via :func:`handle_validate_bundle_error`) and by ``pipelex fix``'s still-invalid arm+ (``remaining_errors``), so the two commands cannot drift. Items come from the shared+ ``build_validation_error_items`` builder, which is also what attaches ``suggested_fix``.+ """+ items_by_category: dict[ValidationErrorCategory, list[ValidationErrorItem]] = {}+ for item in items:+ items_by_category.setdefault(item.category, []).append(item)++ for category in ValidationErrorCategory:+ category_items = items_by_category.get(category, [])+ if not category_items:+ continue+ console.print(f"[bold cyan]{_validation_category_header(category)}[/bold cyan]\n")+ match category:+ case ValidationErrorCategory.DRY_RUN:+ # The dry-run residual is a single graph-level message with no identity fields —+ # keep its historical plain rendering rather than a numbered item.+ for item in category_items:+ console.print(f"[yellow]{escape(item.message)}[/yellow]\n")+ case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:+ for error_index, item in enumerate(category_items, 1):+ _display_validation_error_item(console, item=item, error_index=error_index)+++def handle_validate_bundle_error(+ exc: ValidateBundleError,+ *,+ bundle_path: Path | None = None,+ library_dirs: list[Path] | None = None,+ allow_signatures: bool = False,+) -> NoReturn:"""Handle and display ValidateBundleError with formatted output.Args:exc: The bundle validation error exceptionbundle_path: Optional path to the bundle file being validated+ library_dirs: The ``-L/--library-dir`` values of the invocation, echoed into the+ actionable ``pipelex fix bundle`` footer so the suggested command reproduces the+ same write scope+ allow_signatures: Whether the invocation accepted PipeSignature placeholders; when true,+ the actionable fix command preserves the same leniency."""report = exc.to_error_report()+ items = list(report.validation_errors or [])console = get_console()print_traceback_if_requested(console)console.print("\n[bold red]❌ Bundle validation failed[/bold red]\n")@@ -335,13 +355,30 @@ def handle_validate_bundle_error(exc: ValidateBundleError, *, bundle_path: Pathif bundle_path:console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{escape(str(bundle_path))}[/yellow]\n")- _display_validation_error_details(console=console, exc=exc)+ display_validation_error_items(console, items=items)- # Display helpful tips- tip = report.user_action_detail() or (- "Review the error messages above and check your pipeline configuration. Make sure all required fields are present and correctly formatted."- )- console.print(f"[bold green]💡 Tip:[/bold green] {escape(tip)}")+ # The shared items builder projects the dry-run channel only when it is the sole failure+ # channel (the wire's structured-info invariant); the human surface keeps printing it+ # alongside categorized errors so no diagnostic is lost.+ if exc.dry_run_error_message and not any(item.category.is_dry_run for item in items):+ console.print("[bold cyan]Dry Run Error:[/bold cyan]\n")+ console.print(f"[yellow]{escape(exc.dry_run_error_message)}[/yellow]\n")++ # A hint needs an action behind it: when fixes exist, the actionable footer replaces the+ # generic tip (two stacked 💡 tips would be noise).+ fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs) if bundle_path is not None else 0+ if fixable_count and bundle_path is not None:+ # Shared builder so the human and agent fix-command footers echo -L / --allow-signatures identically.+ fix_command = build_fix_command("pipelex", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)+ console.print(+ f"[bold green]💡 {fixable_count} of these errors can be fixed automatically[/bold green] — run: [cyan]{escape(fix_command)}[/cyan]"+ )+ else:+ tip = report.user_action_detail() or (+ "Review the error messages above and check your pipeline configuration. "+ "Make sure all required fields are present and correctly formatted."+ )+ console.print(f"[bold green]💡 Tip:[/bold green] {escape(tip)}")console.print(f"[dim]Learn more: {URLs.documentation}[/dim]")console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")raise typer.Exit(1) from excdiff --git a/pipelex/core/bundles/exceptions.py b/pipelex/core/bundles/exceptions.pyindex 6732388e0..563c1fbbb 100644--- a/pipelex/core/bundles/exceptions.py+++ b/pipelex/core/bundles/exceptions.py@@ -1,12 +1,40 @@-from enum import StrEnum-from pydantic import BaseModelfrom pipelex.core.pipes.exceptions import PipeValidationErrorType-class PipelexBundleBlueprintFixableErrorType(StrEnum):- """Types of validation errors in Pipelex bundle blueprints that the build agent can address."""+class NativeConceptRedeclarationError(ValueError):+ """A bundle declares a concept whose code collides with a native Pipelex concept.++ Subclasses ``ValueError`` so a ``mode="before"`` pydantic field validator can raise it and+ pydantic preserves it in ``ctx["error"]``; the blueprint categorizer unwraps it structurally+ to recover ``concept_code`` (which a bare ``ValueError`` leaves buried in the message text).+ Carrying the offending code is what lets the fix planner emit a targeted delete.+ """++ def __init__(self, message: str, concept_code: str):+ self.concept_code = concept_code+ super().__init__(message)+++class InvalidPipeCodeSyntaxError(ValueError):+ """A same-domain over-qualified pipe code the fix planner can strip back to its bare form.++ Raised (in place of a bare ``ValueError``) only at the two snake_case-enforcing raise sites —+ a ``[pipe."<domain>.<code>"]`` declaration key and a ``main_pipe = "<domain>.<code>"`` value —+ and only when the code is safely strippable: the prefix equals the bundle's own ``domain``, the+ bare tail is itself a valid snake_case code, and (for a declaration) no bare code already+ occupies that key. Subclasses ``ValueError`` so a ``mode="before"`` field validator can raise+ it and pydantic keeps it in ``ctx["error"]`` for the categorizer to unwrap structurally —+ carrying the ``stripped_code`` (and, for a declaration, the ``offending_code`` to rename from)+ that the ``strip-namespace`` planner needs. Genuinely malformed codes and cross-package dotted+ refs stay bare ``ValueError``s → uncategorized-as-fixable, so they are never stripped.+ """++ def __init__(self, message: str, offending_code: str, stripped_code: str):+ self.offending_code = offending_code+ self.stripped_code = stripped_code+ super().__init__(message)class PipelexBundleBlueprintValidationErrorData(BaseModel):@@ -23,3 +51,9 @@ class PipelexBundleBlueprintValidationErrorData(BaseModel):concept_code: str | None = Nonemessage: strvariable_names: list[str] | None = None++ # The namespace-stripped bare code for a strippable same-domain over-qualified pipe code+ # (``strip-namespace`` enrichment). Present only when the fix planner can act; ``pipe_code``+ # discriminates the two raise sites — set to the offending dotted code for a declaration-key+ # rename, ``None`` for a ``main_pipe`` value strip (which is a root ``set_key``, not a rename).+ stripped_pipe_code: str | None = Nonediff --git a/pipelex/core/bundles/pipelex_bundle_blueprint.py b/pipelex/core/bundles/pipelex_bundle_blueprint.pyindex 62ae98a36..91526f16b 100644--- a/pipelex/core/bundles/pipelex_bundle_blueprint.py+++ b/pipelex/core/bundles/pipelex_bundle_blueprint.py@@ -1,9 +1,10 @@from enum import StrEnumfrom typing import Annotated, Any, cast-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator, model_validatorfrom pydantic.json_schema import SkipJsonSchema+from pipelex.core.bundles.exceptions import InvalidPipeCodeSyntaxError, NativeConceptRedeclarationErrorfrom pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprintfrom pipelex.core.concepts.native.concept_native import NativeConceptCode@@ -27,6 +28,31 @@ from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStructfrom pipelex.pipe_signature.pipe_signature_blueprint import PipeSignatureBlueprintfrom pipelex.urls import URLs++def _strippable_same_domain_pipe_code(code: str, *, domain: str | None, existing_pipe_codes: set[str] | None = None) -> str | None:+ """Return the namespace-stripped bare code when ``code`` is a safely-strippable same-domain+ over-qualification (``<domain>.<bare>``), else ``None`` — the raise-site gate for+ ``strip-namespace``.++ Strippable requires: a dotted code whose prefix equals the bundle's own ``domain``, a bare tail+ that is itself a valid snake_case pipe code, and — for a declaration key, where+ ``existing_pipe_codes`` is supplied — no bare code already occupying that key (the rename would+ collide). ``main_pipe`` passes ``existing_pipe_codes=None``: it is a single value, not a table+ key, and the ``pipe`` field is not yet validated when the ``main_pipe`` validator runs — its+ safety gate lives in the blueprint categorizer (``_main_pipe_strip_is_safe``), which holds the+ raw bundle dict and drops the enrichment when stripping would retarget ``main_pipe`` to a+ different declaration or rewrite it to a pipe that does not exist.+ """+ if domain is None or "." not in code:+ return None+ prefix, bare = code.rsplit(".", 1)+ if prefix != domain or not is_pipe_code_valid(bare):+ return None+ if existing_pipe_codes is not None and bare in existing_pipe_codes:+ return None+ return bare++PipeBlueprintUnion = Annotated[PipeFuncBlueprint| PipeImgGenBlueprint@@ -110,22 +136,29 @@ class PipelexBundleBlueprint(BaseModel):f"Native concepts are: {', '.join(native_concept_codes)}. "f"See {URLs.native_concepts_docs}")- raise ValueError(msg)+ # Typed (still a ValueError, so pydantic wraps it into ``ctx["error"]``) so the+ # blueprint categorizer recovers the offending code structurally for the fix planner.+ raise NativeConceptRedeclarationError(msg, concept_code=concept_code)return concept@field_validator("main_pipe", mode="before")@classmethod- def validate_main_pipe_syntax(cls, main_pipe: str | None) -> str | None:+ def validate_main_pipe_syntax(cls, main_pipe: str | None, info: ValidationInfo) -> str | None:if main_pipe is None:return Noneif not is_pipe_code_valid(main_pipe):msg = f"Invalid main pipe syntax '{main_pipe}'. Must be in snake_case."+ stripped = _strippable_same_domain_pipe_code(main_pipe, domain=cast("str | None", info.data.get("domain")))+ if stripped is not None:+ # Typed (still a ValueError, so pydantic wraps it into ``ctx["error"]``) so the+ # blueprint categorizer recovers the strip target structurally for the fix planner.+ raise InvalidPipeCodeSyntaxError(msg, offending_code=main_pipe, stripped_code=stripped)raise ValueError(msg)return main_pipe@field_validator("pipe", mode="before")@classmethod- def validate_pipe_keys(cls, pipe: Any) -> Any:+ def validate_pipe_keys(cls, pipe: Any, info: ValidationInfo) -> Any:"""Validate pipe codes and normalize typeless sections before the discriminated union runs.A `[pipe.x]` section with no `type` whose keys are exactly the signature contract@@ -141,10 +174,17 @@ class PipelexBundleBlueprint(BaseModel):# Let the field type raise its own "should be a dict" error.return pipetyped_pipe = cast("dict[Any, Any]", pipe)+ domain = cast("str | None", info.data.get("domain"))+ existing_pipe_codes = {key for key in typed_pipe if isinstance(key, str)}normalized: dict[Any, Any] = {}for pipe_code, pipe_section in typed_pipe.items():if isinstance(pipe_code, str) and not is_pipe_code_valid(pipe_code=pipe_code):msg = f"Pipe code '{pipe_code}' is not a valid pipe code. Must be in snake_case."+ stripped = _strippable_same_domain_pipe_code(pipe_code, domain=domain, existing_pipe_codes=existing_pipe_codes)+ if stripped is not None:+ # Typed (still a ValueError) so the categorizer recovers the rename target+ # (offending dotted key + stripped bare key) structurally for the fix planner.+ raise InvalidPipeCodeSyntaxError(msg, offending_code=pipe_code, stripped_code=stripped)raise ValueError(msg)normalized[pipe_code] = normalize_typeless_signature_section(pipe_code, pipe_section=pipe_section)return normalizeddiff --git a/pipelex/core/exceptions.py b/pipelex/core/exceptions.pyindex af5e2d601..222cbfaad 100644--- a/pipelex/core/exceptions.py+++ b/pipelex/core/exceptions.py@@ -60,3 +60,21 @@ class PipesAndConceptValidationErrorData(BaseModel):# === Variable names for input/output errors ===variable_names: list[str] | None = Field(default=None, description="Variable names (for input errors)")++ # === Enriched expected value (for output-mismatch errors) ===+ expected_output_ref: str | None = Field(+ default=None,+ description="The output ref the pipe should declare (bundle representation), set when the validator knows the correct value",+ )++ # === Enriched expected inputs mapping (for controller input-drift errors) ===+ expected_inputs: dict[str, str] | None = Field(+ default=None,+ description="The full inputs mapping the pipe should declare (variable name → bundle-representation ref), "+ "set when the validator knows the correct value",+ )+ declared_inputs: dict[str, str] | None = Field(+ default=None,+ description="The pipe's currently declared inputs mapping, rendered like expected_inputs, "+ "so a fix planner can diff the two without file access",+ )diff --git a/pipelex/core/interpreter/validation_error_categorizer.py b/pipelex/core/interpreter/validation_error_categorizer.pyindex 4770057eb..f574726cf 100644--- a/pipelex/core/interpreter/validation_error_categorizer.py+++ b/pipelex/core/interpreter/validation_error_categorizer.py@@ -5,6 +5,8 @@ from pydantic_core import ErrorDetailsfrom pipelex import logfrom pipelex.core.bundles.exceptions import (+ InvalidPipeCodeSyntaxError,+ NativeConceptRedeclarationError,PipelexBundleBlueprintValidationErrorData,)from pipelex.core.interpreter.helpers import ValidationErrorScope, get_error_scope@@ -13,6 +15,8 @@ from pipelex.core.pipes.handle_pipe_errors import extract_wrapped_pipe_validatioPIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD = "domain"PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD = "source"+PIPELEX_BUNDLE_BLUEPRINT_MAIN_PIPE_FIELD = "main_pipe"+PIPELEX_BUNDLE_BLUEPRINT_PIPE_FIELD = "pipe"# Distinctive fragments of the two type-tag errors raised by the `pipe` before-validators (via# `normalize_typeless_signature_section` in `pipe_blueprint.py`, shared by the blueprint and spec@@ -24,6 +28,70 @@ _MISSING_PIPE_TYPE_MARKER = "has no `type` but declares"_EXPLICIT_SIGNATURE_TAG_MARKER = "is no longer a pipe type"+def _extract_wrapped_native_concept_redeclaration_error(error: ErrorDetails) -> NativeConceptRedeclarationError | None:+ """Extract a ``NativeConceptRedeclarationError`` wrapped by pydantic, or ``None``.++ ``validate_concept_keys`` raises it (a ``ValueError`` subclass) from a ``mode="before"``+ field validator, so pydantic reports a ``value_error`` and keeps the original in+ ``ctx["error"]`` — the same wrapping ``extract_wrapped_pipe_validation_error`` unwraps for+ pipe errors. Structural, never message-matched: the offending ``concept_code`` rides the+ exception itself.+ """+ if error["type"] != "value_error":+ return None+ ctx: dict[str, Any] | None = error.get("ctx")+ if ctx:+ original_error = ctx.get("error")+ if isinstance(original_error, NativeConceptRedeclarationError):+ return original_error+ return None+++def _extract_wrapped_invalid_pipe_code_syntax_error(error: ErrorDetails) -> InvalidPipeCodeSyntaxError | None:+ """Extract an ``InvalidPipeCodeSyntaxError`` wrapped by pydantic, or ``None``.++ Raised (a ``ValueError`` subclass) from the ``main_pipe`` / ``pipe`` ``mode="before"`` field+ validators only when the over-qualified code is safely strippable, so pydantic reports a+ ``value_error`` and keeps the original in ``ctx["error"]`` — the same wrapping the native-concept+ and pipe-error unwraps rely on. Structural, never message-matched: the offending + stripped codes+ ride the exception itself.+ """+ if error["type"] != "value_error":+ return None+ ctx: dict[str, Any] | None = error.get("ctx")+ if ctx:+ original_error = ctx.get("error")+ if isinstance(original_error, InvalidPipeCodeSyntaxError):+ return original_error+ return None+++def _main_pipe_strip_is_safe(*, offending_code: str, stripped_code: str, blueprint_dict: dict[str, Any]) -> bool:+ """Whether stripping ``main_pipe`` is provably safe at the document level.++ The ``main_pipe`` raise site runs before the ``pipe`` field validates, so it cannot see the+ declarations — this categorizer can (it holds the raw bundle dict), making it the document-level+ gate the raise site cannot be. The strip is safe iff EXACTLY ONE of the two codes exists as a+ declaration key:++ - Only the bare tail exists: ``main_pipe`` is an over-qualified *reference* (a same-domain+ qualified ref resolves to the bare pipe), so stripping just normalizes the spelling.+ - Only the dotted code exists: its paired strip-namespace rename will materialize the bare+ target, so the strip converges with it (the loop's cross-file collision split still drops+ the pair together when a sibling file blocks the rename).+ - Both exist: the dotted declaration's own rename is collision-blocked, and stripping+ ``main_pipe`` would silently retarget it from the dotted declaration the author referenced+ to the unrelated bare one — suppressed, ambiguity left to a human.+ - Neither exists (typo'd tail): stripping would rewrite ``main_pipe`` to a pipe that does not+ exist — a SAFE-labeled fix mutating the file while the bundle stays invalid — suppressed.+ """+ raw_pipe = blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_PIPE_FIELD)+ if not isinstance(raw_pipe, dict):+ return False+ pipe_keys = {key for key in cast("dict[Any, Any]", raw_pipe) if isinstance(key, str)}+ return (offending_code in pipe_keys) != (stripped_code in pipe_keys)++def _extract_variable_names_from_message(message: str) -> list[str] | None:"""Extract variable names from error messages like 'Missing input variable(s): var1, var2.'"""# Pattern to match variable names after the colon@@ -276,6 +344,52 @@ def categorize_blueprint_validation_error(variable_names=wrapped_pipe_error.variable_names,)+ # A native-concept redeclaration: ``validate_concept_keys`` raised a typed ``ValueError``+ # carrying the offending code (which the pydantic ``loc`` — ``("concept",)`` — cannot). Recover+ # it structurally so the fix planner can strip exactly that concept key.+ wrapped_native_redeclaration = _extract_wrapped_native_concept_redeclaration_error(error)+ if wrapped_native_redeclaration is not None:+ return PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION,+ domain_code=domain,+ source=source,+ concept_code=wrapped_native_redeclaration.concept_code,+ # The exception's own clean message, not the pydantic ``msg`` (which carries a+ # "Value error, " prefix) — same choice as the wrapped-pipe-error path above.+ message=str(wrapped_native_redeclaration),+ )++ # A strippable same-domain over-qualified pipe code: ``validate_pipe_keys`` /+ # ``validate_main_pipe_syntax`` raised a typed ``ValueError`` carrying the stripped bare code+ # (which the message text and pydantic ``loc`` — ``("pipe",)`` / ``("main_pipe",)`` — cannot).+ # ``pipe_code`` discriminates the two raise sites for the planner: the offending dotted code for+ # a declaration-key rename, ``None`` for a ``main_pipe`` value strip (loc's first element names+ # the field). The bare ``ValueError`` path (malformed codes, cross-package refs) still falls+ # through to the message-matching ``_categorize_syntax_validation_error`` → unfixable.+ #+ # The ``main_pipe`` raise site cannot see the declarations (the ``pipe`` field validates after+ # it), so the safety gate lives here, on the raw bundle dict: a strip that would retarget+ # ``main_pipe`` to a different declaration, or rewrite it to a pipe that does not exist,+ # keeps its category but loses the enrichment → no fix is planned.+ wrapped_invalid_pipe_code = _extract_wrapped_invalid_pipe_code_syntax_error(error)+ if wrapped_invalid_pipe_code is not None:+ is_main_pipe = bool(loc) and loc[0] == PIPELEX_BUNDLE_BLUEPRINT_MAIN_PIPE_FIELD+ stripped_pipe_code: str | None = wrapped_invalid_pipe_code.stripped_code+ if is_main_pipe and not _main_pipe_strip_is_safe(+ offending_code=wrapped_invalid_pipe_code.offending_code,+ stripped_code=wrapped_invalid_pipe_code.stripped_code,+ blueprint_dict=blueprint_dict,+ ):+ stripped_pipe_code = None+ return PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,+ domain_code=domain,+ source=source,+ pipe_code=None if is_main_pipe else wrapped_invalid_pipe_code.offending_code,+ stripped_pipe_code=stripped_pipe_code,+ message=str(wrapped_invalid_pipe_code),+ )+error_scope = get_error_scope(loc)# Categorize based on error scopediff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.pyindex 3b39b5137..7f6dbf6b9 100644--- a/pipelex/core/pipes/exceptions.py+++ b/pipelex/core/pipes/exceptions.py@@ -137,6 +137,11 @@ class PipeValidationErrorType(StrEnum):# assertion can never fire.OPTIONAL_FORCE_REDUNDANT = "optional_force_redundant"+ # Blueprint parse-time concept error: a bundle declares a concept whose code collides with a+ # native Pipelex concept (`Text`, `Number`, …). Structurally suppressible — set only at the+ # single `validate_concept_keys` raise site — so the fix planner keys on it safely.+ NATIVE_CONCEPT_REDECLARATION = "native_concept_redeclaration"+# Wiring / reference-resolution failures, detected when validating a pipe's contract against the# merged library (a referenced concept or dependency pipe does not resolve).UNRESOLVED_CONCEPT = "unresolved_concept"@@ -145,6 +150,168 @@ class PipeValidationErrorType(StrEnum):# Generic fallback for unexpected validation errorsUNKNOWN_VALIDATION_ERROR = "unknown_validation_error"+ @property+ def is_controller_input_drift(self) -> bool:+ """True for the input-drift trio the fix planner can act on when enriched."""+ match self:+ case (+ PipeValidationErrorType.MISSING_INPUT_VARIABLE+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH+ ):+ return True+ case (+ PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE+ | PipeValidationErrorType.MISSING_PIPE_TYPE+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ | PipeValidationErrorType.UNRESOLVED_CONCEPT+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ ):+ return False++ @property+ def is_inadequate_output(self) -> bool:+ """True for the output-mismatch pair the fix planner can act on when enriched."""+ match self:+ case PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:+ return True+ case (+ PipeValidationErrorType.MISSING_INPUT_VARIABLE+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE+ | PipeValidationErrorType.MISSING_PIPE_TYPE+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ | PipeValidationErrorType.UNRESOLVED_CONCEPT+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ ):+ return False++ @property+ def is_inadequate_output_multiplicity(self) -> bool:+ """True only for the multiplicity-mismatch case.++ The required/provided concept-ref suffix appended by the error categorizer is suppressed+ for this case: a multiplicity mismatch has the same concept on both sides by definition+ (the concept-compatibility check passed just before it fired), so the suffix would print+ two identical refs and its list-repr brackets would masquerade as `[]` multiplicity syntax.+ """+ match self:+ case PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:+ return True+ case (+ PipeValidationErrorType.MISSING_INPUT_VARIABLE+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE+ | PipeValidationErrorType.MISSING_PIPE_TYPE+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ | PipeValidationErrorType.UNRESOLVED_CONCEPT+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ ):+ return False++ @property+ def is_native_concept_redeclaration(self) -> bool:+ """True for the blueprint-channel native-concept redeclaration the fix planner strips."""+ match self:+ case PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION:+ return True+ case (+ PipeValidationErrorType.MISSING_INPUT_VARIABLE+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE+ | PipeValidationErrorType.MISSING_PIPE_TYPE+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT+ | PipeValidationErrorType.UNRESOLVED_CONCEPT+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ ):+ return False++ @property+ def is_invalid_pipe_code_syntax(self) -> bool:+ """True for the invalid-pipe-code-syntax error the fix planner strips when it is enriched.++ Gates entry to ``strip-namespace``; the planner still requires the ``stripped_pipe_code``+ enrichment, so un-strippable syntax errors (malformed codes, cross-package dotted refs)+ fall through as ``None`` even though they share this ``error_type``.+ """+ match self:+ case PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX:+ return True+ case (+ PipeValidationErrorType.MISSING_INPUT_VARIABLE+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE+ | PipeValidationErrorType.MISSING_PIPE_TYPE+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ | PipeValidationErrorType.UNRESOLVED_CONCEPT+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ ):+ return False+class PipeValidationError(ValueError):def __init__(@@ -156,6 +323,9 @@ class PipeValidationError(ValueError):variable_names: list[str] | None = None,required_concept_codes: list[str] | None = None,provided_concept_code: str | None = None,+ expected_output_ref: str | None = None,+ expected_inputs: dict[str, str] | None = None,+ declared_inputs: dict[str, str] | None = None,file_path: str | None = None,explanation: str | None = None,):@@ -165,6 +335,18 @@ class PipeValidationError(ValueError):self.variable_names = variable_namesself.required_concept_codes = required_concept_codesself.provided_concept_code = provided_concept_code+ # The output ref the pipe should declare (full bundle representation: concept ++ # multiplicity + presence marker), set only where the validator knows the correct+ # value at detection time — the semantic fact the fix planner translates into a+ # suggested fix.+ self.expected_output_ref = expected_output_ref+ # The full inputs mapping the pipe should declare (variable name → bundle-representation+ # ref), set only at the controller input-drift raise sites where ``needed_inputs()`` is+ # in hand — the semantic fact the fix planner translates into a sync-controller-inputs fix.+ # ``declared_inputs`` is the pipe's current declaration rendered the same way, so the+ # planner (pure, no file access) can emit a minimal diff instead of a table rewrite.+ self.expected_inputs = expected_inputs+ self.declared_inputs = declared_inputsself.file_path = file_pathself.explanation = explanationsuper().__init__(message)@@ -179,6 +361,12 @@ class PipeValidationError(ValueError):msg += f" • required_concept_codes='{self.required_concept_codes}'"if self.provided_concept_code:msg += f" • provided_concept_code='{self.provided_concept_code}'"+ if self.expected_output_ref:+ msg += f" • expected_output_ref='{self.expected_output_ref}'"+ if self.expected_inputs:+ msg += f" • expected_inputs='{self.expected_inputs}'"+ if self.declared_inputs:+ msg += f" • declared_inputs='{self.declared_inputs}'"if self.file_path:msg += f" • file='{self.file_path}'"if self.explanation:diff --git a/pipelex/core/pipes/handle_pipe_errors.py b/pipelex/core/pipes/handle_pipe_errors.pyindex 5826b951c..d9eb70483 100644--- a/pipelex/core/pipes/handle_pipe_errors.py+++ b/pipelex/core/pipes/handle_pipe_errors.py@@ -189,10 +189,14 @@ def categorize_pipe_validation_with_libraries_error(PipesAndConceptValidationErrorData with all relevant fields populated"""message = pipe_error.explanation or str(pipe_error)- if pipe_error.required_concept_codes and pipe_error.provided_concept_code:- message += f" (required: {pipe_error.required_concept_codes}, provided: {pipe_error.provided_concept_code})"-error_type = pipe_error.error_type or PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR+ # The required/provided concept refs are a debugging aid appended to the message. Suppress them+ # for multiplicity errors (identical concept on both sides — see is_inadequate_output_multiplicity)+ # and otherwise render the required refs as joined author-syntax refs, never a Python list repr+ # (whose `['x']` brackets read like MTHDS `[]` multiplicity syntax).+ if not error_type.is_inadequate_output_multiplicity and pipe_error.required_concept_codes and pipe_error.provided_concept_code:+ required_refs = ", ".join(pipe_error.required_concept_codes)+ message += f" (required: {required_refs}, provided: {pipe_error.provided_concept_code})"return PipesAndConceptValidationErrorData(error_type=error_type,domain_code=pipe_error.domain_code,@@ -203,6 +207,9 @@ def categorize_pipe_validation_with_libraries_error(message=message,field_path=pipe_error.file_path or "",variable_names=pipe_error.variable_names,+ expected_output_ref=pipe_error.expected_output_ref,+ expected_inputs=pipe_error.expected_inputs,+ declared_inputs=pipe_error.declared_inputs,)diff --git a/pipelex/core/pipes/pipe_abstract.py b/pipelex/core/pipes/pipe_abstract.pyindex 1c4119438..7f422c11f 100644--- a/pipelex/core/pipes/pipe_abstract.py+++ b/pipelex/core/pipes/pipe_abstract.py@@ -260,6 +260,49 @@ class PipeAbstract(ABC, BaseModel):def generic_validate_output_static(self):self.validate_output_static()+ def _expected_inputs_for_fix(self, needed_inputs: InputStuffSpecs) -> dict[str, str] | None:+ """Render the full needed-inputs mapping a fix would write, or ``None`` for operators.++ Controller-gated: only a controller's ``needed_inputs()`` is a trustworthy ground truth+ for its declared ``inputs`` table (operators re-emit their own declaration). The+ author's declared representation is preserved (keeping their presence marker — presence+ is deliberately not part of the drift contract) whenever the validator would accept it:+ either its concept + multiplicity already match the needed spec, or the needed spec is a+ flexible type (``Dynamic``/``Anything``), which the validator accepts against any concrete+ declaration. This mirrors the flexible-type carve-out in ``generic_validate_inputs_with_library``+ so a co-occurring drift on another input never rewrites a valid concrete declaration back+ to ``Dynamic``/``Anything``. Refs are derived from the needed spec only for variables being+ added or whose concept/multiplicity genuinely changes against a non-flexible need.+ """+ if not self.is_controller:+ return None+ expected_inputs: dict[str, str] = {}+ for named_stuff_spec in needed_inputs.named_stuff_specs:+ var_name = named_stuff_spec.variable_name+ declared_stuff_spec = self.inputs.root.get(var_name)+ if declared_stuff_spec is not None and (+ named_stuff_spec.concept.code in {NativeConceptCode.DYNAMIC, NativeConceptCode.ANYTHING}+ or (declared_stuff_spec.concept == named_stuff_spec.concept and declared_stuff_spec.multiplicity == named_stuff_spec.multiplicity)+ ):+ spec_to_render: StuffSpec = declared_stuff_spec+ else:+ spec_to_render = named_stuff_spec+ expected_inputs[var_name] = spec_to_render.to_bundle_representation(relative_to_domain=self.domain_code)+ return expected_inputs++ def _declared_inputs_for_fix(self) -> dict[str, str] | None:+ """Render the currently declared inputs the same way, or ``None`` for operators.++ Carried alongside ``expected_inputs`` so the fix planner (pure, no file access) can+ emit a minimal diff against the declaration instead of a table rewrite.+ """+ if not self.is_controller:+ return None+ return {+ var_name: declared_stuff_spec.to_bundle_representation(relative_to_domain=self.domain_code)+ for var_name, declared_stuff_spec in self.inputs.root.items()+ }+@finaldef generic_validate_inputs_with_library(self):# First validate required variables are in the inputs (using prefix-based matching)@@ -293,6 +336,8 @@ class PipeAbstract(ABC, BaseModel):domain_code=self.domain_code,pipe_code=self.code,variable_names=[var_name],+ expected_inputs=self._expected_inputs_for_fix(the_needed_inputs),+ declared_inputs=self._declared_inputs_for_fix(),)# TODO: add this to the PipeController validation. (This might need to refactor a little bit how we can override the validation)@@ -310,21 +355,14 @@ class PipeAbstract(ABC, BaseModel):if needed_stuff_spec.concept.code not in {NativeConceptCode.DYNAMIC, NativeConceptCode.ANYTHING} and (declared_stuff_spec.concept != needed_stuff_spec.concept or declared_stuff_spec.multiplicity != needed_stuff_spec.multiplicity):- # Identify the specific mismatched field(s)- mismatch_details: list[str] = []- if declared_stuff_spec.concept != needed_stuff_spec.concept:- mismatch_details.append(f"concept: declared='{declared_stuff_spec.concept}' vs required='{needed_stuff_spec.concept}'")- if declared_stuff_spec.multiplicity != needed_stuff_spec.multiplicity:- mismatch_details.append(- f"multiplicity: declared='{declared_stuff_spec.multiplicity}' vs required='{needed_stuff_spec.multiplicity}'"- )-- mismatch_summary = ", ".join(mismatch_details)+ # Render both specs the way an author would write them in this pipe's domain+ # (bare `Number` / `Text[]`, qualified only for foreign domains) — never the+ # Python repr of the Concept/StuffSpec objects.+ declared_ref = declared_stuff_spec.to_bundle_representation(relative_to_domain=self.domain_code)+ required_ref = needed_stuff_spec.to_bundle_representation(relative_to_domain=self.domain_code)msg = (- f"In the pipe '{self.code}', the input variable '{var_name}' has a stuff spec mismatch.\n"- f"Mismatched field(s): {mismatch_summary}\n"- f"Declared: {declared_stuff_spec}\n"- f"Required: {needed_stuff_spec}"+ f"In pipe '{self.code}', input '{var_name}' is declared as '{declared_ref}' "+ f"but its step needs '{required_ref}'. Update the input to '{required_ref}'.")raise PipeValidationError(message=msg,@@ -332,6 +370,8 @@ class PipeAbstract(ABC, BaseModel):domain_code=self.domain_code,pipe_code=self.code,variable_names=[var_name],+ expected_inputs=self._expected_inputs_for_fix(the_needed_inputs),+ declared_inputs=self._declared_inputs_for_fix(),)# Check that all declared inputs are actually needed@@ -344,6 +384,8 @@ class PipeAbstract(ABC, BaseModel):domain_code=self.domain_code,pipe_code=self.code,variable_names=[input_name],+ expected_inputs=self._expected_inputs_for_fix(the_needed_inputs),+ declared_inputs=self._declared_inputs_for_fix(),)self.validate_inputs_with_library()diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec.py b/pipelex/core/pipes/stuff_spec/stuff_spec.pyindex 2f036273a..989feea34 100644--- a/pipelex/core/pipes/stuff_spec/stuff_spec.py+++ b/pipelex/core/pipes/stuff_spec/stuff_spec.py@@ -19,9 +19,21 @@ class StuffSpec(BaseModel):return self.multiplicityreturn self.multiplicity > 1- def to_bundle_representation(self) -> str:+ def to_bundle_representation(self, *, relative_to_domain: str | None = None) -> str:+ """Render this spec as a bundle ref string (concept + multiplicity + presence marker).++ When ``relative_to_domain`` is given, the concept renders the way an author in that+ domain would write it: bare code when the concept is native or lives in that domain,+ qualified ``domain.Code`` otherwise. Without it, the concept ref is always qualified.+ """+ if relative_to_domain is None:+ concept_ref = self.concept.concept_ref+ elif self.concept.domain_code == relative_to_domain:+ concept_ref = self.concept.code+ else:+ concept_ref = self.concept.simple_concept_refreturn format_concept_with_multiplicity(- self.concept.concept_ref,+ concept_ref,multiplicity=self.multiplicity,presence=self.presence,)diff --git a/pipelex/hub.py b/pipelex/hub.pyindex 1d5bf8fea..9ac1ed2b7 100644--- a/pipelex/hub.py+++ b/pipelex/hub.py@@ -754,14 +754,15 @@ def get_optional_pipe(pipe_code: str) -> PipeAbstract | None:return get_pipelex_hub().get_required_pipe_library().get_optional_pipe(pipe_code=pipe_code)-def get_pipe_source(pipe_code: str) -> Path | None:- """Get the source file path for a pipe.+def get_pipe_source(pipe_code: str) -> str | None:+ """Get the source identifier for a pipe.Args:pipe_code: The pipe code to look up.Returns:- Path to the .mthds file the pipe was loaded from, or None if unknown.+ The source the pipe was loaded from — a filesystem path or a logical URI,+ preserved verbatim — or None if unknown."""return get_pipelex_hub().get_library_manager().get_pipe_source(pipe_code=pipe_code)diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex 1201650eb..dd11d4265 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -28,7 +28,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactoryfrom pipelex.core.qualified_ref import QualifiedReffrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.core.validation import report_validation_error-from pipelex.hub import get_class_registry, get_current_library+from pipelex.hub import get_class_registry, get_current_library, get_current_library_id_or_nonefrom pipelex.libraries.collision_messages import duplicate_ref_msgfrom pipelex.libraries.concept.exceptions import ConceptLibraryErrorfrom pipelex.libraries.concept_reference_validation import validate_concept_references_in_blueprints@@ -98,7 +98,7 @@ class LibraryManager(LibraryManagerAbstract):def __init__(self):# UNTITLED library is the fallback library for all othersself._libraries: dict[str, Library] = {}- self._pipe_source_map: dict[str, Path] = {} # pipe_ref (domain.pipe_code) -> source .mthds file+ self._pipe_source_maps: dict[str, dict[str, str]] = {} # library_id -> pipe_ref -> source identifierself._blueprints: dict[str, list[PipelexBundleBlueprint]] = {} # library_id -> accumulated blueprintsself._crate_cache: dict[str, LibraryCrate] = {} # library_id -> cached crate from get_crate()self._loaded_fingerprints: dict[str, set[str]] = {} # library_id -> set of loaded crate fingerprints@@ -131,11 +131,9 @@ class LibraryManager(LibraryManagerAbstract):if library is None:return Falsetry:- # Remove source map entries for pipes in this library- for pipe_ref in library.pipe_library.root:- self._pipe_source_map.pop(pipe_ref, None)library.teardown()finally:+ self._pipe_source_maps.pop(library_id, None)self._blueprints.pop(library_id, None)self._crate_cache.pop(library_id, None)self._loaded_fingerprints.pop(library_id, None)@@ -156,7 +154,7 @@ class LibraryManager(LibraryManagerAbstract):# teardown can result from a raising library.libraries = list(self._libraries.values())self._libraries = {}- self._pipe_source_map = {}+ self._pipe_source_maps = {}self._blueprints = {}self._crate_cache = {}self._loaded_fingerprints = {}@@ -232,23 +230,29 @@ class LibraryManager(LibraryManagerAbstract):return self._libraries[library_id]@override- def get_pipe_source(self, pipe_code: str) -> Path | None:- """Get the source file path for a pipe.+ def get_pipe_source(self, pipe_code: str) -> str | None:+ """Get the source identifier for a pipe.Args:pipe_code: The pipe code or pipe_ref (domain.code) to look up.Returns:- Path to the .mthds file the pipe was loaded from, or None if unknown.+ The source the pipe was loaded from — a filesystem path or a logical URI+ (e.g. ``api://bundle-0.mthds``), preserved verbatim — or None if unknown."""+ library_id = get_current_library_id_or_none()+ if library_id is None:+ return None+ source_map = self._pipe_source_maps.get(library_id, {})+# Direct lookup by pipe_ref- result = self._pipe_source_map.get(pipe_code)+ result = source_map.get(pipe_code)if result is not None:return result# Bare code fallback: search for a key ending with .pipe_codeif "." not in pipe_code:suffix = f".{pipe_code}"- matches = [path for key, path in self._pipe_source_map.items() if key.endswith(suffix)]+ matches = [path for key, path in source_map.items() if key.endswith(suffix)]if len(matches) == 1:return matches[0]return None@@ -504,7 +508,7 @@ class LibraryManager(LibraryManagerAbstract):# Track source file for this pipe (used by get_pipe_source)source = crate.source_map.get(pipe_ref)if source:- self._pipe_source_map[pipe_ref] = Path(source)+ self._pipe_source_maps.setdefault(library_id, {})[pipe_ref] = sourcelibrary.pipe_library.add_pipes(pipes=all_pipes)diff --git a/pipelex/libraries/library_manager_abstract.py b/pipelex/libraries/library_manager_abstract.pyindex eea984bdc..ad8d1addd 100644--- a/pipelex/libraries/library_manager_abstract.py+++ b/pipelex/libraries/library_manager_abstract.py@@ -56,14 +56,15 @@ class LibraryManagerAbstract(ABC):"""return None- def get_pipe_source(self, pipe_code: str) -> Path | None: # noqa: ARG002- """Get the source file path for a pipe.+ def get_pipe_source(self, pipe_code: str) -> str | None: # noqa: ARG002+ """Get the source identifier for a pipe.Args:pipe_code: The pipe code to look up.Returns:- Path to the .mthds file the pipe was loaded from, or None if unknown.+ The source the pipe was loaded from — a filesystem path or a logical URI,+ preserved verbatim — or None if unknown."""return Nonediff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.pyindex d3ce9786d..5ad92a6e0 100644--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py@@ -9,7 +9,8 @@ from pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundErrorfrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecsfrom pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactoryfrom pipelex.core.pipes.pipe_output import PipeOutput-from pipelex.core.pipes.variable_multiplicity import is_multiplicity_compatible+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec+from pipelex.core.pipes.variable_multiplicity import PresenceMarker, is_multiplicity_compatiblefrom pipelex.core.qualified_ref import QualifiedReffrom pipelex.hub import get_concept_library, get_optional_pipe, get_required_pipefrom pipelex.pipe_controllers.absence_taint import (@@ -67,12 +68,37 @@ class PipeSequence(PipeController):The output of the pipe sequence should match the output of the last step,both in terms of concept compatibility and multiplicity."""- last_step_pipe_code = self.sequential_sub_pipes[-1].pipe_code+ last_sub_pipe = self.sequential_sub_pipes[-1]+ last_step_pipe_code = last_sub_pipe.pipe_code# Skip output validation if the last step is an unresolved cross-package refif QualifiedRef.has_cross_package_prefix(last_step_pipe_code) and get_optional_pipe(pipe_code=last_step_pipe_code) is None:returnlast_step_pipe = get_required_pipe(pipe_code=last_step_pipe_code)+ effective_last_step_output_multiplicity = last_sub_pipe.output_multiplicity+ if not effective_last_step_output_multiplicity:+ effective_last_step_output_multiplicity = last_step_pipe.output.multiplicity++ taint_analysis = self.analyze_taint()++ # The last step's effective output in bundle representation — what the sequence's declared+ # output should be. This is the enriched semantic fact the fix planner needs, rendered the+ # way an author in the sequence's domain would write it, with the effective multiplicity+ # (sub-pipe override wins) and boundary presence. A singular sequence boundary remains+ # optional when its declaration, last step, or taint propagation says it may be absent.+ # Plural outputs must stay plain because the grammar forbids combining multiplicity with+ # a presence marker and represents an absent plural result as an empty list.+ expected_output_presence = PresenceMarker.PLAIN+ if effective_last_step_output_multiplicity is None and (+ self.output.presence.is_optional or last_step_pipe.output.presence.is_optional or taint_analysis.output_taint is not None+ ):+ expected_output_presence = PresenceMarker.OPTIONAL+ expected_output_ref = StuffSpec(+ concept=last_step_pipe.output.concept,+ multiplicity=effective_last_step_output_multiplicity,+ presence=expected_output_presence,+ ).to_bundle_representation(relative_to_domain=self.domain_code)+# Check concept compatibilityif not get_concept_library().is_compatible(tested_concept=last_step_pipe.output.concept, wanted_concept=self.output.concept):msg = (@@ -87,23 +113,19 @@ class PipeSequence(PipeController):pipe_code=self.code,provided_concept_code=last_step_pipe.output.concept.concept_ref,required_concept_codes=[self.output.concept.concept_ref],+ expected_output_ref=expected_output_ref,)- last_sub_pipe = self.sequential_sub_pipes[-1]- effective_last_step_output_multiplicity = last_sub_pipe.output_multiplicity- if not effective_last_step_output_multiplicity:- effective_last_step_output_multiplicity = get_required_pipe(pipe_code=last_sub_pipe.pipe_code).output.multiplicity-# Check multiplicity compatibilityif not is_multiplicity_compatible(source_multiplicity=effective_last_step_output_multiplicity,target_multiplicity=self.output.multiplicity,):+ declared_output_ref = self.output.to_bundle_representation(relative_to_domain=self.domain_code)msg = (- f"PipeSequence output multiplicity mismatch: the sequence '{self.code}' declares "- f"output multiplicity={self.output.multiplicity}, but the last step '{last_step_pipe.code}' "- f"has output multiplicity={effective_last_step_output_multiplicity}. They are not compatible. "- "Update one of them to match the other."+ f"PipeSequence output multiplicity mismatch: the sequence '{self.code}' declares its output as "+ f"'{declared_output_ref}', but its last step '{last_step_pipe.code}' yields '{expected_output_ref}'. "+ f"Update the sequence's output to '{expected_output_ref}' (or change the last step).")raise PipeValidationError(message=msg,@@ -112,11 +134,11 @@ class PipeSequence(PipeController):pipe_code=self.code,provided_concept_code=last_step_pipe.output.concept.concept_ref,required_concept_codes=[self.output.concept.concept_ref],+ expected_output_ref=expected_output_ref,)# The absence-taint boundary check (D6): a maybe-absent slot ending the sequence must be# matched by an optional (`?`) declared output, or the taint silently escapes the boundary.- taint_analysis = self.analyze_taint()if taint_analysis.output_taint is not None and not self.output.presence.is_optional:msg = (f"PipeSequence '{self.code}' output '{self.output.concept.concept_ref}' may resolve absent at run time, "diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.pyindex 567c46d6a..98d1332f9 100644--- a/pipelex/pipeline/exceptions.py+++ b/pipelex/pipeline/exceptions.py@@ -69,6 +69,53 @@ class PipelineManagerAlreadyExistsError(PipelexError):pass+class FixWriteConflictError(PipelexError):+ """A bundle changed after autofix read it but before the atomic commit."""+++class FixTransactionError(PipelexUnexpectedError):+ """An autofix multi-file commit failed and could not be fully rolled back."""+++def _summarize_bundle_validation_message(+ *,+ blueprint_errors: list[PipelexBundleBlueprintValidationErrorData],+ factory_errors: list[PipeFactoryErrorData],+ pipe_validation_errors: list[PipesAndConceptValidationErrorData],+ dry_run_error_message: str | None,+ raw_message: str,+) -> str:+ """Compose a clean, author-facing top-line summary of a bundle-validation failure (disease C).++ The pydantic / interpreter path builds ``raw_message`` by ``str()``-ing a pydantic+ ``ValidationError``, leaking a ``Validation error(s): … Value errors: '<field>': Value error, …``+ dump (and prefixes like ``Pipe validation failed:`` / ``Could not load MTHDS bundle from '…'+ because of:``) into every surface that shows the top-line — the agent JSON ``message`` and the+ API report ``message`` / ``detail``. The per-error item messages are already clean and+ author-facing, so summarize from them instead of the raw pydantic string: the lone item+ message when there is one categorized error, or ``N validation errors (first: …)`` when there+ are several.++ Falls back to ``raw_message`` only when there is no categorized data at all — a parse-level+ failure (TOML syntax, an empty blueprint, a bundle elaborator) whose raw message is the+ authoritative description and the sole diagnostic. Reads only the ``message`` field off each+ error-data model — no fix planning — so it is cheap enough to run in ``__init__``. Ordering+ mirrors ``build_validation_error_items`` (blueprint → factory → pipe/concept → dry-run residual)+ so the "first" message is the same item the structured surfaces list first.+ """+ item_messages = [error.message for error in blueprint_errors]+ item_messages += [error.message for error in factory_errors]+ item_messages += [error.message for error in pipe_validation_errors]+ if not item_messages and dry_run_error_message:+ item_messages = [dry_run_error_message]+ if not item_messages:+ return raw_message+ first_message = item_messages[0]+ if len(item_messages) == 1:+ return first_message+ return f"{len(item_messages)} validation errors (first: {first_message})"++class ValidateBundleError(PipelexError):"""Raised when bundle validation fails.@@ -114,7 +161,22 @@ class ValidateBundleError(PipelexError):self.dry_run_error_message = dry_run_error_message- super().__init__(message)+ # Disease C: the top-line ``message`` is often a leaky ``str(pydantic ValidationError)``+ # (``Value errors: '<field>': Value error, …``). Replace it at the source with a clean+ # summary derived from the already-clean per-error item messages, so EVERY surface that+ # shows the top-line — the agent JSON ``message`` and the API report — benefits (one+ # engine), not just the CLI markdown. The raw ``message`` still rides ``to_error_report``'s+ # ``fallback_message`` residual, which only fires when there is no categorized data (the+ # summary is the raw message in that same case, so the two stay consistent).+ super().__init__(+ _summarize_bundle_validation_message(+ blueprint_errors=self.pipelex_bundle_blueprint_validation_errors,+ factory_errors=self.pipe_factory_errors,+ pipe_validation_errors=self.pipe_validation_error_data,+ dry_run_error_message=self.dry_run_error_message,+ raw_message=message,+ )+ )@propertydef pipe_validation_error_data(self) -> list[PipesAndConceptValidationErrorData]:diff --git a/pipelex/pipeline/fixes/__init__.py b/pipelex/pipeline/fixes/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/pipelex/pipeline/fixes/applicability.py b/pipelex/pipeline/fixes/applicability.pynew file mode 100644index 000000000..0c67c9f41--- /dev/null+++ b/pipelex/pipeline/fixes/applicability.py@@ -0,0 +1,18 @@+"""Shared source and write-scope predicates for autofix execution and CLI hints."""++from collections.abc import Sequence+from pathlib import Path++from pipelex.suggested_fix import SuggestedFix+++def is_safe_fix_for_load_scope(fix: SuggestedFix, *, is_single_file: bool) -> bool:+ """Whether a safe fix has enough source identity for this load scope."""+ if not fix.safety.is_safe:+ return False+ return fix.source is not None or is_single_file+++def is_target_in_write_scope(target_path: Path, *, entry_path: Path, writable_dirs: Sequence[Path]) -> bool:+ """Whether a target is the entry file or lies under an explicitly writable directory."""+ return target_path == entry_path or any(target_path.is_relative_to(writable_dir) for writable_dir in writable_dirs)diff --git a/pipelex/pipeline/fixes/applier.py b/pipelex/pipeline/fixes/applier.pynew file mode 100644index 000000000..8ac72687e--- /dev/null+++ b/pipelex/pipeline/fixes/applier.py@@ -0,0 +1,253 @@+"""Fix applier — applies ``FixOp`` patch ops to a tomlkit DOM, then renders canonical MTHDS.++Two clearly-separated steps, because they preserve different things — do not conflate them:++- ``apply_fix_ops`` mutates the tomlkit DOM **in place**, never rebuilding containers, so at the+ DOM level tomlkit keeps the comments, ordering, and table style of untouched content (and of+ the patched line itself) by construction. A caller that wants the mutated-but-unformatted DOM+ stops here.+- ``serialize_and_format`` then serializes the whole DOM and hands it to the MTHDS formatter+ (``pipelex_tools.format_mthds``) for the one canonical style. This is a **whole-file** reflow:+ the returned text is canonical MTHDS, not a surgical diff — spacing and column alignment of+ *untouched* tables is normalized too (a no-op on already-formatted files, which is the norm,+ since MTHDS is formatted on save + CI-enforced). This is the intended output philosophy for a+ file-rewriting fix tool; it is emphatically not byte-level preservation of untouched lines.++Guarded application: an op only applies when its target table path exists in the DOM. This+protects against errors raised on elaborated/synthetic constructs (a synthesized sequence has no+TOML to patch) and against ops targeting a different file than the one being patched — a skipped+op is reported, never raised.+"""++from enum import StrEnum+from typing import TYPE_CHECKING, Any, cast++import tomlkit+from pipelex_tools import format_mthds+from pydantic import BaseModel, ConfigDict, Field+from tomlkit import TOMLDocument+from tomlkit.container import Container, OutOfOrderTableProxy+from tomlkit.items import AbstractTable, Item++from pipelex.base_exceptions import PipelexUnexpectedError+from pipelex.suggested_fix import FixOp, FixOpKind, TomlValue++if TYPE_CHECKING:+ # ``Diagnostic`` is a type-only TypedDict from the stub — declared in ``__all__`` but not a+ # runtime export of the compiled module, so it must not be imported at runtime.+ from pipelex_tools import Diagnostic+++class FixOpOutcome(StrEnum):+ """What happened to one op during application."""++ APPLIED = "applied"+ SKIPPED = "skipped"++ @property+ def did_apply(self) -> bool:+ match self:+ case FixOpOutcome.APPLIED:+ return True+ case FixOpOutcome.SKIPPED:+ return False+++class FixOpApplication(BaseModel):+ """Per-op application report: the op, whether it applied, and why not when skipped."""++ model_config = ConfigDict(frozen=True, extra="forbid")++ op: FixOp+ outcome: FixOpOutcome = Field(strict=False)+ detail: str | None = None+++def _resolve_table(toml_doc: TOMLDocument, *, table_path: list[str]) -> dict[str, Any] | None:+ """Walk ``table_path`` down the DOM, returning the addressed table or ``None`` when absent.++ Every segment must resolve to a dict-like container (tomlkit tables and inline tables+ all subclass ``dict``); a missing or non-table segment means the target does not exist.+ """+ node = cast("dict[str, Any]", toml_doc)+ for segment in table_path:+ candidate = node.get(segment)+ if not isinstance(candidate, dict):+ return None+ node = cast("dict[str, Any]", candidate)+ return node+++def _rename_key_in_place(parent_table: dict[str, Any], *, key: str, new_key: str) -> None:+ """Rename ``key`` to ``new_key`` in a resolved table node, preserving position and comments.++ tomlkit exposes no public position-preserving rename; ``Container._replace`` is its own+ internal primitive (what ``__setitem__`` uses to re-home an existing key). It swaps the key in+ ``_body`` in place and re-renders the table header, so the renamed table keeps its position+ among siblings and its comments — a ``del`` + re-add would append it to the bottom of the+ parent (the old fixer's reordering bug). The golden byte-compare tests are the CI tripwire if+ a tomlkit bump ever changes this.++ ``_resolve_table`` hands back one of three dict-like shapes, each with its own route to the+ ``Container`` that owns the key:++ - ``OutOfOrderTableProxy`` — ``[pipe.*]`` sections interleaved with other tables: the keys+ live in the proxy's underlying sub-tables, so rename inside **every** one holding ``key``;+ - ``AbstractTable`` — a regular ``Table`` or an inline ``pipe = {...}``: its ``.value``;+ - the root ``TOMLDocument``, itself a ``Container``.+ """+ if isinstance(parent_table, OutOfOrderTableProxy):+ # The same dotted key can appear in MORE THAN ONE sub-table: a pipe whose header+ # ``[pipe."d.x"]`` and whose block ``[pipe."d.x".inputs]`` land in different out-of-order+ # chunks (split by an intervening ``[concept]`` etc.) both carry the key ``d.x``. Renaming+ # only the first would leave the other chunk under the old dotted name — orphaning the+ # pipe's nested content in a phantom, still-invalid key. Rename in every chunk holding it.+ renamed_in_any = False+ for sub_table in parent_table._tables: # noqa: SLF001 # pyright: ignore[reportPrivateUsage]+ if key in sub_table:+ _replace_key_in_container(sub_table.value, key=key, new_key=new_key)+ renamed_in_any = True+ if not renamed_in_any:+ # The caller checked ``key in parent_table``, and the proxy's dict-facade is built from+ # exactly these sub-tables — reaching here means the facade and sub-tables disagree.+ msg = f"key '{key}' not found in any sub-table of the out-of-order table during rename — applier bug"+ raise PipelexUnexpectedError(msg)+ return+ if isinstance(parent_table, AbstractTable):+ _replace_key_in_container(parent_table.value, key=key, new_key=new_key)+ return+ if isinstance(parent_table, Container):+ _replace_key_in_container(parent_table, key=key, new_key=new_key)+ return+ msg = f"cannot rename key in unsupported tomlkit node type '{type(parent_table).__name__}' — applier bug"+ raise PipelexUnexpectedError(msg)+++def _replace_key_in_container(container: Container, *, key: str, new_key: str) -> None:+ container._replace(key, new_key, cast("Item", container[key])) # pyright: ignore[reportPrivateUsage]+++def _as_tomlkit_value(value: TomlValue | None) -> Any:+ """Convert a mapping value to an inline table (`inputs = { ... }`, the dominant authoring+ form), so a freshly-created mapping stays attached to its pipe rather than being emitted as+ a detached ``[pipe.x.inputs]`` block table at the end of the file (what a plain dict assign+ yields). tomlkit owns key quoting and per-value rendering; canonical spacing is the+ formatter's job in ``serialize_and_format``. Scalars pass through — tomlkit wraps them on+ assignment.+ """+ if isinstance(value, dict):+ inline = tomlkit.inline_table()+ for item_key, item_value in value.items():+ inline[item_key] = item_value+ return inline+ return value+++def serialize_and_format(toml_doc: TOMLDocument) -> str:+ """Serialize the mutated DOM and return its canonical MTHDS text.++ The applier mutates in place and leaves formatting alone; the single source of canonical+ style is ``pipelex_tools.format_mthds`` (the same ``taplo``/MTHDS engine the ``plxt`` CLI+ runs on save), which reflows inline-table and array spacing to the canonical form and is a+ no-op on already-canonical files (the norm — MTHDS is formatted on save + CI-enforced). A+ ``kind="syntax"`` diagnostic means the applier emitted malformed TOML — a planner/applier+ bug, never something to write out — so it is raised, not swallowed.+ """+ dumped: str = tomlkit.dumps(toml_doc) # pyright: ignore[reportUnknownMemberType]+ result = format_mthds(dumped)+ syntax_diagnostics = [diagnostic for diagnostic in result["diagnostics"] if diagnostic["kind"] == "syntax"]+ if syntax_diagnostics:+ reported = "; ".join(_render_syntax_diagnostic(diagnostic) for diagnostic in syntax_diagnostics)+ msg = f"fix applier produced malformed TOML (formatter reported: {reported}) — planner/applier bug"+ raise PipelexUnexpectedError(msg)+ return result["formatted"]+++def _render_syntax_diagnostic(diagnostic: "Diagnostic") -> str:+ """One formatter syntax diagnostic as ``message (line L:C)``, keeping the position it carries+ so a planner/applier bug is debuggable from the raised message alone.+ """+ diagnostic_range = diagnostic["range"]+ if diagnostic_range is None:+ return diagnostic["message"]+ return f"{diagnostic['message']} (line {diagnostic_range['start_line']}:{diagnostic_range['start_col']})"+++def apply_fix_ops(toml_doc: TOMLDocument, *, ops: list[FixOp]) -> list[FixOpApplication]:+ """Apply each op to the DOM in place, returning one application report per op, in order.++ Idempotent: re-applying an already-applied op sets the same value / finds the key+ already gone, so the serialized bytes do not change.+ """+ applications: list[FixOpApplication] = []+ for fix_op in ops:+ applications.append(_apply_one_op(toml_doc, fix_op=fix_op))+ return applications+++def _apply_one_op(toml_doc: TOMLDocument, *, fix_op: FixOp) -> FixOpApplication:+ table_path_str = ".".join(fix_op.table_path)+ match fix_op.kind:+ case FixOpKind.SET_KEY:+ if fix_op.key is None or fix_op.value is None:+ msg = f"set_key op on '{table_path_str}' requires both key and value — planner bug"+ raise PipelexUnexpectedError(msg)+ target_table = _resolve_table(toml_doc, table_path=fix_op.table_path)+ if target_table is None:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' not found in document")+ target_table[fix_op.key] = _as_tomlkit_value(fix_op.value)+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)+ case FixOpKind.ENSURE_TABLE:+ if not fix_op.table_path:+ msg = "ensure_table op requires a non-empty table_path — planner bug"+ raise PipelexUnexpectedError(msg)+ existing_table = _resolve_table(toml_doc, table_path=fix_op.table_path)+ if existing_table is not None:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' already exists")+ parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path[:-1])+ table_key = fix_op.table_path[-1]+ if parent_table is None or table_key in parent_table:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"parent of table '{table_path_str}' not found")+ parent_table[table_key] = tomlkit.inline_table()+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)+ case FixOpKind.DELETE_KEY:+ if fix_op.key is None:+ msg = f"delete_key op on '{table_path_str}' requires a key — planner bug"+ raise PipelexUnexpectedError(msg)+ target_table = _resolve_table(toml_doc, table_path=fix_op.table_path)+ if target_table is None:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' not found in document")+ if fix_op.key not in target_table:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"key '{fix_op.key}' not found in table '{table_path_str}'")+ del target_table[fix_op.key]+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)+ case FixOpKind.DELETE_TABLE:+ if not fix_op.table_path:+ msg = "delete_table op requires a non-empty table_path — planner bug"+ raise PipelexUnexpectedError(msg)+ parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path[:-1])+ table_key = fix_op.table_path[-1]+ # The final segment must itself be a table — a scalar there is a drifted target+ # (same guarded-skip contract _resolve_table enforces for every other segment).+ if parent_table is None or not isinstance(parent_table.get(table_key), dict):+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"table '{table_path_str}' not found in document")+ del parent_table[table_key]+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)+ case FixOpKind.RENAME_TABLE_KEY:+ if fix_op.key is None or fix_op.new_key is None:+ msg = f"rename_table_key op on '{table_path_str}' requires both key and new_key — planner bug"+ raise PipelexUnexpectedError(msg)+ parent_table = _resolve_table(toml_doc, table_path=fix_op.table_path)+ if parent_table is None or fix_op.key not in parent_table:+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.SKIPPED, detail=f"key '{fix_op.key}' not found in table '{table_path_str}'")+ if fix_op.new_key in parent_table:+ # Collision: the bare name is already taken by a separate declaration — renaming+ # would clobber it. The raise-site guard suppresses this case, but the applier+ # stays defensive (a stale fix from a prior loop iteration could reach here).+ return FixOpApplication(+ op=fix_op,+ outcome=FixOpOutcome.SKIPPED,+ detail=f"cannot rename to '{fix_op.new_key}': already present in table '{table_path_str}'",+ )+ _rename_key_in_place(parent_table, key=fix_op.key, new_key=fix_op.new_key)+ return FixOpApplication(op=fix_op, outcome=FixOpOutcome.APPLIED)diff --git a/pipelex/pipeline/fixes/fix_loop.py b/pipelex/pipeline/fixes/fix_loop.pynew file mode 100644index 000000000..d5033d841--- /dev/null+++ b/pipelex/pipeline/fixes/fix_loop.py@@ -0,0 +1,690 @@+"""Fix convergence loop — validate → collect SAFE fixes → apply per file → re-validate.++Reuses ``validate_bundle`` wholesale (THE validator — no parallel validation pipeline).+Cascades are expected: fixing one pipe can surface the next mismatch, so the loop runs to a+fixed point bounded by ``max_iterations``. Non-convergence is a first-class, loudly-reported+outcome: a fix fingerprint proposed twice (e.g. its ops target a synthetic pipe the applier+skips) ends the loop with a ``bail_reason`` instead of spinning.++Multi-file targeting: each fix carries the declaring file as ``source`` (backfilled at the+``validate_bundle`` catch boundary from the library manager's pipe-source map), and the loop+applies it to that file — grouping the iteration's fixes per target, one tomlkit DOM per file.+Two scoping rules bound what gets touched:++- **Single-file gate** (source-less fixes): derived from the RESOLVED library dirs+ (``resolve_library_dirs``), not the raw argument — an explicit ``[]`` is genuinely+ single-file, while a ``None`` that falls through to ambient dirs (hub defaults,+ ``PIPELEXPATH``) is multi-file, where a source-less fix could patch the wrong same-named+ table and is conservatively dropped.+- **Write scope**: only files the user passed to THIS command are ever written — the entry+ file plus ``.mthds`` files under the per-call ``library_dirs``. Fixes sourced at files+ loaded via ambient resolution are excluded; when every fix is out of scope the loop bails+ loudly, naming the files and the ``-L`` remedy.+"""++import os+import stat+import sys+import tempfile+from collections.abc import Sequence+from pathlib import Path+from typing import Any, NamedTuple, cast++import tomlkit+from pydantic import BaseModel, ConfigDict, Field++from pipelex.base_exceptions import ValidationErrorItem+from pipelex.config import get_config+from pipelex.core.pipes.pipe_blueprint import SIGNATURE_ONLY_KEYS+from pipelex.hub import resolve_library_dirs+from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs+from pipelex.pipeline.exceptions import FixTransactionError, FixWriteConflictError, ValidateBundleError+from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scope+from pipelex.pipeline.fixes.applier import apply_fix_ops, serialize_and_format+from pipelex.pipeline.validate_bundle import validate_bundle+from pipelex.pipeline.validation_errors import build_validation_error_items+from pipelex.suggested_fix import FixOp, FixOpKind, SuggestedFix+from pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.toml_utils import load_toml_from_path++_MAIN_PIPE_KEY = "main_pipe"+++class _FileSnapshot(NamedTuple):+ """Bytes and permission bits read from one target before fixes are applied."""++ path: Path+ content: bytes+ mode: int+ device: int+ inode: int+++class _PendingFileUpdate(NamedTuple):+ """A fully rendered replacement paired with the snapshot it was derived from."""++ snapshot: _FileSnapshot+ new_content: str+++class _StagedFileUpdate(NamedTuple):+ """Same-directory temp files for one replacement and its rollback copy."""++ snapshot: _FileSnapshot+ replacement_snapshot: _FileSnapshot+ rollback_path: Path+++class _BoundFix(NamedTuple):+ """A suggested fix pinned to the source identity snapshotted before validation."""++ fix: SuggestedFix+ snapshot: _FileSnapshot++ @property+ def target_path(self) -> Path:+ return self.snapshot.path+++def _read_file_snapshot(path: Path) -> _FileSnapshot:+ """Read bytes and mode from one open file descriptor, avoiding split stat/read state."""+ with path.open("rb") as file:+ content = file.read()+ file_stat = os.fstat(file.fileno())+ return _FileSnapshot(+ path=path,+ content=content,+ mode=stat.S_IMODE(file_stat.st_mode),+ device=file_stat.st_dev,+ inode=file_stat.st_ino,+ )+++def _write_staged_file(snapshot: _FileSnapshot, *, content: bytes, label: str) -> Path:+ """Write and fsync a same-directory temp file ready for atomic replacement."""+ temp_file = tempfile.NamedTemporaryFile( # noqa: SIM115 - closed before the atomic replace+ mode="wb",+ dir=str(snapshot.path.parent),+ prefix=f".{snapshot.path.name}.pipelex-fix-{label}.",+ suffix=".tmp",+ delete=False,+ )+ temp_path = Path(temp_file.name)+ try:+ try:+ temp_file.write(content)+ os.fchmod(temp_file.fileno(), snapshot.mode)+ temp_file.flush()+ os.fsync(temp_file.fileno())+ finally:+ temp_file.close()+ except OSError:+ temp_path.unlink(missing_ok=True)+ raise+ return temp_path+++def _stage_file_update(update: _PendingFileUpdate) -> _StagedFileUpdate:+ replacement_path = _write_staged_file(update.snapshot, content=update.new_content.encode("utf-8"), label="new")+ try:+ replacement_snapshot = _read_file_snapshot(replacement_path)+ rollback_path = _write_staged_file(update.snapshot, content=update.snapshot.content, label="rollback")+ except OSError:+ replacement_path.unlink(missing_ok=True)+ raise+ return _StagedFileUpdate(snapshot=update.snapshot, replacement_snapshot=replacement_snapshot, rollback_path=rollback_path)+++def _file_state_matches(current_snapshot: _FileSnapshot, *, expected_snapshot: _FileSnapshot) -> bool:+ """Whether content, permissions, and filesystem identity still match an observed file."""+ return (+ current_snapshot.content == expected_snapshot.content+ and current_snapshot.mode == expected_snapshot.mode+ and current_snapshot.device == expected_snapshot.device+ and current_snapshot.inode == expected_snapshot.inode+ )+++def _assert_snapshot_unchanged(snapshot: _FileSnapshot) -> None:+ """Verify that a path still names the exact file state previously observed."""+ try:+ current_snapshot = _read_file_snapshot(snapshot.path)+ except FileNotFoundError as exc:+ msg = f"refusing to overwrite '{snapshot.path}': the file was removed while fixes were being prepared"+ raise FixWriteConflictError(msg) from exc+ if not _file_state_matches(current_snapshot, expected_snapshot=snapshot):+ msg = f"refusing to overwrite '{snapshot.path}': the file changed while fixes were being prepared"+ raise FixWriteConflictError(msg)+++def _rollback_committed_updates(committed_updates: list[_StagedFileUpdate]) -> list[str]:+ """Restore targets still owned by this transaction, returning rollback failures."""+ failures: list[str] = []+ for staged_update in reversed(committed_updates):+ target_path = staged_update.snapshot.path+ try:+ current_snapshot = _read_file_snapshot(target_path)+ if not _file_state_matches(current_snapshot, expected_snapshot=staged_update.replacement_snapshot):+ failures.append(f"{target_path}: file changed after the autofix replacement was committed")+ continue+ staged_update.rollback_path.replace(target_path)+ except OSError as exc:+ failures.append(f"{target_path}: {exc}")+ return failures+++def _commit_staged_updates(staged_updates: list[_StagedFileUpdate]) -> None:+ committed_updates: list[_StagedFileUpdate] = []+ try:+ for staged_update in staged_updates:+ # Accepted portability tradeoff: this check and Path.replace() are not one compare-and-swap operation.+ # An edit in the tiny gap can be overwritten; keep this portable unless real-world evidence justifies serialization.+ _assert_snapshot_unchanged(staged_update.snapshot)+ staged_update.replacement_snapshot.path.replace(staged_update.snapshot.path)+ committed_updates.append(staged_update)+ except (FixWriteConflictError, OSError) as exc:+ rollback_failures = _rollback_committed_updates(committed_updates)+ if rollback_failures:+ failures = "; ".join(rollback_failures)+ msg = f"autofix commit failed and rollback was incomplete ({failures}); inspect the named files before retrying"+ raise FixTransactionError(msg) from exc+ raise+++def _cleanup_staged_updates(staged_updates: list[_StagedFileUpdate]) -> list[str]:+ """Remove transaction temps and record cleanup failures for the caller to report."""+ failures: list[str] = []+ for staged_update in staged_updates:+ for temp_path in (staged_update.replacement_snapshot.path, staged_update.rollback_path):+ try:+ temp_path.unlink(missing_ok=True)+ except OSError as exc:+ failures.append(f"{temp_path}: {exc}")+ return failures+++def _commit_file_updates(updates: list[_PendingFileUpdate]) -> None:+ """Stage a round completely, then atomically replace targets with rollback on failure."""+ staged_updates: list[_StagedFileUpdate] = []+ try:+ for update in updates:+ staged_updates.append(_stage_file_update(update))+ _commit_staged_updates(staged_updates)+ finally:+ cleanup_failures = _cleanup_staged_updates(staged_updates)+ active_exception = sys.exception()+ if cleanup_failures and active_exception is not None:+ active_exception.add_note(f"autofix temporary-file cleanup also failed ({'; '.join(cleanup_failures)})")+ elif cleanup_failures:+ failures = "; ".join(cleanup_failures)+ msg = f"autofix target changes were committed, but temporary-file cleanup failed ({failures})"+ raise FixTransactionError(msg)+++class FixBundleResult(BaseModel):+ """Outcome of one fix run: the final verdict, the work done, and what remains."""++ model_config = ConfigDict(frozen=True, extra="forbid")++ is_valid: bool+ iterations: int+ """Number of apply rounds performed (0 when the bundle was already valid)."""+ fixes_applied: list[SuggestedFix]+ """Fixes with at least one op actually applied, in application order."""+ files_written: list[str] = Field(default_factory=list)+ """Distinct files written, in first-write order across iterations (resolved paths)."""+ remaining_errors: list[ValidationErrorItem]+ """The last failed validation's structured errors; empty when ``is_valid``."""+ pending_signatures: list[str] | None = None+ """Qualified refs still declared as ``PipeSignature`` after a successful validation."""+ is_runnable: bool | None = None+ """Whether the fixed bundle has no pending ``PipeSignature`` placeholders."""+ bail_reason: str | None = None+ """Why the loop stopped early (no-progress repeat, out-of-scope targets, cross-file+ collision, max_iterations), if it did."""+++def _fix_fingerprint(fix: SuggestedFix) -> str:+ """Stable identity of a fix attempt: fix_code + source + each op's (kind, path, key, value, new_key).++ ``new_key`` participates so two ``rename_table_key`` ops that differ only in their target name+ are distinct fingerprints (they would otherwise collide and trip the no-progress bail).+ """+ op_parts = [f"{op.kind}:{'.'.join(op.table_path)}:{op.key}:{op.value!r}:{op.new_key}" for op in fix.ops]+ return f"{fix.fix_code}|{fix.source}|{'|'.join(op_parts)}"+++def _validation_error_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:+ """Project the error's categorized lists into wire items — same channels as ``to_error_report``."""+ return build_validation_error_items(+ blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,+ factory_errors=exc.pipe_factory_errors,+ pipe_validation_errors=exc.pipe_validation_error_data,+ dry_run_error_message=exc.dry_run_error_message,+ fallback_message=exc.message,+ )+++def _pending_signatures_from_validation_result(validation_result: Any) -> list[str]:+ """Pending signatures reported by validation, defaulting to none for success-only mocks."""+ pending_signatures = getattr(validation_result, "pending_signatures", None)+ if not isinstance(pending_signatures, list):+ return []+ typed_pending_signatures = cast("list[Any]", pending_signatures)+ validated_pending_signatures: list[str] = []+ for pipe_ref in typed_pending_signatures:+ if not isinstance(pipe_ref, str):+ return []+ validated_pending_signatures.append(pipe_ref)+ return validated_pending_signatures+++def _absolute_source_path(path: Path) -> Path:+ """Normalize a source pathname without following symlinks."""+ return Path(os.path.abspath(path))+++def _snapshot_loaded_sources(*, entry_source_path: Path, effective_dirs: Sequence[Path]) -> dict[Path, _FileSnapshot]:+ """Snapshot every source identity validation is about to load.++ Keys are lexical absolute source names, while each snapshot is pinned to the destination+ resolved at the same time. The resolved destination is also an alias when unambiguous, which+ accommodates injected managers that already report canonical source paths.+ """+ source_paths: set[Path] = {_absolute_source_path(entry_source_path)}+ source_paths.update(+ _absolute_source_path(mthds_path)+ for mthds_path in get_pipelex_mthds_files_from_dirs(dirs={_absolute_source_path(directory) for directory in effective_dirs})+ )+ snapshots_by_source: dict[Path, _FileSnapshot] = {}+ for source_path in sorted(source_paths, key=str):+ target_path = source_path.resolve()+ snapshot = _read_file_snapshot(target_path)+ snapshots_by_source[source_path] = snapshot+ snapshots_by_source.setdefault(target_path, snapshot)+ return snapshots_by_source+++def _bind_fixes_to_snapshots(+ fixes: list[SuggestedFix],+ *,+ entry_source_path: Path,+ snapshots_by_source: dict[Path, _FileSnapshot],+) -> list[_BoundFix]:+ """Bind each fix once to the pre-validation file identity that supplied its source."""+ bound_fixes: list[_BoundFix] = []+ for fix in fixes:+ source_path = entry_source_path if fix.source is None else Path(fix.source)+ absolute_source = _absolute_source_path(source_path)+ snapshot = snapshots_by_source.get(absolute_source)+ if snapshot is None:+ msg = f"refusing to apply fix from '{absolute_source}': its source identity changed during validation"+ raise FixWriteConflictError(msg)+ try:+ current_target = absolute_source.resolve(strict=True)+ except FileNotFoundError as exc:+ msg = f"refusing to apply fix from '{absolute_source}': its source was removed during validation"+ raise FixWriteConflictError(msg) from exc+ if current_target != snapshot.path:+ msg = f"refusing to apply fix from '{absolute_source}': its source was retargeted during validation"+ raise FixWriteConflictError(msg)+ _assert_snapshot_unchanged(snapshot)+ bound_fixes.append(_BoundFix(fix=fix, snapshot=snapshot))+ return bound_fixes+++def _safe_fixes(+ items: list[ValidationErrorItem],+ *,+ is_single_file: bool,+ select_codes: Sequence[str] | None,+ ignore_codes: Sequence[str] | None,+) -> list[SuggestedFix]:+ """SAFE fixes whose target file is provable, filtered by the caller's rule selection.++ A source-less fix is only trustworthy under single-file validation: with library files+ merged in, a same-named pipe from another domain could resolve to this file's table+ (pipe codes are only unique per domain), so source-less fixes are dropped rather than+ risk patching an unrelated pipe.++ ``select_codes`` keeps only the named rules; ``ignore_codes`` drops them. Code validation+ (unknown code → loud rejection) belongs to the CLI layer, not here — the loop just filters.+ """+ fixes: list[SuggestedFix] = []+ for item in items:+ suggested_fix = item.suggested_fix+ if suggested_fix is None or not is_safe_fix_for_load_scope(suggested_fix, is_single_file=is_single_file):+ continue+ if select_codes is not None and suggested_fix.fix_code not in select_codes:+ continue+ if ignore_codes is not None and suggested_fix.fix_code in ignore_codes:+ continue+ fixes.append(suggested_fix)+ return fixes+++def _partition_by_write_scope(+ fixes: list[_BoundFix],+ *,+ entry_path: Path,+ writable_dirs: Sequence[Path],+) -> tuple[list[_BoundFix], list[Path]]:+ """Split fixes into (writable, out-of-scope target paths).++ Writable = the entry file, plus anything under a per-call ``library_dirs`` directory.+ Files loaded via ambient resolution (hub defaults, ``PIPELEXPATH``) are read-only: the+ user did not pass them to THIS command, so their fixes are excluded rather than applied.+ """+ in_scope: list[_BoundFix] = []+ out_of_scope_paths: list[Path] = []+ for fix in fixes:+ target_path = fix.target_path+ if is_target_in_write_scope(target_path, entry_path=entry_path, writable_dirs=writable_dirs):+ in_scope.append(fix)+ else:+ out_of_scope_paths.append(target_path)+ return in_scope, out_of_scope_paths+++def _is_signature_pipe_section(pipe_section: Any) -> bool:+ """Whether a raw ``[pipe.<code>]`` section is a typeless contract-only signature."""+ if not isinstance(pipe_section, dict):+ return False+ typed_section = cast("dict[Any, Any]", pipe_section)+ return "type" not in typed_section and all(key in SIGNATURE_ONLY_KEYS for key in typed_section)+++def _pipe_codes_by_file(*, entry_path: Path, effective_dirs: Sequence[Path]) -> dict[Path, set[str]]:+ """Concrete pipe declaration keys of every loaded bundle file, keyed by resolved path.++ Cross-domain on purpose: a bare pipe code must resolve unambiguously across the loaded+ library — ``PipeLibrary.get_optional_pipe`` raises on a bare code declared by two domains —+ so a rename target colliding with a same-named declaration in ANY other loaded file would+ leave the library unloadable. Signature-only headers are excluded: a matching concrete+ definition is allowed to replace a ``PipeSignature`` during crate merge, so treating the+ header as a hard collision would block a valid fix. Rebuilt each iteration: multiple files+ can now mutate per round. A file that fails to parse contributes nothing here — its own+ problems surface through validation, not this scan.+ """+ all_paths: set[Path] = {entry_path}+ all_paths.update(mthds_path.resolve() for mthds_path in get_pipelex_mthds_files_from_dirs(dirs=set(effective_dirs)))+ codes_by_file: dict[Path, set[str]] = {}+ for mthds_path in all_paths:+ try:+ toml_doc = load_toml_from_path(mthds_path)+ except TomlError:+ continue+ pipe_section = toml_doc.get("pipe")+ if isinstance(pipe_section, dict):+ codes_by_file[mthds_path] = {+ key+ for key, section in cast("dict[Any, Any]", pipe_section).items()+ if isinstance(key, str) and not _is_signature_pipe_section(section)+ }+ else:+ codes_by_file[mthds_path] = set()+ return codes_by_file+++def _colliding_op_name(+ fix_op: FixOp,+ *,+ target_file_pipe_codes: set[str],+ other_file_pipe_codes: set[str],+) -> str | None:+ """The pipe code this op would collide with across files, or ``None`` when it cannot.++ Two op shapes can write a bare pipe code that another loaded file already declares:++ - a ``[pipe]`` ``rename_table_key`` whose ``new_key`` is declared elsewhere — applying it+ would create a duplicate declaration (same domain) or a bare-code ambiguity (another+ domain) that the loop can never repair;+ - a root ``main_pipe`` ``set_key`` whose value is declared elsewhere while the target file+ does NOT declare that value — its paired declaration rename is exactly the case above+ (dropped), so applying the ``set_key`` alone would write an orphaned ``main_pipe``+ pointing at a pipe this file will never declare. If the target file already declares the+ value, the ``main_pipe`` remains bundle-local and safe despite same-named sibling pipes.+ The categorizer cannot see cross-file state, so this suppression lives here.+ """+ match fix_op.kind:+ case FixOpKind.RENAME_TABLE_KEY:+ if fix_op.table_path == ["pipe"] and fix_op.new_key is not None and fix_op.new_key in other_file_pipe_codes:+ return fix_op.new_key+ return None+ case FixOpKind.SET_KEY:+ if (+ not fix_op.table_path+ and fix_op.key == _MAIN_PIPE_KEY+ and isinstance(fix_op.value, str)+ and fix_op.value in other_file_pipe_codes+ and fix_op.value not in target_file_pipe_codes+ ):+ return fix_op.value+ return None+ case FixOpKind.ENSURE_TABLE | FixOpKind.DELETE_KEY | FixOpKind.DELETE_TABLE:+ return None+++def _split_cross_file_collisions(+ fixes: list[_BoundFix],+ *,+ codes_by_file: dict[Path, set[str]],+) -> tuple[list[_BoundFix], list[str]]:+ """Split ``fixes`` into (kept, colliding pipe codes of the dropped ones).++ The raise-site collision gate only sees the one file being validated; in a multi-file run a+ bare pipe of the same name may live in another loaded file, where writing it (as a ``[pipe]``+ key rename or a ``main_pipe`` value) would create a state the loop can never repair. Each+ fix is checked against the pipe codes of every loaded file OTHER than its own target.+ Dropped fixes simply leave their error unfixed (still reported in ``remaining_errors``).+ """+ kept: list[_BoundFix] = []+ colliding_names: list[str] = []+ other_codes_cache: dict[Path, set[str]] = {}+ for fix in fixes:+ target_path = fix.target_path+ target_codes = codes_by_file.get(target_path, set())+ other_codes = other_codes_cache.get(target_path)+ if other_codes is None:+ other_codes = set[str]()+ for file_path, file_codes in codes_by_file.items():+ if file_path != target_path:+ other_codes.update(file_codes)+ other_codes_cache[target_path] = other_codes+ fix_collisions = [+ name+ for fix_op in fix.fix.ops+ if (+ name := _colliding_op_name(+ fix_op,+ target_file_pipe_codes=target_codes,+ other_file_pipe_codes=other_codes,+ )+ )+ is not None+ ]+ if fix_collisions:+ colliding_names.extend(fix_collisions)+ else:+ kept.append(fix)+ return kept, colliding_names+++async def fix_bundle_file(+ mthds_file_path: Path,+ *,+ library_dirs: Sequence[Path] | None = None,+ writable_library_dirs: Sequence[Path] | None = None,+ allow_signatures: bool = False,+ max_iterations: int | None = None,+ select_codes: Sequence[str] | None = None,+ ignore_codes: Sequence[str] | None = None,+) -> FixBundleResult:+ """Fix a bundle in place until valid, out of fixes, no progress, or max_iterations.++ Each iteration: validate; on failure collect the SAFE suggested fixes riding the+ structured errors; group the unseen ones by the file they target (declaring file via+ ``source``, entry file for source-less); apply each group to its file's tomlkit DOM+ (style-preserving) and write the changed files; re-validate. Only fixes with at least one+ applied op count in ``fixes_applied``. ``allow_signatures`` mirrors ``validate bundle``:+ signature placeholders are tolerated for the exit gate only, while the success result still+ reports ``pending_signatures`` and ``is_runnable``. ``max_iterations=None`` resolves to the+ ``fix_loop_max_attempts`` builder config. ``select_codes`` / ``ignore_codes`` filter which fix+ rules may apply (see ``_safe_fixes``); the CLI validates the codes before calling.+ """+ if max_iterations is None:+ max_iterations = get_config().pipelex.builder_config.fix_loop_max_attempts+ entry_source_path = _absolute_source_path(mthds_file_path)+ entry_path = entry_source_path.resolve()+ effective_dirs, _ = resolve_library_dirs(library_dirs)+ is_single_file = not effective_dirs+ write_scope_dirs = library_dirs if writable_library_dirs is None else writable_library_dirs+ writable_dirs: list[Path] = [Path(writable_dir).resolve() for writable_dir in write_scope_dirs] if write_scope_dirs is not None else []++ seen_fingerprints: set[str] = set()+ fixes_applied: list[SuggestedFix] = []+ files_written: list[str] = []+ written_paths: set[Path] = set()+ apply_rounds = 0+ last_error_items: list[ValidationErrorItem] = []++ for _ in range(max_iterations):+ snapshots_by_source = _snapshot_loaded_sources(entry_source_path=entry_source_path, effective_dirs=effective_dirs)+ try:+ validation_result = await validate_bundle(+ mthds_file_path=mthds_file_path,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ )+ pending_signatures = _pending_signatures_from_validation_result(validation_result)+ return FixBundleResult(+ is_valid=True,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=[],+ pending_signatures=pending_signatures,+ is_runnable=not pending_signatures,+ )+ except ValidateBundleError as exc:+ last_error_items = _validation_error_items(exc)++ safe_fixes = _safe_fixes(last_error_items, is_single_file=is_single_file, select_codes=select_codes, ignore_codes=ignore_codes)+ if not safe_fixes:+ return FixBundleResult(+ is_valid=False,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=last_error_items,+ )++ bound_fixes = _bind_fixes_to_snapshots(+ safe_fixes,+ entry_source_path=entry_source_path,+ snapshots_by_source=snapshots_by_source,+ )+ in_scope_fixes, out_of_scope_paths = _partition_by_write_scope(bound_fixes, entry_path=entry_path, writable_dirs=writable_dirs)+ if not in_scope_fixes:+ out_of_scope_names = ", ".join(sorted({str(out_path) for out_path in out_of_scope_paths}))+ bail_reason = (+ f"fixes target files outside write scope: {out_of_scope_names} — pass their directory with -L/--library-dir to allow writing"+ )+ return FixBundleResult(+ is_valid=False,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=last_error_items,+ bail_reason=bail_reason,+ )++ if not is_single_file:+ codes_by_file = _pipe_codes_by_file(entry_path=entry_path, effective_dirs=effective_dirs)+ in_scope_fixes, colliding_names = _split_cross_file_collisions(in_scope_fixes, codes_by_file=codes_by_file)+ if not in_scope_fixes:+ colliding = ", ".join(f"'{name}'" for name in sorted(set(colliding_names)))+ bail_reason = f"cross-file collision: every remaining fix would write a pipe code ({colliding}) already declared in a sibling bundle"+ return FixBundleResult(+ is_valid=False,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=last_error_items,+ bail_reason=bail_reason,+ )++ new_fixes = [fix for fix in in_scope_fixes if _fix_fingerprint(fix.fix) not in seen_fingerprints]+ if not new_fixes:+ # Author-facing: name the fixes that kept being re-proposed (their descriptions), not the+ # internal fingerprints — a re-proposal that changed nothing means the fix's target could+ # not be applied as written. The remaining errors (with their 💡 lines) print right below.+ repeated_descriptions = ", ".join(sorted({fix.fix.description for fix in in_scope_fixes}))+ bail_reason = (+ f"no progress: the same fix was re-proposed without changing the bundle ({repeated_descriptions}); "+ "its target could not be applied as written — fix the remaining errors manually"+ )+ return FixBundleResult(+ is_valid=False,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=last_error_items,+ bail_reason=bail_reason,+ )++ fixes_by_target: dict[Path, tuple[_FileSnapshot, list[SuggestedFix]]] = {}+ for bound_fix in new_fixes:+ target_group = fixes_by_target.setdefault(bound_fix.target_path, (bound_fix.snapshot, []))+ target_group[1].append(bound_fix.fix)++ pending_updates: list[_PendingFileUpdate] = []+ round_fixes_applied: list[SuggestedFix] = []+ round_written_paths: list[Path] = []+ for target_path, (snapshot, target_fixes) in fixes_by_target.items():+ toml_doc = tomlkit.loads(snapshot.content.decode("utf-8"))+ any_op_applied = False+ for target_fix in target_fixes:+ applications = apply_fix_ops(toml_doc, ops=target_fix.ops)+ if any(application.outcome.did_apply for application in applications):+ round_fixes_applied.append(target_fix)+ any_op_applied = True+ if any_op_applied:+ pending_updates.append(_PendingFileUpdate(snapshot=snapshot, new_content=serialize_and_format(toml_doc)))+ round_written_paths.append(target_path)++ _commit_file_updates(pending_updates)+ seen_fingerprints.update(_fix_fingerprint(fix.fix) for fix in new_fixes)+ fixes_applied.extend(round_fixes_applied)+ for target_path in round_written_paths:+ if target_path not in written_paths:+ written_paths.add(target_path)+ files_written.append(str(target_path))+ apply_rounds += 1++ # max_iterations apply rounds done — the final verdict comes from one last validation.+ try:+ validation_result = await validate_bundle(+ mthds_file_path=mthds_file_path,+ library_dirs=library_dirs,+ allow_signatures=allow_signatures,+ )+ pending_signatures = _pending_signatures_from_validation_result(validation_result)+ return FixBundleResult(+ is_valid=True,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=[],+ pending_signatures=pending_signatures,+ is_runnable=not pending_signatures,+ )+ except ValidateBundleError as exc:+ return FixBundleResult(+ is_valid=False,+ iterations=apply_rounds,+ fixes_applied=fixes_applied,+ files_written=files_written,+ remaining_errors=_validation_error_items(exc),+ bail_reason=f"max_iterations ({max_iterations}) reached without convergence",+ )diff --git a/pipelex/pipeline/fixes/fix_render.py b/pipelex/pipeline/fixes/fix_render.pynew file mode 100644index 000000000..7fa4dcfd5--- /dev/null+++ b/pipelex/pipeline/fixes/fix_render.py@@ -0,0 +1,124 @@+"""Markdown rendering for deterministic bundle-fix results."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++from pipelex.pipeline.validation_render import format_validation_error_items_markdown++if TYPE_CHECKING:+ from pipelex.pipeline.fixes.fix_loop import FixBundleResult+++def _format_fix_file(fix_payload: dict[str, Any], *, bundle_path: str | None) -> str | None:+ source = fix_payload.get("source")+ if not isinstance(source, str):+ return None+ if bundle_path is not None and Path(source).resolve() == Path(bundle_path).resolve():+ return None+ return source+++def format_fix_markdown(result: dict[str, Any]) -> str:+ """Render a successful ``pipelex-agent fix bundle`` result as markdown."""+ fixes = result.get("fixes_applied")+ fix_items = cast("list[Any]", fixes) if isinstance(fixes, list) else []+ is_runnable = result.get("is_runnable")+ if is_runnable is False:+ title = "# Bundle valid but not runnable"+ elif fix_items:+ title = "# Fix applied - bundle is valid"+ else:+ title = "# Bundle already valid"+ lines: list[str] = [title, ""]++ bundle_path = result.get("bundle_path")+ bundle_path_str = bundle_path if isinstance(bundle_path, str) else None+ if bundle_path_str is not None:+ lines.append(f"- **Bundle:** `{bundle_path_str}`")++ iterations = result.get("iterations")+ if isinstance(iterations, int):+ lines.append(f"- **Iterations:** {iterations}")++ pending_signatures = result.get("pending_signatures")+ if isinstance(pending_signatures, list) and pending_signatures:+ lines += [+ "",+ "## Pending Signatures",+ "",+ "This bundle is valid but not runnable until these `PipeSignature` placeholders are implemented:",+ "",+ ]+ for pipe_ref in cast("list[Any]", pending_signatures):+ lines.append(f"- `{pipe_ref}`")++ if fix_items:+ lines += ["", "## Applied Fixes", ""]+ for fix_item in fix_items:+ if not isinstance(fix_item, dict):+ continue+ typed_fix_item = cast("dict[str, Any]", fix_item)+ fix_code = str(typed_fix_item.get("fix_code", "unknown"))+ description = str(typed_fix_item.get("description", ""))+ source = _format_fix_file(typed_fix_item, bundle_path=bundle_path_str)+ suffix = f" (`{source}`)" if source is not None else ""+ lines.append(f"- `{fix_code}` - {description}{suffix}")++ files_written = result.get("files_written")+ if isinstance(files_written, list) and files_written:+ lines += ["", "## Files Written", ""]+ for file_path in cast("list[Any]", files_written):+ lines.append(f"- `{file_path}`")++ return "\n".join(lines)+++def format_fix_still_invalid_markdown(result: FixBundleResult, *, bundle_path: str) -> str:+ """Render a still-invalid ``fix bundle`` result as agent-readable markdown (stderr, exit 1).++ The markdown sibling of the human ``_render_fix_result`` still-invalid arm+ (``cli/commands/fix/_fix_core.py``): a heading, the bundle, the partial progress that WAS+ applied, the bail reason, then the remaining errors rendered as prose items (with their ``💡+ Suggested fix`` lines, via the shared :func:`format_validation_error_items_markdown`) rather+ than a raw JSON dump, and a context-aware tip. This is the step-5-deferred "richer+ still-invalid markdown for the agent command".+ """+ lines: list[str] = ["# Fix incomplete - bundle still invalid", "", f"**Bundle:** `{bundle_path}`"]++ # Partial progress is normal: name what WAS applied before the remaining errors.+ if result.fixes_applied:+ entry_resolved = Path(bundle_path).resolve()+ lines += ["", "## Applied Fixes", ""]+ for fix in result.fixes_applied:+ suffix = f" (`{fix.source}`)" if fix.source is not None and Path(fix.source).resolve() != entry_resolved else ""+ lines.append(f"- `{fix.fix_code}` - {fix.description}{suffix}")+ if result.files_written:+ lines += ["", "## Files Written", ""]+ for file_path in result.files_written:+ lines.append(f"- `{file_path}`")+ lines += ["", f"- **Iterations:** {result.iterations}"]++ if result.bail_reason:+ lines += ["", f"**Stopped:** {result.bail_reason}"]++ if result.remaining_errors:+ lines += ["", format_validation_error_items_markdown(result.remaining_errors)]++ # A remaining error can still carry a 💡 suggested-fix line — dropped by --select/--ignore, left+ # outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix" there would+ # contradict the line just printed, so only say it when nothing fixable remains (mirrors the human tip).+ if any(item.suggested_fix is not None for item in result.remaining_errors):+ lines += [+ "",+ (+ "💡 Some remaining errors above still show a suggested fix that was not applied — they were skipped by "+ "--select/--ignore, fell outside the write scope, or the loop stopped early (see the reason above). "+ "Adjust those flags (or pass -L) and re-run, or fix the rest manually."+ ),+ ]+ else:+ lines += ["", "💡 The remaining errors have no deterministic safe fix — they need a manual edit."]++ return "\n".join(lines)diff --git a/pipelex/pipeline/fixes/planner.py b/pipelex/pipeline/fixes/planner.pynew file mode 100644index 000000000..45b6e1194--- /dev/null+++ b/pipelex/pipeline/fixes/planner.py@@ -0,0 +1,212 @@+"""Fix planner — translates enriched validation error data into ``SuggestedFix`` payloads.++Pure functions keyed strictly on ``error_type`` + structured fields, never message strings.+The planner runs inside report assembly (``build_validation_error_items``), so every consumer+of the validation report — CLI, API, MCP — sees fixes with zero extra plumbing.+"""++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.suggested_fix import FixOp, FixOpKind, FixSafety, SuggestedFix++MATCH_SEQUENCE_OUTPUT_FIX_CODE = "match-sequence-output"+SYNC_CONTROLLER_INPUTS_FIX_CODE = "sync-controller-inputs"+STRIP_NATIVE_CONCEPT_REDECL_FIX_CODE = "strip-native-concept-redecl"+STRIP_NAMESPACE_FIX_CODE = "strip-namespace"++# Every fix-rule code the planner can emit — the validation set for user-facing rule filters+# (``--select`` / ``--ignore``). A new rule constant above must be added here; the CLI rejects+# codes outside this set loudly (a typo'd filter selects *behavior*, so lenient-ignore is wrong).+KNOWN_FIX_CODES: frozenset[str] = frozenset(+ {+ MATCH_SEQUENCE_OUTPUT_FIX_CODE,+ SYNC_CONTROLLER_INPUTS_FIX_CODE,+ STRIP_NATIVE_CONCEPT_REDECL_FIX_CODE,+ STRIP_NAMESPACE_FIX_CODE,+ }+)+++def plan_fix_for_pipe_validation_error(error_data: PipesAndConceptValidationErrorData) -> SuggestedFix | None:+ """Derive a suggested fix from one pipe-validation error data, or ``None`` when not fixable.++ Each rule fires only when its enrichment is present — set only at the raise sites that know+ the correct value — so the same error types raised elsewhere (PipeParallel / PipeCondition /+ operator pipes) carry no enrichment and are suppressed here structurally.+ """+ if error_data.error_type.is_inadequate_output:+ return _plan_match_sequence_output(error_data)+ if error_data.error_type.is_controller_input_drift:+ return _plan_sync_controller_inputs(error_data)+ return None+++def _plan_match_sequence_output(error_data: PipesAndConceptValidationErrorData) -> SuggestedFix | None:+ """``match-sequence-output``: an ``INADEQUATE_OUTPUT_*`` carrying the enriched+ ``expected_output_ref`` becomes a ``set_key`` of the pipe's ``output``.+ """+ if error_data.expected_output_ref is None or error_data.pipe_code is None:+ return None+ return SuggestedFix(+ fix_code=MATCH_SEQUENCE_OUTPUT_FIX_CODE,+ description=f"Set output of pipe '{error_data.pipe_code}' to '{error_data.expected_output_ref}' to match its last step",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=[+ FixOp(+ kind=FixOpKind.SET_KEY,+ table_path=["pipe", error_data.pipe_code],+ key="output",+ value=error_data.expected_output_ref,+ ),+ ],+ )+++def _plan_sync_controller_inputs(error_data: PipesAndConceptValidationErrorData) -> SuggestedFix | None:+ """``sync-controller-inputs``: an input-drift error carrying the enriched ``expected_inputs``+ + ``declared_inputs`` mappings becomes a minimal diff of the pipe's ``inputs`` table —+ ``set_key`` for added/changed variables, ``delete_key`` for extraneous ones. Because the+ mappings are complete, one fix repairs all input drift for the pipe even though validation+ aborts at the first error. With nothing declared, an ``ensure_table`` followed by per-key+ writes creates a missing inline table while preserving an explicitly empty block table and+ any comments attached inside it.+ """+ if error_data.expected_inputs is None or error_data.declared_inputs is None or error_data.pipe_code is None:+ return None++ if not error_data.declared_inputs:+ if not error_data.expected_inputs:+ return None+ variables = ", ".join(f"'{var_name}'" for var_name in error_data.expected_inputs)+ inputs_table_path = ["pipe", error_data.pipe_code, "inputs"]+ create_ops = [FixOp(kind=FixOpKind.ENSURE_TABLE, table_path=inputs_table_path)]+ create_ops.extend(+ FixOp(kind=FixOpKind.SET_KEY, table_path=inputs_table_path, key=var_name, value=expected_ref)+ for var_name, expected_ref in error_data.expected_inputs.items()+ )+ return SuggestedFix(+ fix_code=SYNC_CONTROLLER_INPUTS_FIX_CODE,+ description=f"Declare inputs of pipe '{error_data.pipe_code}' as needed by its steps: {variables}",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=create_ops,+ )++ inputs_table_path = ["pipe", error_data.pipe_code, "inputs"]+ added: list[str] = []+ updated: list[str] = []+ removed: list[str] = []+ ops: list[FixOp] = []+ for var_name, expected_ref in error_data.expected_inputs.items():+ declared_ref = error_data.declared_inputs.get(var_name)+ if declared_ref == expected_ref:+ continue+ (added if declared_ref is None else updated).append(var_name)+ ops.append(FixOp(kind=FixOpKind.SET_KEY, table_path=inputs_table_path, key=var_name, value=expected_ref))+ for var_name in error_data.declared_inputs:+ if var_name not in error_data.expected_inputs:+ removed.append(var_name)+ ops.append(FixOp(kind=FixOpKind.DELETE_KEY, table_path=inputs_table_path, key=var_name))+ if not ops:+ # The renderings already agree (e.g. two concepts that render to the same relative ref):+ # an empty diff would be a no-op fix the loop applies forever — suppress instead.+ return None++ change_parts: list[str] = []+ if added:+ change_parts.append("add " + ", ".join(f"'{var_name}'" for var_name in added))+ if updated:+ change_parts.append("update " + ", ".join(f"'{var_name}'" for var_name in updated))+ if removed:+ change_parts.append("remove " + ", ".join(f"'{var_name}'" for var_name in removed))+ return SuggestedFix(+ fix_code=SYNC_CONTROLLER_INPUTS_FIX_CODE,+ description=f"Sync inputs of pipe '{error_data.pipe_code}' with its steps' needs: {'; '.join(change_parts)}",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=ops,+ )+++def plan_fix_for_blueprint_validation_error(error_data: PipelexBundleBlueprintValidationErrorData) -> SuggestedFix | None:+ """Derive a suggested fix from one blueprint-validation error data, or ``None`` when not fixable.++ The blueprint channel carries an optional ``error_type``; only errors whose enrichment is+ present (set at the raise site that knows the correct value) become fixes, so uncategorized+ residuals and unrelated blueprint errors are suppressed structurally.+ """+ if error_data.error_type is None:+ return None+ if error_data.error_type.is_native_concept_redeclaration:+ return _plan_strip_native_concept_redecl(error_data)+ if error_data.error_type.is_invalid_pipe_code_syntax:+ return _plan_strip_namespace(error_data)+ return None+++def _plan_strip_native_concept_redecl(error_data: PipelexBundleBlueprintValidationErrorData) -> SuggestedFix | None:+ """``strip-native-concept-redecl``: a native-concept redeclaration carrying the enriched+ ``concept_code`` becomes a ``delete_key`` of that key under ``["concept"]`` — the one op that+ covers every authoring form (``[concept.X]`` table, ``X = "…"`` shorthand, dotted+ ``concept.X``) since tomlkit represents them all as a ``concept`` table keyed by the code.+ """+ if error_data.concept_code is None:+ return None+ return SuggestedFix(+ fix_code=STRIP_NATIVE_CONCEPT_REDECL_FIX_CODE,+ description=f"Remove the redeclaration of native concept '{error_data.concept_code}'",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=[+ FixOp(+ kind=FixOpKind.DELETE_KEY,+ table_path=["concept"],+ key=error_data.concept_code,+ ),+ ],+ )+++def _plan_strip_namespace(error_data: PipelexBundleBlueprintValidationErrorData) -> SuggestedFix | None:+ """``strip-namespace``: a same-domain over-qualified pipe code carrying the enriched+ ``stripped_pipe_code`` becomes either a position-preserving ``rename_table_key`` of the+ ``[pipe]`` declaration key (when ``pipe_code`` holds the offending dotted key) or a root+ ``set_key`` of ``main_pipe`` (when it does not — a ``main_pipe`` value is not a table key).++ Only the declaration key and ``main_pipe`` are ever stripped: internal references+ (``steps[].pipe``, ``branches[].pipe``, …) keep resolving because a same-domain *qualified*+ ref resolves to the bare pipe, so they need no rewrite. Un-strippable syntax errors carry no+ ``stripped_pipe_code`` and are suppressed here structurally.+ """+ if error_data.stripped_pipe_code is None:+ return None+ if error_data.pipe_code is not None:+ return SuggestedFix(+ fix_code=STRIP_NAMESPACE_FIX_CODE,+ description=f"Strip the same-domain prefix from pipe '{error_data.pipe_code}' (rename to '{error_data.stripped_pipe_code}')",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=[+ FixOp(+ kind=FixOpKind.RENAME_TABLE_KEY,+ table_path=["pipe"],+ key=error_data.pipe_code,+ new_key=error_data.stripped_pipe_code,+ ),+ ],+ )+ return SuggestedFix(+ fix_code=STRIP_NAMESPACE_FIX_CODE,+ description=f"Strip the same-domain prefix from main_pipe (set to '{error_data.stripped_pipe_code}')",+ safety=FixSafety.SAFE,+ source=error_data.source,+ ops=[+ FixOp(+ kind=FixOpKind.SET_KEY,+ table_path=[],+ key="main_pipe",+ value=error_data.stripped_pipe_code,+ ),+ ],+ )diff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.pyindex b7184bd4a..68d9008f2 100644--- a/pipelex/pipeline/validate_bundle.py+++ b/pipelex/pipeline/validate_bundle.py@@ -91,6 +91,30 @@ def build_pending_signatures(pipes_by_ref: dict[str, PipeAbstract]) -> list[str]return sorted(pipe.pipe_ref for ref_key, pipe in pipes_by_ref.items() if pipe.is_signature and not QualifiedRef.has_cross_package_prefix(ref_key))+def _backfill_pipe_error_source(pipe_error: PipeValidationError) -> None:+ """Backfill ``file_path`` on a pipe-channel error from the library manager's pipe-source map.++ Raise sites (``PipeAbstract`` input checks, ``PipeSequence`` output checks) don't know their+ file — pipes deliberately carry no source; provenance lives in the crate's ``source_map``,+ mirrored into the current library's source map during load, *before* ``validate_library``+ runs. Intercepting once at this catch boundary covers every raise site, present and future.++ Lookup is by the full ``domain.pipe_code`` ref only — never the bare-code suffix fallback+ (bare codes are ambiguous across domains, exactly what the fix loop's cross-file guard+ defends against). A miss leaves ``file_path`` as ``None``: the fix stays source-less and+ falls under the conservative single-file rule, which is the safe direction.+ """+ if pipe_error.file_path is not None:+ return+ if pipe_error.domain_code is None or pipe_error.pipe_code is None:+ return+ source = get_library_manager().get_pipe_source(f"{pipe_error.domain_code}.{pipe_error.pipe_code}")+ if source is not None:+ # Compatibility boundary: injected managers written against the previous protocol may+ # still return ``Path``. Normalize before assigning to the string-only error model.+ pipe_error.file_path = str(source)++@contextmanagerdef _translate_to_validate_bundle_error(category: Literal["pipe", "concept"]) -> Generator[None, None, None]:"""Translate the bundle-loading exception surface into a single ``ValidateBundleError``.@@ -133,6 +157,7 @@ def _translate_to_validate_bundle_error(category: Literal["pipe", "concept"]) -># ``pydantic.ValidationError``) is pinned by# ``tests/unit/pipelex/pipeline/test_validate_bundle_helper.py``.except PipeValidationError as pipe_error:+ _backfill_pipe_error_source(pipe_error)pipe_error_data = categorize_pipe_validation_with_libraries_error(pipe_error=pipe_error)raise ValidateBundleError(message=f"Pipe validation failed: {pipe_error}",diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.pyindex 533bbc321..a8c6b790d 100644--- a/pipelex/pipeline/validation_errors.py+++ b/pipelex/pipeline/validation_errors.py@@ -18,6 +18,7 @@ is no import cycle.from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorDatafrom pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData+from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error, plan_fix_for_pipe_validation_errordef build_validation_error_items(@@ -89,6 +90,7 @@ def build_validation_error_items(source=blueprint_error.source,variable_names=blueprint_error.variable_names or None,message=blueprint_error.message,+ suggested_fix=plan_fix_for_blueprint_validation_error(blueprint_error),))@@ -119,6 +121,7 @@ def build_validation_error_items(field_name=pipe_error.field_name,variable_names=pipe_error.variable_names or None,message=pipe_error.message,+ suggested_fix=plan_fix_for_pipe_validation_error(pipe_error),))diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.pyindex 4efe17253..b1f9c2c0e 100644--- a/pipelex/pipeline/validation_render.py+++ b/pipelex/pipeline/validation_render.py@@ -12,12 +12,27 @@ cannot drift.``render_invalid_validation_markdown`` renders the **invalid-arm** verdict (thestructured ``validation_errors``). Both are shared pipelex code so the local CLIand the API-runner cannot drift in format/structure.++``format_validation_error_items_markdown`` is the markdown sibling of the human+``display_validation_error_items`` (``cli/error_handlers.py``): it renders typed+:class:`ValidationErrorItem`s as category-grouped prose with per-item ``💡+Suggested fix`` lines. It backs the agent ``validate`` failure surface and the+agent ``fix`` still-invalid surface (and, in a later phase, the API+``rendered_markdown``) so the prose an agent reads mirrors the human panel and+cannot drift. ``build_fix_command`` is the shared builder for the copy-pasteable+``<executable> fix bundle <path>`` footer, used by both the human and agent+``validate`` surfaces so the ``-L`` / ``--allow-signatures`` echo cannot drift."""from __future__ import annotations+import shlex+from pathlib import Pathfrom typing import Any, cast+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.hub import resolve_library_dirs+from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scopefrom pipelex.tools.misc.string_utils import count_with_noun@@ -106,13 +121,19 @@ def format_validate_markdown(result: dict[str, Any]) -> str:def render_invalid_validation_markdown(report: dict[str, Any]) -> str:"""Render an invalid validation verdict (the InvalidReport arm) as agent-readable markdown.- Faithfully renders the structured ``validation_errors`` the hosted ``/validate``- InvalidReport carries — the same typed items the agent CLI emits — as a- ``# Validation failed`` heading, the summary ``message``, then a numbered- ``## Errors`` list with each item's ``category`` + ``message`` and any present- locators (pipe / concept / domain / field / source). This is a faithful render- of the structured verdict; it does NOT reproduce the agent CLI's generic- error-envelope byte-for-byte.+ Reconstructs the typed :class:`ValidationErrorItem`s from the report's serialized+ ``validation_errors`` and delegates to the shared+ :func:`format_validation_error_items_markdown` — the *same* prose renderer that backs the+ agent ``validate`` failure surface and the human panel. So the markdown an agent reads+ through the hosted ``/validate`` (the opt-in ``rendered_markdown``) is byte-identical in+ structure to the local CLI prose: category-grouped items with humanized titles, identity+ fields, the message, and per-item ``💡 Suggested fix`` lines (which the old dict-based+ renderer dropped). A ``# Validation failed`` heading frames it.++ ``rendered_markdown`` is presentation, never the contract — the machine consumer branches on+ the JSON ``is_valid`` / ``validation_errors`` fields (see workspace ``CLAUDE.md`` § "Surface+ output conventions"). No CLI-command footer is emitted here: an API consumer applies fixes via+ the structured ``suggested_fix`` ops, not a ``pipelex-agent fix`` invocation.Args:report: The InvalidReport-shaped dict (``is_valid: False``,@@ -121,32 +142,164 @@ def render_invalid_validation_markdown(report: dict[str, Any]) -> str:Returns:A markdown string."""+ raw_items: list[dict[str, Any]] = report.get("validation_errors") or []+ items = [ValidationErrorItem.model_validate(raw_item) for raw_item in raw_items]+lines: list[str] = ["# Validation failed", ""]+ body = format_validation_error_items_markdown(items)+ if body:+ lines.append(body)+ else:+ # Defensive: the structured-info invariant guarantees a non-empty validation_errors[] on+ # every produced invalid verdict, so this branch should be unreachable — but a report that+ # somehow carries no items still shows its summary message rather than a bare heading.+ message = report.get("message")+ if message:+ lines.append(str(message))- message = report.get("message")- if message:- lines += [str(message), ""]-- validation_errors: list[dict[str, Any]] = report.get("validation_errors") or []- lines += [f"## Errors ({len(validation_errors)})", ""]-- # Locators rendered in a stable order, only when present (non-None) — mirrors the- # structured-info invariant: each item carries the locators it can attribute.- locator_labels: list[tuple[str, str]] = [- ("pipe", "pipe_code"),- ("missing pipe", "missing_pipe_code"),- ("concept", "concept_code"),- ("missing concept", "missing_concept_code"),- ("domain", "domain_code"),- ("field", "field_name"),- ("path", "field_path"),- ("source", "source"),- ]- for index, item in enumerate(validation_errors, start=1):- lines.append(f"{index}. **{item.get('category')}** — {item.get('message')}")- for label, key in locator_labels:- value = item.get(key)- if value:- lines.append(f" - {label}: `{value}`")+ return "\n".join(lines).rstrip()- return "\n".join(lines)++def _markdown_category_header(category: ValidationErrorCategory) -> str:+ """The section heading for one validation-error category — markdown sibling of the human header."""+ match category:+ case ValidationErrorCategory.BLUEPRINT_VALIDATION:+ return "Blueprint validation errors"+ case ValidationErrorCategory.PIPE_FACTORY:+ return "Pipe factory errors"+ case ValidationErrorCategory.PIPE_VALIDATION:+ return "Pipe validation errors"+ case ValidationErrorCategory.DRY_RUN:+ return "Dry run error"+++def _render_error_item_markdown(item: ValidationErrorItem, *, index: int) -> list[str]:+ """Render one structured item as prose: humanized title, identity fields, message, fix, locators.++ Markdown sibling of the human ``_display_validation_error_item`` — same fields in the same+ order, emitting ``**bold**`` / backticks instead of Rich markup.+ """+ title = item.error_type.replace("_", " ").title() if item.error_type else "Validation Error"+ lines: list[str] = [f"{index}. **{title}**"]+ if item.pipe_code:+ lines.append(f" - Pipe: `{item.pipe_code}`")+ if item.concept_code:+ lines.append(f" - Concept: `{item.concept_code}`")+ if item.domain_code:+ lines.append(f" - Domain: `{item.domain_code}`")+ if item.field_name:+ lines.append(f" - Field: `{item.field_name}`")+ if item.missing_concept_code:+ lines.append(f" - Missing concept: `{item.missing_concept_code}`")+ if item.missing_pipe_code:+ lines.append(f" - Missing pipe: `{item.missing_pipe_code}`")+ if item.declared_concepts:+ declared = ", ".join(f"`{concept_code}`" for concept_code in item.declared_concepts)+ lines.append(f" - Declared concepts: {declared}")+ if item.variable_names:+ variables = ", ".join(f"`{variable_name}`" for variable_name in item.variable_names)+ lines.append(f" - Variables: {variables}")+ lines.append(f" - {item.message}")+ if item.suggested_fix is not None:+ lines.append(f" - 💡 Suggested fix: {item.suggested_fix.description}")+ if item.field_path:+ lines.append(f" - Path: `{item.field_path}`")+ if item.source:+ lines.append(f" - Source: `{item.source}`")+ return lines+++def format_validation_error_items_markdown(items: list[ValidationErrorItem]) -> str:+ """Render structured validation-error items grouped by category as agent-readable markdown.++ The markdown sibling of the human ``display_validation_error_items``+ (``cli/error_handlers.py``): same category grouping, same per-item identity fields + message+ + ``💡 Suggested fix`` line, emitting markdown instead of Rich markup. Consumes the typed+ items produced by the shared ``build_validation_error_items`` builder — the same source the+ human panel and the structured wire draw from — so the prose an agent reads cannot drift from+ what a human sees. Returns only the grouped items block (no heading, no footer); callers wrap+ it with the surface-specific framing.++ Args:+ items: The structured validation-error items to render, in builder order.++ Returns:+ A markdown string: one ``## <Category>`` section per populated category, each holding+ numbered prose items (the ``dry_run`` residual keeps its plain single-message rendering).+ """+ items_by_category: dict[ValidationErrorCategory, list[ValidationErrorItem]] = {}+ for item in items:+ items_by_category.setdefault(item.category, []).append(item)++ lines: list[str] = []+ for category in ValidationErrorCategory:+ category_items = items_by_category.get(category, [])+ if not category_items:+ continue+ if lines:+ lines.append("")+ lines += [f"## {_markdown_category_header(category)}", ""]+ match category:+ case ValidationErrorCategory.DRY_RUN:+ # The dry-run residual is a single graph-level message with no identity fields —+ # keep its plain rendering rather than a numbered item, mirroring the human surface.+ for item in category_items:+ lines.append(item.message)+ case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:+ for error_index, item in enumerate(category_items, 1):+ lines += _render_error_item_markdown(item, index=error_index)+ lines.append("")++ return "\n".join(lines).rstrip()+++def build_fix_command(executable: str, *, bundle_path: Path, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> str:+ """Build the copy-pasteable ``<executable> fix bundle <path>`` command for a fix-aware footer.++ Shared by the human ``validate`` footer (``executable="pipelex"``) and the agent ``validate``+ footer (``executable="pipelex-agent"``) so the suggested command reproduces the same write+ scope — the ``-L`` library dirs and ``--allow-signatures`` leniency — identically on both+ surfaces. ``shlex.join`` keeps a path with spaces a single argument when the footer is pasted.++ Args:+ executable: The CLI binary name (``pipelex`` or ``pipelex-agent``).+ bundle_path: The bundle file / pipeline directory being validated.+ library_dirs: The ``-L/--library-dir`` values of the invocation, echoed so the fix runs+ with the same library scope.+ allow_signatures: Whether the invocation accepted ``PipeSignature`` placeholders; echoed so+ the fix preserves the same leniency.++ Returns:+ The shell-safe command string.+ """+ command_parts = [executable, "fix", "bundle", str(bundle_path)]+ for library_dir in library_dirs or []:+ command_parts.extend(["-L", str(library_dir)])+ if allow_signatures:+ command_parts.append("--allow-signatures")+ return shlex.join(command_parts)+++def count_applicable_fixes(+ items: list[ValidationErrorItem],+ *,+ bundle_path: Path,+ library_dirs: list[Path] | None,+) -> int:+ """Count safe fixes the displayed command is authorized and able to apply."""+ effective_dirs, _ = resolve_library_dirs(library_dirs)+ is_single_file = not effective_dirs+ entry_path = bundle_path.resolve()+ writable_dirs = [library_dir.resolve() for library_dir in library_dirs] if library_dirs is not None else []+ applicable_count = 0+ for item in items:+ fix = item.suggested_fix+ if fix is None or not is_safe_fix_for_load_scope(fix, is_single_file=is_single_file):+ continue+ if fix.source is None:+ target_path = entry_path+ else:+ target_path = Path(fix.source).resolve()+ if is_target_in_write_scope(target_path, entry_path=entry_path, writable_dirs=writable_dirs):+ applicable_count += 1+ return applicable_countdiff --git a/pipelex/suggested_fix.py b/pipelex/suggested_fix.pynew file mode 100644index 000000000..0b443c10f--- /dev/null+++ b/pipelex/suggested_fix.py@@ -0,0 +1,81 @@+"""Suggested-fix wire models — structured, deterministic fixes attached to validation diagnostics.++Each fixable ``ValidationErrorItem`` carries a ``SuggestedFix``: semantic patch ops addressed+by TOML path, translated by the fix planner from enriched typed errors (never from message+strings). The ops are the machine contract; any rendered diff is presentation.++This module is deliberately low-level (stdlib + pydantic only) so that+``pipelex.base_exceptions`` — where ``ValidationErrorItem`` lives — can import it without+creating an import cycle. Naming is brand-neutral: fixes are a language-level concept.+"""++from enum import StrEnum+from typing import TypeAlias++from pydantic import BaseModel, ConfigDict, Field++# A TOML-representable value for a set_key op: a scalar (output refs, input refs), or a flat+# scalar mapping for fixes that create a whole table at once (written as an inline table —+# e.g. a missing `inputs` mapping). Deeper nesting would come with rules that need it.+TomlScalar: TypeAlias = str | int | float | bool+TomlValue: TypeAlias = TomlScalar | dict[str, TomlScalar]+++class FixOpKind(StrEnum):+ """The semantic patch operations a suggested fix is composed of."""++ SET_KEY = "set_key"+ ENSURE_TABLE = "ensure_table"+ DELETE_KEY = "delete_key"+ DELETE_TABLE = "delete_table"+ RENAME_TABLE_KEY = "rename_table_key"+++class FixSafety(StrEnum):+ """Whether a fix is safe to auto-apply (SAFE) or requires explicit opt-in (UNSAFE)."""++ SAFE = "safe"+ UNSAFE = "unsafe"++ @property+ def is_safe(self) -> bool:+ match self:+ case FixSafety.SAFE:+ return True+ case FixSafety.UNSAFE:+ return False+++class FixOp(BaseModel):+ """One semantic patch op addressed by TOML path.++ ``table_path`` addresses the containing table (e.g. ``["pipe", "my_seq"]``), aligned with+ the ``field_path`` conventions of validation errors. For ``ensure_table`` it addresses the+ table to create when absent. ``key`` / ``value`` are used by ``set_key`` / ``delete_key``;+ ``new_key`` only by ``rename_table_key``.+ """++ model_config = ConfigDict(frozen=True, extra="forbid")++ kind: FixOpKind = Field(strict=False)+ table_path: list[str]+ key: str | None = None+ value: TomlValue | None = None+ new_key: str | None = None+++class SuggestedFix(BaseModel):+ """A deterministic fix for one validation error, ready for a style-preserving applier.++ ``fix_code`` is the kebab-case rule id (e.g. ``"match-sequence-output"``). ``source`` is+ the file the ops target, when known (multi-file libraries) — an applier must only apply+ ops to the file they target.+ """++ model_config = ConfigDict(frozen=True, extra="forbid")++ fix_code: str+ description: str+ safety: FixSafety = Field(strict=False)+ source: str | None = None+ ops: list[FixOp]diff --git a/pyproject.toml b/pyproject.tomlindex 6befb9a4b..aba040e7f 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -36,6 +36,7 @@ dependencies = ["opentelemetry-semantic-conventions","opentelemetry-sdk","pillow>=12.1.1",+ "pipelex-tools-py==0.1.1","polyfactory>=2.21.0","portkey-ai>=2.1.0","posthog>=6.7.0",diff --git a/tests/data/fixes/controller_inputs_block.golden.mthds b/tests/data/fixes/controller_inputs_block.golden.mthdsnew file mode 100644index 000000000..2c13662d4--- /dev/null+++ b/tests/data/fixes/controller_inputs_block.golden.mthds@@ -0,0 +1,26 @@+# Golden fixture for the sync-controller-inputs applier test (block `[pipe.x.inputs]` form).+domain = "inputsfix_golden_block"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted block-form inputs."+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]++# Comment above the inputs block survives.+[pipe.make_summary.inputs]+# Comment inside the block survives.+text = "Text" # wrong concept on purposediff --git a/tests/data/fixes/controller_inputs_block.mthds b/tests/data/fixes/controller_inputs_block.mthdsnew file mode 100644index 000000000..bef6db9db--- /dev/null+++ b/tests/data/fixes/controller_inputs_block.mthds@@ -0,0 +1,27 @@+# Golden fixture for the sync-controller-inputs applier test (block `[pipe.x.inputs]` form).+domain = "inputsfix_golden_block"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted block-form inputs."+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]++# Comment above the inputs block survives.+[pipe.make_summary.inputs]+# Comment inside the block survives.+text = "Number" # wrong concept on purpose+note = "Text" # extraneous on purposediff --git a/tests/data/fixes/controller_inputs_inline.golden.mthds b/tests/data/fixes/controller_inputs_inline.golden.mthdsnew file mode 100644index 000000000..8fd993efd--- /dev/null+++ b/tests/data/fixes/controller_inputs_inline.golden.mthds@@ -0,0 +1,25 @@+# Golden fixture for the sync-controller-inputs applier test (inline `inputs = {...}` form).+# The sequence's inputs table drifts in all three ways at once: a wrong concept to update,+# a needed variable to add, and an extraneous one to remove.+domain = "inputsfix_golden_inline"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text." # inline concept declaration++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text", style = "Text" } # inline table style+output = "Summary"+prompt = "Summarize $text in style $style"++# The sequence below declares drifted inputs on purpose.+[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted inputs."+inputs = { text = "Text", style = "Text" } # drifted on purpose+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]diff --git a/tests/data/fixes/controller_inputs_inline.mthds b/tests/data/fixes/controller_inputs_inline.mthdsnew file mode 100644index 000000000..312d7efb8--- /dev/null+++ b/tests/data/fixes/controller_inputs_inline.mthds@@ -0,0 +1,25 @@+# Golden fixture for the sync-controller-inputs applier test (inline `inputs = {...}` form).+# The sequence's inputs table drifts in all three ways at once: a wrong concept to update,+# a needed variable to add, and an extraneous one to remove.+domain = "inputsfix_golden_inline"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text." # inline concept declaration++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text", style = "Text" } # inline table style+output = "Summary"+prompt = "Summarize $text in style $style"++# The sequence below declares drifted inputs on purpose.+[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted inputs."+inputs = { text = "Number", note = "Text" } # drifted on purpose+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]diff --git a/tests/data/fixes/controller_inputs_missing_table.golden.mthds b/tests/data/fixes/controller_inputs_missing_table.golden.mthdsnew file mode 100644index 000000000..770135cf0--- /dev/null+++ b/tests/data/fixes/controller_inputs_missing_table.golden.mthds@@ -0,0 +1,24 @@+# Golden fixture for the sync-controller-inputs applier test (no inputs declared at all).+# The fix creates the whole `inputs` mapping as one inline table.+domain = "inputsfix_golden_missing"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++# The sequence below forgot to declare its inputs.+[pipe.make_summary]+type = "PipeSequence"+description = "Sequence that declares no inputs."+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+inputs = { text = "Text" }diff --git a/tests/data/fixes/controller_inputs_missing_table.mthds b/tests/data/fixes/controller_inputs_missing_table.mthdsnew file mode 100644index 000000000..73f0f24fa--- /dev/null+++ b/tests/data/fixes/controller_inputs_missing_table.mthds@@ -0,0 +1,23 @@+# Golden fixture for the sync-controller-inputs applier test (no inputs declared at all).+# The fix creates the whole `inputs` mapping as one inline table.+domain = "inputsfix_golden_missing"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++# The sequence below forgot to declare its inputs.+[pipe.make_summary]+type = "PipeSequence"+description = "Sequence that declares no inputs."+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]diff --git a/tests/data/fixes/native_redecl_dotted.golden.mthds b/tests/data/fixes/native_redecl_dotted.golden.mthdsnew file mode 100644index 000000000..5aea8326b--- /dev/null+++ b/tests/data/fixes/native_redecl_dotted.golden.mthds@@ -0,0 +1,12 @@+domain = "nativefix_dotted"+main_pipe = "make_memo"++# A real, non-native concept — must survive the fix untouched.+concept.Memo = "A memo."++[pipe.make_memo]+type = "PipeLLM"+description = "Make a memo."+inputs = { count = "Number" }+output = "Memo"+prompt = "Write a memo with $count items"diff --git a/tests/data/fixes/native_redecl_dotted.mthds b/tests/data/fixes/native_redecl_dotted.mthdsnew file mode 100644index 000000000..cf60cb3fb--- /dev/null+++ b/tests/data/fixes/native_redecl_dotted.mthds@@ -0,0 +1,13 @@+domain = "nativefix_dotted"+main_pipe = "make_memo"++# A real, non-native concept — must survive the fix untouched.+concept.Memo = "A memo."+concept.Number = "Redeclared native Number."++[pipe.make_memo]+type = "PipeLLM"+description = "Make a memo."+inputs = { count = "Number" }+output = "Memo"+prompt = "Write a memo with $count items"diff --git a/tests/data/fixes/native_redecl_inline.golden.mthds b/tests/data/fixes/native_redecl_inline.golden.mthdsnew file mode 100644index 000000000..e540d7e7f--- /dev/null+++ b/tests/data/fixes/native_redecl_inline.golden.mthds@@ -0,0 +1,13 @@+domain = "nativefix_inline"+main_pipe = "make_note"++[concept]+# A real, non-native concept — must survive the fix untouched.+Note = "A short note."++[pipe.make_note]+type = "PipeLLM"+description = "Make a note."+inputs = { topic = "Text" }+output = "Note"+prompt = "Write a note about $topic"diff --git a/tests/data/fixes/native_redecl_inline.mthds b/tests/data/fixes/native_redecl_inline.mthdsnew file mode 100644index 000000000..60b49c838--- /dev/null+++ b/tests/data/fixes/native_redecl_inline.mthds@@ -0,0 +1,14 @@+domain = "nativefix_inline"+main_pipe = "make_note"++[concept]+# A real, non-native concept — must survive the fix untouched.+Note = "A short note."+Text = "Redeclared native Text."++[pipe.make_note]+type = "PipeLLM"+description = "Make a note."+inputs = { topic = "Text" }+output = "Note"+prompt = "Write a note about $topic"diff --git a/tests/data/fixes/native_redecl_table.golden.mthds b/tests/data/fixes/native_redecl_table.golden.mthdsnew file mode 100644index 000000000..d40a1ddc6--- /dev/null+++ b/tests/data/fixes/native_redecl_table.golden.mthds@@ -0,0 +1,13 @@+domain = "nativefix_table"+main_pipe = "make_report"++# A real, non-native concept — must survive the fix untouched.+[concept.Report]+description = "A report."++[pipe.make_report]+type = "PipeLLM"+description = "Make a report."+inputs = { topic = "Text" }+output = "Report"+prompt = "Write a report about $topic"diff --git a/tests/data/fixes/native_redecl_table.mthds b/tests/data/fixes/native_redecl_table.mthdsnew file mode 100644index 000000000..4af2b7b88--- /dev/null+++ b/tests/data/fixes/native_redecl_table.mthds@@ -0,0 +1,19 @@+domain = "nativefix_table"+main_pipe = "make_report"++# A real, non-native concept — must survive the fix untouched.+[concept.Report]+description = "A report."++[concept.Text]+description = "Redeclared native Text."++[concept.Text.structure]+body = { type = "text", description = "The body." }++[pipe.make_report]+type = "PipeLLM"+description = "Make a report."+inputs = { topic = "Text" }+output = "Report"+prompt = "Write a report about $topic"diff --git a/tests/data/fixes/sequence_wrong_output.golden.mthds b/tests/data/fixes/sequence_wrong_output.golden.mthdsnew file mode 100644index 000000000..f870f8ee8--- /dev/null+++ b/tests/data/fixes/sequence_wrong_output.golden.mthds@@ -0,0 +1,27 @@+# Golden fixture for the match-sequence-output applier test.+# Deliberately mixes styles: trailing comments, an inline table, a block table,+# a multi-line string, and non-alphabetical key ordering.+domain = "seqfix_golden" # trailing comment with extra spaces+main_pipe = "list_ideas"++[concept]+Idea = "An idea." # inline concept declaration++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+output = "Idea[]"+inputs = { topic = "Text" } # inline table style, key deliberately after output+prompt = """+Generate ideas about $topic+"""++# The sequence below declares the wrong output on purpose.+[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence."+inputs = { topic = "Text" }+output = "Idea[]" # wrong: the last step yields a list+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]diff --git a/tests/data/fixes/sequence_wrong_output.mthds b/tests/data/fixes/sequence_wrong_output.mthdsnew file mode 100644index 000000000..1534e57b5--- /dev/null+++ b/tests/data/fixes/sequence_wrong_output.mthds@@ -0,0 +1,27 @@+# Golden fixture for the match-sequence-output applier test.+# Deliberately mixes styles: trailing comments, an inline table, a block table,+# a multi-line string, and non-alphabetical key ordering.+domain = "seqfix_golden" # trailing comment with extra spaces+main_pipe = "list_ideas"++[concept]+Idea = "An idea." # inline concept declaration++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+output = "Idea[]"+inputs = { topic = "Text" } # inline table style, key deliberately after output+prompt = """+Generate ideas about $topic+"""++# The sequence below declares the wrong output on purpose.+[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence."+inputs = { topic = "Text" }+output = "Idea" # wrong: the last step yields a list+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]diff --git a/tests/data/fixes/strip_namespace_rename.golden.mthds b/tests/data/fixes/strip_namespace_rename.golden.mthdsnew file mode 100644index 000000000..2fd1a9fe4--- /dev/null+++ b/tests/data/fixes/strip_namespace_rename.golden.mthds@@ -0,0 +1,25 @@+# Fixture for the strip-namespace applier test: a same-domain over-qualified pipe+# declaration key and main_pipe, plus a qualified step reference that must survive untouched.+domain = "namespacefix"+main_pipe = "run_seq"++[pipe.first_pipe]+type = "PipeLLM"+description = "First pipe, untouched."+output = "Text"+prompt = "First"++# This pipe is over-qualified with its own domain prefix.+[pipe.hello]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello" # trailing comment stays on this line++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "namespacefix.hello", result = "greeting" },+]diff --git a/tests/data/fixes/strip_namespace_rename.mthds b/tests/data/fixes/strip_namespace_rename.mthdsnew file mode 100644index 000000000..ed37a83a5--- /dev/null+++ b/tests/data/fixes/strip_namespace_rename.mthds@@ -0,0 +1,25 @@+# Fixture for the strip-namespace applier test: a same-domain over-qualified pipe+# declaration key and main_pipe, plus a qualified step reference that must survive untouched.+domain = "namespacefix"+main_pipe = "namespacefix.run_seq"++[pipe.first_pipe]+type = "PipeLLM"+description = "First pipe, untouched."+output = "Text"+prompt = "First"++# This pipe is over-qualified with its own domain prefix.+[pipe."namespacefix.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello" # trailing comment stays on this line++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "namespacefix.hello", result = "greeting" },+]diff --git a/tests/e2e/agent_cli/test_fix_bundle.py b/tests/e2e/agent_cli/test_fix_bundle.pynew file mode 100644index 000000000..9147c42d7--- /dev/null+++ b/tests/e2e/agent_cli/test_fix_bundle.py@@ -0,0 +1,101 @@+"""E2E tests for ``pipelex-agent fix bundle`` via subprocess."""++from __future__ import annotations++import json+import subprocess # noqa: S404 - invokes the real pipelex-agent binary for E2E coverage+from typing import TYPE_CHECKING++import pytest++from tests.e2e.agent_cli.conftest import PIPELEX_AGENT_BIN, set_gateway_enabled++if TYPE_CHECKING:+ from pathlib import Path++_FIXABLE_SEQUENCE_MTHDS = """domain = "agent_fix_e2e"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_UNFIXABLE_MTHDS = """domain = "agent_fix_e2e_unfixable"+main_pipe = "say_hi"++[pipe.say_hi]+type = "PipeLLM"+description = "References a missing concept."+inputs = { name = "MissingConcept" }+output = "Text"+prompt = "Say hi to $name"+"""+++def _run_fix_bundle(bundle_path: Path, *, env: dict[str, str], cwd: Path) -> subprocess.CompletedProcess[str]:+ return subprocess.run( # noqa: S603+ [+ str(PIPELEX_AGENT_BIN),+ "fix",+ "bundle",+ str(bundle_path),+ "--format",+ "json",+ ],+ env=env,+ cwd=str(cwd),+ capture_output=True,+ text=True,+ check=False,+ timeout=120,+ )++[email protected]_disabled+class TestFixBundleE2E:+ def test_fixable_bundle_outputs_clean_json_and_writes_file(self, hermetic_home: Path, offline_subprocess_env: dict[str, str]) -> None:+ pipelex_dir = hermetic_home / ".pipelex"+ set_gateway_enabled(pipelex_dir / "inference" / "backends.toml", enabled=False)+ bundle_path = hermetic_home / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ result = _run_fix_bundle(bundle_path, env=offline_subprocess_env, cwd=hermetic_home)++ assert result.returncode == 0, f"fix bundle must succeed.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ payload = json.loads(result.stdout)+ assert payload["success"] is True+ assert payload["is_valid"] is True+ assert [fix["fix_code"] for fix in payload["fixes_applied"]] == ["match-sequence-output"]+ assert payload["files_written"] == [str(bundle_path.resolve())]+ assert 'output = "Idea[]"' in bundle_path.read_text(encoding="utf-8")++ def test_unfixable_bundle_outputs_json_error_and_exit_one(self, hermetic_home: Path, offline_subprocess_env: dict[str, str]) -> None:+ pipelex_dir = hermetic_home / ".pipelex"+ set_gateway_enabled(pipelex_dir / "inference" / "backends.toml", enabled=False)+ bundle_path = hermetic_home / "bundle.mthds"+ bundle_path.write_text(_UNFIXABLE_MTHDS, encoding="utf-8")++ result = _run_fix_bundle(bundle_path, env=offline_subprocess_env, cwd=hermetic_home)++ assert result.returncode == 1, f"unfixable bundle must exit 1.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ assert result.stdout == ""+ payload = json.loads(result.stderr)+ assert payload["error_type"] == "FixBundleError"+ assert payload["is_valid"] is False+ assert payload["remaining_errors"]diff --git a/tests/e2e/pipelex/cli/conftest.py b/tests/e2e/pipelex/cli/conftest.pynew file mode 100644index 000000000..c98ad52bc--- /dev/null+++ b/tests/e2e/pipelex/cli/conftest.py@@ -0,0 +1,10 @@+"""Fixtures for human-CLI E2E tests.++Re-exports the hermetic-HOME subprocess harness of the agent-CLI E2E suite so human-CLI+subprocess tests (e.g. ``pipelex fix bundle``) run against the same isolated config tree.+"""++from tests.e2e.agent_cli.conftest import ( # noqa: F401 - fixtures re-exported for this directory+ hermetic_home,+ offline_subprocess_env,+)diff --git a/tests/e2e/pipelex/cli/test_fix_bundle_cmd.py b/tests/e2e/pipelex/cli/test_fix_bundle_cmd.pynew file mode 100644index 000000000..cec1e14f3--- /dev/null+++ b/tests/e2e/pipelex/cli/test_fix_bundle_cmd.py@@ -0,0 +1,108 @@+"""E2E tests for the human ``pipelex fix bundle`` command via subprocess.++Reuses the hermetic-HOME harness of the agent-CLI E2E suite (imported fixtures) and invokes+the real ``.venv/bin/pipelex`` binary, so the whole surface is exercised: Typer registration,+boot, the fix loop, human rendering, and exit codes.+"""++from __future__ import annotations++import subprocess # noqa: S404 - invokes the real pipelex binary for E2E coverage+from typing import TYPE_CHECKING++import pytest++from tests.e2e.agent_cli.conftest import REPO_ROOT, set_gateway_enabled++if TYPE_CHECKING:+ from pathlib import Path++PIPELEX_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex"++_FIXABLE_SEQUENCE_MTHDS = """domain = "human_fix_e2e"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_UNFIXABLE_MTHDS = """domain = "human_fix_e2e_unfixable"+main_pipe = "say_hi"++[pipe.say_hi]+type = "PipeLLM"+description = "References a missing concept."+inputs = { name = "MissingConcept" }+output = "Text"+prompt = "Say hi to $name"+"""+++def _run_fix_bundle(bundle_path: Path, *, env: dict[str, str], cwd: Path) -> subprocess.CompletedProcess[str]:+ return subprocess.run( # noqa: S603+ [+ str(PIPELEX_BIN),+ "--no-logo",+ "fix",+ "bundle",+ str(bundle_path),+ ],+ env=env,+ cwd=str(cwd),+ capture_output=True,+ text=True,+ check=False,+ timeout=120,+ )++[email protected]_disabled+class TestFixBundleHumanE2E:+ def test_fixable_bundle_exits_zero_names_change_and_writes_file(+ self,+ hermetic_home: Path,+ offline_subprocess_env: dict[str, str],+ ) -> None:+ pipelex_dir = hermetic_home / ".pipelex"+ set_gateway_enabled(pipelex_dir / "inference" / "backends.toml", enabled=False)+ bundle_path = hermetic_home / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ result = _run_fix_bundle(bundle_path, env=offline_subprocess_env, cwd=hermetic_home)++ assert result.returncode == 0, f"fix bundle must succeed.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ assert "Bundle fixed" in result.stdout+ assert "match-sequence-output" in result.stdout+ assert 'output = "Idea[]"' in bundle_path.read_text(encoding="utf-8")++ def test_unfixable_bundle_exits_one_with_remaining_errors(+ self,+ hermetic_home: Path,+ offline_subprocess_env: dict[str, str],+ ) -> None:+ pipelex_dir = hermetic_home / ".pipelex"+ set_gateway_enabled(pipelex_dir / "inference" / "backends.toml", enabled=False)+ bundle_path = hermetic_home / "bundle.mthds"+ bundle_path.write_text(_UNFIXABLE_MTHDS, encoding="utf-8")++ result = _run_fix_bundle(bundle_path, env=offline_subprocess_env, cwd=hermetic_home)++ assert result.returncode == 1, f"unfixable bundle must exit 1.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ assert "could not be fully fixed" in result.stdout+ assert "MissingConcept" in result.stdoutdiff --git a/tests/integration/pipelex/cli/test_agent_fix_bundle.py b/tests/integration/pipelex/cli/test_agent_fix_bundle.pynew file mode 100644index 000000000..cdd72cfd0--- /dev/null+++ b/tests/integration/pipelex/cli/test_agent_fix_bundle.py@@ -0,0 +1,174 @@+"""Integration tests for ``pipelex-agent fix bundle`` command logic."""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, cast++import pytest+import tomlkit+import typer++from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat+from pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmd++if TYPE_CHECKING:+ from collections.abc import Callable+ from pathlib import Path+ from typing import Any++ from pytest_mock import MockerFixture++FIX_BUNDLE_MODULE = "pipelex.cli.agent_cli.commands.fix.bundle_cmd"++_FIXABLE_SEQUENCE_MTHDS = """domain = "agent_fix_bundle"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_UNFIXABLE_MTHDS = """domain = "agent_fix_unfixable"+main_pipe = "say_hi"++[pipe.say_hi]+type = "PipeLLM"+description = "References a missing concept."+inputs = { name = "MissingConcept" }+output = "Text"+prompt = "Say hi to $name"+"""++_SIGNATURE_ONLY_MTHDS = """domain = "agent_fix_signature"+main_pipe = "summarize_doc"++[concept]+SigDocument = "A document concept used for testing signatures."++[pipe.summarize_doc]+description = "Produces a summary of a document (contract only)."+inputs = { doc = "SigDocument" }+output = "Text"+"""+++def _pipes(bundle_path: Path) -> dict[str, Any]:+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ return cast("dict[str, Any]", parsed["pipe"])+++def _patch_setup(mocker: MockerFixture) -> None:+ mocker.patch(f"{FIX_BUNDLE_MODULE}.make_pipelex_for_agent_cli")+ mocker.patch(f"{FIX_BUNDLE_MODULE}.Pipelex.teardown_if_needed")+++class TestAgentFixBundle:+ def test_fixable_bundle_exits_zero_and_mutates_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ _patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ payload = json.loads(capsys.readouterr().out)+ assert payload["success"] is True+ assert payload["is_valid"] is True+ assert [fix["fix_code"] for fix in payload["fixes_applied"]] == ["match-sequence-output"]+ assert payload["files_written"] == [str(bundle_path.resolve())]+ assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea[]"++ def test_unfixable_bundle_exits_one_with_structured_error(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ _patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_UNFIXABLE_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ payload = json.loads(capsys.readouterr().err)+ assert payload["error_type"] == "FixBundleError"+ assert payload["is_valid"] is False+ assert payload["fixes_applied"] == []+ assert payload["remaining_errors"]++ def test_signature_only_bundle_exits_one_after_success_payload(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ _patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_SIGNATURE_ONLY_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.err == ""+ payload = json.loads(captured.out)+ assert payload["success"] is True+ assert payload["is_valid"] is True+ assert payload["is_runnable"] is False+ assert payload["pending_signatures"] == ["agent_fix_signature.summarize_doc"]+ assert payload["fixes_applied"] == []+ assert payload["remaining_errors"] == []++ def test_select_filter_is_honored_end_to_end(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ _patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(+ path=str(bundle_path),+ select_codes_raw=["strip-namespace"],+ output_format=CliOutputFormat.JSON,+ )++ assert exc_info.value.exit_code == 1+ payload = json.loads(capsys.readouterr().err)+ assert payload["is_valid"] is False+ assert payload["fixes_applied"] == []+ assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea"diff --git a/tests/integration/pipelex/cli/test_fix_bundle_human.py b/tests/integration/pipelex/cli/test_fix_bundle_human.pynew file mode 100644index 000000000..9cd87377d--- /dev/null+++ b/tests/integration/pipelex/cli/test_fix_bundle_human.py@@ -0,0 +1,358 @@+"""Integration tests for the human ``pipelex fix bundle`` command against the real fix loop.++Mirrors ``test_agent_fix_bundle.py``: the Pipelex boot/teardown/telemetry seams are patched+(the suite's session boot owns the runtime), while ``fix_bundle_file`` runs for real against+``tmp_path`` copies — so these pin the whole command path: resolution, loop, mutation on disk,+human rendering, and exit codes.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, cast++import pytest+import tomlkit+import typer+from rich.console import Console++from pipelex.cli.commands.fix.bundle_cmd import fix_bundle_cmd++if TYPE_CHECKING:+ from collections.abc import Callable+ from pathlib import Path+ from typing import Any++ from pytest_mock import MockerFixture++FIX_CORE_MODULE = "pipelex.cli.commands.fix._fix_core"++_FIXABLE_SEQUENCE_MTHDS = """domain = "human_fix_bundle"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_CASCADE_SEQUENCE_MTHDS = """domain = "human_fix_cascade"+main_pipe = "outer"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.inner]+type = "PipeSequence"+description = "Inner sequence with the wrong output."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]++[pipe.outer]+type = "PipeSequence"+description = "Outer sequence matching the inner's wrong declared output."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "inner", result = "ideas" },+]+"""++_UNFIXABLE_MTHDS = """domain = "human_fix_unfixable"+main_pipe = "say_hi"++[pipe.say_hi]+type = "PipeLLM"+description = "References a missing concept."+inputs = { name = "MissingConcept" }+output = "Text"+prompt = "Say hi to $name"+"""+++def _pipes(bundle_path: Path) -> dict[str, Any]:+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ return cast("dict[str, Any]", parsed["pipe"])+++class TestFixBundleHuman:+ @pytest.fixture+ def console(self, mocker: MockerFixture) -> Console:+ """Recorded plain-text console patched into the fix core module."""+ recorded_console = Console(width=500, record=True, color_system=None)+ mocker.patch(f"{FIX_CORE_MODULE}.get_console", return_value=recorded_console)+ return recorded_console++ def _patch_setup(self, mocker: MockerFixture) -> None:+ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")++ def test_fixable_bundle_exits_zero_mutates_file_and_names_the_change(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ fix_bundle_cmd(path=str(bundle_path))++ output = console.export_text()+ assert "✅ Bundle fixed — valid" in output+ assert "match-sequence-output" in output+ assert "Set output of pipe 'list_ideas' to 'Idea[]'" in output+ assert "Files written:" in output+ assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea[]"++ def test_unfixable_bundle_exits_one_with_remaining_errors(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_UNFIXABLE_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "❌ Bundle could not be fully fixed" in output+ assert "MissingConcept" in output++ def test_select_filter_is_honored_end_to_end(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), select_codes_raw=["strip-namespace"])++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "❌ Bundle could not be fully fixed" in output+ assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea"++ def test_diff_preview_leaves_originals_untouched_and_prints_diff(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()++ fix_bundle_cmd(path=str(bundle_path), diff=True)++ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert "Preview (--diff): no files were written." in output+ assert f"--- {bundle_path.resolve()}" in output+ assert '+output = "Idea[]"' in output+ assert '-output = "Idea"' in output+ assert "✅ Fix preview — these fixes would make the bundle valid" in output++ def test_diff_preview_uses_ambient_entry_copy_without_duplicate_identity(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ """An entry discoverable through ambient scope is loaded once from its sandbox copy."""+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()+ mocker.patch(+ "pipelex.cli.commands.fix._diff_sandbox.resolve_library_dirs",+ return_value=([tmp_path], "PIPELEXPATH"),+ )++ fix_bundle_cmd(path=str(bundle_path), diff=True)++ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert "✅ Fix preview — these fixes would make the bundle valid" in output+ assert "outside write scope" not in output++ def test_diff_preview_deduplicates_equivalent_explicit_library_dirs(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Equivalent ``-L`` aliases do not invent duplicate declarations in the sandbox."""+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ fix_bundle_cmd(+ path=str(bundle_path),+ library_dir=[str(tmp_path), str(tmp_path / ".")],+ diff=True,+ )++ output = console.export_text()+ assert "✅ Fix preview — these fixes would make the bundle valid" in output+ assert "already declared" not in output++ def test_diff_preview_on_unfixable_bundle_exits_one_originals_untouched(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_UNFIXABLE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), diff=True)++ assert exc_info.value.exit_code == 1+ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert "❌ Fix preview — the bundle would still be invalid" in output++ def test_diff_preview_still_invalid_exits_one_without_writing(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Partial previews name original files in both diagnostic path fields after the sandbox is removed."""+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_CASCADE_SEQUENCE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), max_iterations=1, diff=True)++ assert exc_info.value.exit_code == 1+ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert "❌ Fix preview — the bundle would still be invalid" in output+ assert "Fixes that would be applied:" in output+ assert f"Path: {bundle_path.resolve()}" in output+ assert f"Source: {bundle_path.resolve()}" in output+ assert "pipelex-fix-preview-" not in output++ def test_diff_preview_directory_mode_maps_paths_to_originals(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Directory mode mirrors the dir; diffs and labels must name the ORIGINAL files, untouched."""+ load_empty_library()+ self._patch_setup(mocker)+ bundle_dir = tmp_path / "pipeline_01"+ bundle_dir.mkdir()+ bundle_path = bundle_dir / "only_one.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()++ fix_bundle_cmd(path=str(bundle_dir), diff=True)++ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert f"--- {bundle_path.resolve()}" in output+ assert "pipelex-fix-preview-" not in output++ def test_diff_preview_tolerates_missing_library_dir_like_the_real_run(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A non-existent -L dir must not crash --diff or mislabel it as a missing bundle: the real run skips it, so the preview must too."""+ load_empty_library()+ self._patch_setup(mocker)+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")+ original_bytes = bundle_path.read_bytes()+ missing_dir = tmp_path / "typo_dir"++ fix_bundle_cmd(path=str(bundle_path), library_dir=[str(missing_dir)], diff=True)++ assert bundle_path.read_bytes() == original_bytes+ output = console.export_text()+ assert "✅ Fix preview — these fixes would make the bundle valid" in output+ assert "bundle file not found" not in output+ assert "Failed to fix" not in output++ def test_directory_mode_auto_detects_and_fixes(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ self._patch_setup(mocker)+ bundle_dir = tmp_path / "pipeline_01"+ bundle_dir.mkdir()+ bundle_path = bundle_dir / "only_one.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ fix_bundle_cmd(path=str(bundle_dir))++ output = console.export_text()+ assert "✅ Bundle fixed — valid" in output+ assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea[]"diff --git a/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py b/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.pynew file mode 100644index 000000000..bb15bffbe--- /dev/null+++ b/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py@@ -0,0 +1,77 @@+"""Integration pin: human ``pipelex validate bundle`` surfaces the 💡 suggested-fix line.++Runs the real validation path (only the boot/teardown/telemetry seams are patched — the+suite's session boot owns the runtime) on a fixable bundle, and asserts the rendered output+carries the per-error ``💡 Suggested fix:`` line plus the actionable ``pipelex fix bundle``+footer, wired end-to-end through the shared items builder.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+import typer+from rich.console import Console++from pipelex.cli.commands.validate.bundle_cmd import validate_bundle_cmd++if TYPE_CHECKING:+ from collections.abc import Callable+ from pathlib import Path++ from pytest_mock import MockerFixture++VALIDATE_CORE_MODULE = "pipelex.cli.commands.validate._validate_core"++_FIXABLE_SEQUENCE_MTHDS = """domain = "human_validate_fixable"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""+++class TestValidateSuggestedFixIntegration:+ def test_fixable_bundle_renders_suggested_fix_and_actionable_footer(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ load_empty_library: Callable[[], str],+ ) -> None:+ load_empty_library()+ mocker.patch(f"{VALIDATE_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{VALIDATE_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{VALIDATE_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{VALIDATE_CORE_MODULE}.tag")+ recorded_console = Console(width=500, record=True, color_system=None)+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)++ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ validate_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 1+ output = recorded_console.export_text()+ assert "❌ Bundle validation failed" in output+ assert "💡 Suggested fix: Set output of pipe 'list_ideas' to 'Idea[]' to match its last step" in output+ assert "can be fixed automatically" in output+ assert f"pipelex fix bundle {bundle_path}" in outputdiff --git a/tests/integration/pipelex/libraries/test_load_from_crate.py b/tests/integration/pipelex/libraries/test_load_from_crate.pyindex 0b9116ed3..3017beaf6 100644--- a/tests/integration/pipelex/libraries/test_load_from_crate.py+++ b/tests/integration/pipelex/libraries/test_load_from_crate.py@@ -3,7 +3,7 @@ from collections.abc import Callablefrom pathlib import Pathfrom pipelex.core.interpreter.interpreter import PipelexInterpreter-from pipelex.hub import get_library_manager+from pipelex.hub import clear_current_library, get_library_manager, set_current_libraryfrom pipelex.libraries.library_crate_factory import LibraryCrateFactorySCORING_MTHDS = """\@@ -105,3 +105,28 @@ class TestLoadFromCrate:crate = LibraryCrateFactory.make_from_blueprints(blueprints=blueprints)assert "scoring" in crate.domainsassert crate.domains["scoring"].main_pipe == "compute_score"++ def test_pipe_source_is_scoped_to_current_library(self, tmp_path: Path) -> None:+ """Same pipe refs loaded concurrently must retain each library's own source path."""+ first_path = tmp_path / "first.mthds"+ second_path = tmp_path / "second.mthds"+ first_path.write_text(SCORING_MTHDS, encoding="utf-8")+ second_path.write_text(SCORING_MTHDS, encoding="utf-8")+ first_blueprint = PipelexInterpreter.make_pipelex_bundle_blueprint(bundle_path=first_path)+ second_blueprint = PipelexInterpreter.make_pipelex_bundle_blueprint(bundle_path=second_path)+ library_manager = get_library_manager()+ first_library_id, _ = library_manager.open_library()+ second_library_id, _ = library_manager.open_library()++ try:+ library_manager.load_from_blueprints(library_id=first_library_id, blueprints=[first_blueprint])+ library_manager.load_from_blueprints(library_id=second_library_id, blueprints=[second_blueprint])++ set_current_library(library_id=first_library_id)+ assert library_manager.get_pipe_source("scoring.compute_score") == str(first_path)+ set_current_library(library_id=second_library_id)+ assert library_manager.get_pipe_source("scoring.compute_score") == str(second_path)+ finally:+ clear_current_library()+ library_manager.teardown(library_id=first_library_id)+ library_manager.teardown(library_id=second_library_id)diff --git a/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py b/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.pynew file mode 100644index 000000000..c9e6b8990--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py@@ -0,0 +1,456 @@+"""Pin: controller input-drift errors carry the full expected inputs mapping (autofix enrichment).++A controller's ``needed_inputs()`` is the ground truth its declared ``inputs`` table must+match, and the validator has it in hand at detection time. These tests pin that+``MISSING_INPUT_VARIABLE`` / ``EXTRANEOUS_INPUT_VARIABLE`` / ``INPUT_STUFF_SPEC_MISMATCH``+raised on a **controller** carry the full ``expected_inputs`` mapping (variable name →+bundle-representation ref, the exact strings a fix would write) on the categorized error+data — while operator-raised variants of the same error types carry ``None`` and stay+structurally unfixable. This enriched fact is what the fix planner translates into a+``sync-controller-inputs`` suggested fix.+"""++from collections.abc import Callable++import pytest++from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validate_bundle import validate_bundle++_MISSING_INPUT_MTHDS = """+domain = "inputsfix_missing"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence not declaring the input its step needs."+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_EXTRANEOUS_INPUT_MTHDS = """+domain = "inputsfix_extra"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence declaring an input no step needs."+inputs = { text = "Text", note = "Text" }+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_CONCEPT_MISMATCH_MTHDS = """+domain = "inputsfix_concept"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence declaring the wrong concept for its step's input."+inputs = { text = "Number" }+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_MULTIPLICITY_MISMATCH_MTHDS = """+domain = "inputsfix_mult"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence declaring a list where its step needs a single item."+inputs = { text = "Text[]" }+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_FLEXIBLE_NEED_PRESERVED_MTHDS = """+domain = "inputsfix_flex"+main_pipe = "make_summary"++[pipe.summarize]+type = "PipeLLM"+description = "Needs a flexible input plus a concrete one."+inputs = { data = "Anything", other = "Text" }+output = "Text"+prompt = "Use $data and $other"++[pipe.make_summary]+type = "PipeSequence"+description = "Narrows the flexible need to a concrete concept while drifting the other input."+inputs = { data = "Text", other = "Number" }+output = "Text"+steps = [+ { pipe = "summarize", result = "summary" },+]+"""++_OPTIONAL_MARKER_MTHDS = """+domain = "inputsfix_optional"+main_pipe = "check_doc"++[concept]+Verdict = "A verdict."++[pipe.check]+type = "PipeLLM"+description = "Check the doc."+inputs = { doc = "Text" }+output = "Verdict"+prompt = "Check $doc"++[pipe.check_doc]+type = "PipeSequence"+description = "Sequence with a lift-skip optional input plus an extraneous one."+inputs = { doc = "Text?", note = "Text" }+output = "Verdict?"+steps = [+ { pipe = "check", result = "verdict" },+]+"""++_CROSS_DOMAIN_CONCEPTS_MTHDS = """+domain = "docsdom"+main_pipe = "read_doc"++[concept]+Doc = "A document."++[pipe.read_doc]+type = "PipeLLM"+description = "Read the doc."+inputs = { doc = "Doc" }+output = "Text"+prompt = "Read $doc"+"""++_CROSS_DOMAIN_FLOW_MTHDS = """+domain = "flowdom"+main_pipe = "make_flow"++[pipe.summarize]+type = "PipeLLM"+description = "Summarize a cross-domain doc."+inputs = { doc = "docsdom.Doc" }+output = "Text"+prompt = "Summarize $doc"++[pipe.make_flow]+type = "PipeSequence"+description = "Sequence not declaring the cross-domain input its step needs."+output = "Text"+steps = [+ { pipe = "summarize", result = "summary" },+]+"""++_OPERATOR_MISSING_MTHDS = """+domain = "inputsfix_op_missing"+main_pipe = "write"++[pipe.write]+type = "PipeLLM"+description = "Prompt references a variable that is not declared."+output = "Text"+prompt = "Summarize $text"+"""++_OPERATOR_EXTRANEOUS_MTHDS = """+domain = "inputsfix_op_extra"+main_pipe = "write"++[pipe.write]+type = "PipeLLM"+description = "Declares an input the prompt never uses."+inputs = { text = "Text", note = "Text" }+output = "Text"+prompt = "Summarize $text"+"""++_OPERATOR_STRUCTURE_MISMATCH_MTHDS = """+domain = "inputsfix_op_struct"+main_pipe = "extract_record"++[concept.Record]+description = "A record."++[concept.Record.structure]+title = { type = "text", description = "Title" }++[pipe.extract_record]+type = "PipeStructure"+description = "Structure from an image input (invalid: not Text-compatible)."+inputs = { img = "Image" }+output = "Record"+"""++_CONDITION_EXPRESSION_VAR_MTHDS = """+domain = "inputsfix_cond"+main_pipe = "gate"++[concept]+Verdict = "A verdict."++[pipe.check]+type = "PipeLLM"+description = "Check the doc."+inputs = { doc = "Text" }+output = "Verdict"+prompt = "Check $doc"++[pipe.gate]+type = "PipeCondition"+description = "Gate whose expression variable is not declared in inputs."+inputs = { doc = "Text" }+output = "Verdict?"+expression = "mode"+default_outcome = "continue"++[pipe.gate.outcomes]+go = "check"+"""++_UNRESOLVED_DEP_MTHDS = """+domain = "inputsfix_unresolved"+main_pipe = "make_flow"++[pipe.make_flow]+type = "PipeSequence"+description = "Sequence referencing a pipe that does not exist."+inputs = { text = "Text" }+output = "Text"+steps = [+ { pipe = "nonexistent_pipe", result = "out" },+]+"""+++async def _error_data_for(+ mthds_contents: list[str],+ *,+ error_type: PipeValidationErrorType,+) -> PipesAndConceptValidationErrorData:+ """Validate invalid bundles and return the first pipe-validation error data of the given type."""+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=mthds_contents)+ matching = [error_data for error_data in exc_info.value.pipe_validation_error_data if error_data.error_type == error_type]+ assert matching, f"Expected a {error_type} error, got {[(e.error_type, e.pipe_code) for e in exc_info.value.pipe_validation_error_data]}"+ return matching[0]++[email protected](loop_scope="class")+class TestControllerInputsEnrichment:+ async def test_missing_input_carries_expected_inputs(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A controller missing a needed input carries the full expected mapping."""+ load_empty_library()+ error_data = await _error_data_for([_MISSING_INPUT_MTHDS], error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_inputs == {"text": "Text"}++ async def test_extraneous_input_carries_expected_inputs(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A controller declaring an unneeded input carries the mapping without it."""+ load_empty_library()+ error_data = await _error_data_for([_EXTRANEOUS_INPUT_MTHDS], error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_inputs == {"text": "Text"}++ async def test_concept_mismatch_carries_expected_inputs(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A concept mismatch on a controller input carries the needed concept's ref."""+ load_empty_library()+ error_data = await _error_data_for([_CONCEPT_MISMATCH_MTHDS], error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_inputs == {"text": "Text"}+ # The message speaks author syntax (Number vs Text) and names the fix — never the Python repr+ # of the Concept/StuffSpec objects (`Concept(...)`, `presence=<PresenceMarker...>`).+ assert (+ error_data.message+ == "In pipe 'make_summary', input 'text' is declared as 'Number' but its step needs 'Text'. Update the input to 'Text'."+ )+ assert "Concept(" not in error_data.message+ assert "presence=" not in error_data.message++ async def test_multiplicity_mismatch_carries_expected_inputs(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A multiplicity mismatch on a controller input carries the needed single-item ref."""+ load_empty_library()+ error_data = await _error_data_for([_MULTIPLICITY_MISMATCH_MTHDS], error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_inputs == {"text": "Text"}++ async def test_flexible_need_preserves_declared_concrete_input(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A concrete input narrowing a flexible (Anything/Dynamic) need is preserved, not widened.++ The validator accepts a concrete declaration against a flexible need (its concept/multiplicity+ check is skipped for Dynamic/Anything), so the fix renderer must mirror that carve-out: when a+ co-occurring drift on another input raises the enriched error, the narrowed concrete input must+ survive in ``expected_inputs`` instead of being rewritten back to the flexible ``Anything``.+ """+ load_empty_library()+ error_data = await _error_data_for([_FLEXIBLE_NEED_PRESERVED_MTHDS], error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_inputs == {"data": "Text", "other": "Text"}++ async def test_declared_optional_marker_preserved_in_expected_inputs(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A declared input matching the needed spec keeps the author's `?` marker in the mapping."""+ load_empty_library()+ error_data = await _error_data_for([_OPTIONAL_MARKER_MTHDS], error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE)+ assert error_data.pipe_code == "check_doc"+ assert error_data.expected_inputs == {"doc": "Text?"}++ async def test_cross_domain_needed_input_is_qualified(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A needed input whose concept lives in another domain renders as a qualified ref."""+ load_empty_library()+ error_data = await _error_data_for(+ [_CROSS_DOMAIN_CONCEPTS_MTHDS, _CROSS_DOMAIN_FLOW_MTHDS],+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ )+ assert error_data.pipe_code == "make_flow"+ assert error_data.expected_inputs == {"doc": "docsdom.Doc"}++ async def test_operator_missing_prompt_variable_not_enriched(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A PipeLLM missing a prompt variable stays on the blueprint channel, unenriched.++ The operator's static validation raises at blueprint stage, so the error is a+ blueprint-channel lookalike carrying no ``expected_inputs`` — the input-fix planner+ never sees it (it only hooks the pipe-validation channel).+ """+ load_empty_library()+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[_OPERATOR_MISSING_MTHDS])+ assert not exc_info.value.pipe_validation_error_data+ blueprint_error_types = [error_data.error_type for error_data in exc_info.value.pipelex_bundle_blueprint_validation_errors]+ assert PipeValidationErrorType.MISSING_INPUT_VARIABLE in blueprint_error_types++ async def test_operator_extraneous_input_not_enriched(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A PipeLLM declaring an unused input stays on the blueprint channel, unenriched."""+ load_empty_library()+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[_OPERATOR_EXTRANEOUS_MTHDS])+ assert not exc_info.value.pipe_validation_error_data+ blueprint_error_types = [error_data.error_type for error_data in exc_info.value.pipelex_bundle_blueprint_validation_errors]+ assert PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE in blueprint_error_types++ async def test_operator_structure_mismatch_not_enriched(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A PipeStructure input mismatch carries no expected mapping (unfixable)."""+ load_empty_library()+ error_data = await _error_data_for([_OPERATOR_STRUCTURE_MISMATCH_MTHDS], error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH)+ assert error_data.pipe_code == "extract_record"+ assert error_data.expected_inputs is None++ async def test_condition_expression_variable_not_enriched(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A controller's missing *expression* variable is unknowable — no expected mapping.++ The required-variables check fires before ``needed_inputs()`` is computed, and for a+ PipeCondition the needed spec of an expression variable comes from the declared inputs+ themselves — there is nothing trustworthy to derive a fix from.+ """+ load_empty_library()+ error_data = await _error_data_for([_CONDITION_EXPRESSION_VAR_MTHDS], error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE)+ assert error_data.pipe_code == "gate"+ assert error_data.expected_inputs is None++ async def test_unresolved_dependency_precludes_input_errors(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """An unresolved step dependency surfaces alone — input-drift errors cannot co-occur.++ Library validation resolves every controller dependency (raising immediately on+ failure) before any pipe's ``validate_with_libraries`` runs, so ``needed_inputs()``+ is trustworthy wherever the input checks fire — the prerequisite-clean guard is+ satisfied by validation ordering, not by planner-side scanning.+ """+ load_empty_library()+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[_UNRESOLVED_DEP_MTHDS])+ error_types = [error_data.error_type for error_data in exc_info.value.pipe_validation_error_data]+ assert PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY in error_types+ input_error_types = {+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH,+ }+ assert not input_error_types.intersection(error_types)+ assert all(error_data.expected_inputs is None for error_data in exc_info.value.pipe_validation_error_data)diff --git a/tests/integration/pipelex/pipeline/test_fix_convergence_loop.py b/tests/integration/pipelex/pipeline/test_fix_convergence_loop.pynew file mode 100644index 000000000..468971a2f--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_fix_convergence_loop.py@@ -0,0 +1,893 @@+"""Integration tests for the fix convergence loop — validate → apply SAFE fixes → re-validate.++The loop reuses ``validate_bundle`` wholesale (no parallel validation pipeline). Cascades are+expected: fixing an inner sequence's output can surface the outer sequence's mismatch on the+next iteration — the loop is the design, not a fallback.+"""++from collections.abc import Callable+from pathlib import Path+from typing import Any, cast++import pytest+import tomlkit+from pytest_mock import MockerFixture++from pipelex.pipeline.exceptions import FixWriteConflictError, ValidateBundleError+from pipelex.pipeline.fixes import fix_loop+from pipelex.pipeline.fixes.fix_loop import fix_bundle_file+++def _pipes(bundle_path: Path) -> dict[str, Any]:+ """The fixed file's ``[pipe]`` table as plain data — asserting on parsed values, not raw+ whitespace, since the fix loop rewrites the whole file to canonical MTHDS (the formatter+ column-aligns single-line tables, so a hardcoded ``output = "x"`` spacing is not stable).+ """+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ return cast("dict[str, Any]", parsed["pipe"])+++_SINGLE_PASS_MTHDS = """domain = "seqfix_loop_single"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++# Wrong on purpose: the sequence declares a single Idea while the last step yields a list.+[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_OPTIONAL_BOUNDARY_MTHDS = """domain = "seqfix_loop_presence"+main_pipe = "make_summary"++[concept]+Summary = "A summary."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Lift over optional input while declaring the wrong output concept."+inputs = { text = "Text?" }+output = "Number?"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_CASCADE_MTHDS = """domain = "seqfix_loop_cascade"+main_pipe = "outer"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++# Both sequences are wrong on purpose. The outer's declared output matches the inner's+# declared (wrong) output, so only the inner error surfaces on the first validation;+# fixing the inner surfaces the outer mismatch on the second iteration.+[pipe.inner]+type = "PipeSequence"+description = "Inner sequence with the wrong output."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]++[pipe.outer]+type = "PipeSequence"+description = "Outer sequence matching the inner's wrong declared output."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "inner", result = "ideas" },+]+"""+++_INPUTS_DRIFT_MTHDS = """domain = "inputsfix_loop"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text", style = "Text" }+output = "Summary"+prompt = "Summarize $text in style $style"++# Drifted on purpose: wrong concept for text, extraneous note, missing style.+[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted inputs."+inputs = { text = "Number", note = "Text" }+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_NATIVE_REDECL_MULTI_MTHDS = """domain = "nativefix_converge"+main_pipe = "greet"++[concept]+Greeting = "A greeting message."+# Both redeclare native concepts (illegal). The mode="before" validator raises on the first+# offending code per pass, so they converge one strip per iteration.+Text = "Redeclared native Text."+Number = "Redeclared native Number."++[pipe.greet]+type = "PipeLLM"+description = "Greet someone a number of times."+inputs = { name = "Text", count = "Number" }+output = "Greeting"+prompt = "Greet $name $count times"+"""++_STRIP_NAMESPACE_MTHDS = """domain = "nsfix_loop"+main_pipe = "nsfix_loop.run_seq"++# Over-qualified declaration key with the bundle's own domain (invalid); the qualified step ref+# below stays put (it still resolves to the bare pipe), so only the declaration and main_pipe strip.+[pipe."nsfix_loop.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "nsfix_loop.hello", result = "greeting" },+]+"""++# Cross-file collision pair: the target's dotted declaration would strip to a bare code already+# declared by a sibling bundle — the rename must not be applied. Same domain it would be a+# duplicate declaration; another domain it would be a bare-code ambiguity+# (``PipeLibrary.get_optional_pipe`` raises on a bare code declared by two domains). Either way+# the loop could never repair the state it would write.+_XFILE_TARGET_MTHDS = """domain = "nsfix_xfile"++[pipe."nsfix_xfile.hola"]+type = "PipeLLM"+description = "Say hola."+output = "Text"+prompt = "Say hola"+"""++_XFILE_SIBLING_SAME_DOMAIN_MTHDS = """domain = "nsfix_xfile"++[pipe.hola]+type = "PipeLLM"+description = "Bare hola, declared in a sibling bundle of the same domain."+output = "Text"+prompt = "Say hola"+"""++_XFILE_SIBLING_OTHER_DOMAIN_MTHDS = """domain = "nsfix_xfile_other"++[pipe.hola]+type = "PipeLLM"+description = "Bare hola in another domain."+output = "Text"+prompt = "Say hola"+"""++_XFILE_SIGNATURE_TARGET_MTHDS = """domain = "nsfix_xsig"++[pipe."nsfix_xsig.hello"]+type = "PipeLLM"+description = "Concrete hello whose same-domain prefix should be stripped."+inputs = { name = "Text" }+output = "Text"+prompt = "Say hello to $name"+"""++_XFILE_SIGNATURE_SIBLING_MTHDS = """domain = "nsfix_xsig"++[pipe.hello]+description = "Forward-declared hello signature."+inputs = { name = "Text" }+output = "Text"+"""++# Typo'd main_pipe tail: dotted, same-domain, valid snake tail — but NEITHER the dotted code nor+# the bare tail exists as a declaration key. The categorizer suppresses the enrichment, so the+# loop must apply nothing and leave the file byte-identical (checkpoint-C item 1, categorizer half).+_MAIN_PIPE_TYPO_TAIL_MTHDS = """domain = "nsfix_typo_loop"+main_pipe = "nsfix_typo_loop.helo"++[pipe.hello]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++# Convergent dotted-declaration main_pipe: the declaration's own rename materializes the bare+# target, so the paired main_pipe strip is safe and both land in one round.+_MAIN_PIPE_DOTTED_DECL_MTHDS = """domain = "nsfix_conv_loop"+main_pipe = "nsfix_conv_loop.hello"++[pipe."nsfix_conv_loop.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++# Two-file main_pipe orphan hazard (checkpoint-C item 1, fix-loop half — the PR #1031 cubic P2+# gap): the target's dotted declaration strips to a bare code declared by a SAME-DOMAIN sibling.+# The declaration rename is dropped as cross-file colliding — and the paired root ``main_pipe``+# set_key must be dropped WITH it, else iteration 1 writes an orphaned ``main_pipe = "hello"``+# to a file that never declares ``hello``.+_XFILE_MAIN_PIPE_TARGET_MTHDS = """domain = "nsfix_xmain"+main_pipe = "nsfix_xmain.hello"++[pipe."nsfix_xmain.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++_XFILE_MAIN_PIPE_SIBLING_MTHDS = """domain = "nsfix_xmain"++[pipe.hello]+type = "PipeLLM"+description = "Bare hello, declared in a sibling bundle of the same domain."+output = "Text"+prompt = "Say hello"+"""++_LOCAL_MAIN_PIPE_WITH_SIBLING_SAME_CODE_MTHDS = """domain = "nsfix_localmain"+main_pipe = "nsfix_localmain.hello"++[pipe.hello]+type = "PipeLLM"+description = "Local bare hello, already declared in this bundle."+output = "Text"+prompt = "Say hello"+"""++_LOCAL_MAIN_PIPE_SIBLING_SAME_CODE_MTHDS = """domain = "nsfix_localmain_other"++[pipe.hello]+type = "PipeLLM"+description = "Same bare code in another domain; should not block local main_pipe strip."+output = "Text"+prompt = "Say hello"+"""++# A sibling declaring an unrelated pipe code: must NOT block the rename (no over-dropping).+_XFILE_SIBLING_UNRELATED_MTHDS = """domain = "nsfix_xfile_other"++[pipe.adios]+type = "PipeLLM"+description = "Unrelated sibling pipe."+output = "Text"+prompt = "Say adios"+"""++# Multi-file cascade pair: the entry and a sibling library file EACH carry their own sequence+# output mismatch. Validation aborts at the first error per pass, so the loop must fix the+# sibling in the sibling file, re-validate, then fix the entry in the entry file.+_MULTI_FILE_ENTRY_MTHDS = """domain = "multifix_entry"+main_pipe = "entry_seq"++[concept]+Idea = "An idea."++[pipe.entry_gen]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++# Wrong on purpose: single output declared, last step yields a list.+[pipe.entry_seq]+type = "PipeSequence"+description = "Entry sequence with the wrong output."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "entry_gen", result = "ideas" },+]+"""++_MULTI_FILE_SIBLING_MTHDS = """domain = "multifix_sibling"++[concept]+Notion = "A notion."++[pipe.sibling_gen]+type = "PipeLLM"+description = "Generate notions."+inputs = { topic = "Text" }+output = "Notion[]"+prompt = "Generate notions about $topic"++# Wrong on purpose: single output declared, last step yields a list.+[pipe.sibling_seq]+type = "PipeSequence"+description = "Sibling sequence with the wrong output."+inputs = { topic = "Text" }+output = "Notion"+steps = [+ { pipe = "sibling_gen", result = "notions" },+]+"""++# Corruption-scenario pair: the SAME pipe code declared by two domains across two files. The+# entry's `list_ideas` is valid; the sibling's `list_ideas` is broken. The fix must patch the+# declaring sibling — never the entry file's same-named table (the spike-era corruption bug).+_SAME_CODE_ENTRY_MTHDS = """domain = "corruptfix_entry"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.list_ideas]+type = "PipeLLM"+description = "A VALID pipe whose code collides with a broken same-named pipe in another domain."+inputs = { topic = "Text" }+output = "Idea"+prompt = "Write one idea about $topic"+"""++_SAME_CODE_SIBLING_MTHDS = """domain = "corruptfix_sibling"++[concept]+Notion = "A notion."++[pipe.gen_notions]+type = "PipeLLM"+description = "Generate notions."+inputs = { topic = "Text" }+output = "Notion[]"+prompt = "Generate notions about $topic"++# Wrong on purpose: single output declared, last step yields a list — and the pipe code+# collides with the entry file's valid pipe.+[pipe.list_ideas]+type = "PipeSequence"+description = "Broken sibling sequence sharing the entry pipe's code."+inputs = { topic = "Text" }+output = "Notion"+steps = [+ { pipe = "gen_notions", result = "notions" },+]+"""++_CROSS_RULE_CASCADE_MTHDS = """domain = "crossfix_loop"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++# Both wrong on purpose: the sequence misses its needed input AND declares the wrong+# output. Inputs are validated before outputs, so the input error masks the output error+# until the first fix lands — a natural cross-rule cascade on one pipe.+[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence with drifted inputs and the wrong output."+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++[email protected](loop_scope="class")+class TestFixConvergenceLoop:+ async def test_single_iteration_fixes_and_revalidates(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """One apply round fixes the sequence output; the re-validation verdict is valid."""+ load_empty_library()+ bundle_path = tmp_path / "single.mthds"+ bundle_path.write_text(_SINGLE_PASS_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert result.remaining_errors == []+ assert result.bail_reason is None+ assert 'output = "Idea[]"' in bundle_path.read_text(encoding="utf-8")++ async def test_optional_sequence_boundary_converges_in_one_iteration(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A concept fix preserves taint-derived sequence optionality and fully converges."""+ load_empty_library()+ bundle_path = tmp_path / "optional_boundary.mthds"+ bundle_path.write_text(_OPTIONAL_BOUNDARY_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[])++ assert result.is_valid is True+ assert result.is_runnable is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert result.remaining_errors == []+ assert result.bail_reason is None+ assert _pipes(bundle_path)["make_summary"]["output"] == "Summary?"++ async def test_concurrent_edit_during_render_is_not_overwritten(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ mocker: MockerFixture,+ ) -> None:+ load_empty_library()+ bundle_path = tmp_path / "concurrent.mthds"+ bundle_path.write_text(_SINGLE_PASS_MTHDS, encoding="utf-8")+ user_edit = f"{_SINGLE_PASS_MTHDS}\n# concurrent user edit\n"+ original_serialize = fix_loop.serialize_and_format++ def serialize_after_user_edit(toml_doc: tomlkit.TOMLDocument) -> str:+ rendered = original_serialize(toml_doc)+ bundle_path.write_text(user_edit, encoding="utf-8")+ return rendered++ mocker.patch.object(fix_loop, "serialize_and_format", side_effect=serialize_after_user_edit)++ with pytest.raises(FixWriteConflictError, match="file changed"):+ await fix_bundle_file(bundle_path)++ assert bundle_path.read_text(encoding="utf-8") == user_edit++ async def test_edit_during_validation_is_not_overwritten(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ mocker: MockerFixture,+ ) -> None:+ """A fix derived from pre-edit validation cannot be applied to post-edit bytes."""+ load_empty_library()+ bundle_path = tmp_path / "validation_race.mthds"+ bundle_path.write_text(_SINGLE_PASS_MTHDS, encoding="utf-8")+ user_edit = f"{_SINGLE_PASS_MTHDS}\n# edit saved during validation\n"+ original_validate = fix_loop.validate_bundle+ injected = False++ async def validate_then_edit(**kwargs: Any) -> Any:+ nonlocal injected+ try:+ return await original_validate(**kwargs)+ except ValidateBundleError:+ if not injected:+ injected = True+ bundle_path.write_text(user_edit, encoding="utf-8")+ raise++ mocker.patch.object(fix_loop, "validate_bundle", new=validate_then_edit)++ with pytest.raises(FixWriteConflictError, match="file changed"):+ await fix_bundle_file(bundle_path)++ assert bundle_path.read_text(encoding="utf-8") == user_edit++ async def test_cascade_needs_two_iterations(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Fixing the inner sequence surfaces the outer mismatch; two apply rounds converge."""+ load_empty_library()+ bundle_path = tmp_path / "cascade.mthds"+ bundle_path.write_text(_CASCADE_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 2+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output", "match-sequence-output"]+ assert result.bail_reason is None+ # Both sequences now declare the list output the last step yields.+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve()]+ pipes = _pipes(bundle_path)+ assert pipes["inner"]["output"] == "Idea[]"+ assert pipes["outer"]["output"] == "Idea[]"++ async def test_controller_inputs_drift_fixed_in_one_iteration(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """One sync-controller-inputs fix repairs add + update + delete drift in one round."""+ load_empty_library()+ bundle_path = tmp_path / "inputs_drift.mthds"+ bundle_path.write_text(_INPUTS_DRIFT_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["sync-controller-inputs"]+ assert result.remaining_errors == []+ assert result.bail_reason is None+ make_summary = _pipes(bundle_path)["make_summary"]+ assert make_summary["inputs"] == {"text": "Text", "style": "Text"}+ assert "note" not in make_summary["inputs"]++ async def test_cross_rule_cascade_inputs_then_output(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """The input error masks the output error; two rounds apply the two different rules."""+ load_empty_library()+ bundle_path = tmp_path / "cross_rule.mthds"+ bundle_path.write_text(_CROSS_RULE_CASCADE_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 2+ assert [fix.fix_code for fix in result.fixes_applied] == ["sync-controller-inputs", "match-sequence-output"]+ assert result.bail_reason is None+ list_ideas = _pipes(bundle_path)["list_ideas"]+ assert list_ideas["inputs"] == {"topic": "Text"}+ assert list_ideas["output"] == "Idea[]"++ async def test_native_redeclarations_converge_error_by_error(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A bundle redeclaring two native concepts strips one per iteration until valid.++ The ``mode="before"`` concept validator raises on the first offending code, so the+ blueprint-channel ``strip-native-concept-redecl`` fix converges error-by-error — the same+ cascade shape as the pipe channel, now proven on the blueprint channel end-to-end.+ """+ load_empty_library()+ bundle_path = tmp_path / "native_redecl.mthds"+ bundle_path.write_text(_NATIVE_REDECL_MULTI_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 2+ assert [fix.fix_code for fix in result.fixes_applied] == [+ "strip-native-concept-redecl",+ "strip-native-concept-redecl",+ ]+ assert result.bail_reason is None+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ concept = cast("dict[str, Any]", parsed["concept"])+ assert "Text" not in concept+ assert "Number" not in concept+ # The real, non-native concept survives untouched.+ assert concept["Greeting"] == "A greeting message."++ async def test_strip_namespace_converges_leaving_qualified_refs(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A same-domain over-qualified declaration key and main_pipe are stripped in one iteration.++ Both syntax errors surface in the same validation pass (independent field validators), so+ the rename and the main_pipe set_key apply together. The qualified ``steps[].pipe`` reference+ is intentionally left in place — a same-domain qualified ref resolves to the bare pipe, so no+ reference rewrite is needed for validity (the array-of-tables addressing gap never opens).+ """+ load_empty_library()+ bundle_path = tmp_path / "strip_ns.mthds"+ bundle_path.write_text(_STRIP_NAMESPACE_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace", "strip-namespace"]+ assert result.bail_reason is None+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ pipes = cast("dict[str, Any]", parsed["pipe"])+ assert "hello" in pipes+ assert "nsfix_loop.hello" not in pipes+ assert parsed["main_pipe"] == "run_seq"+ # The qualified step reference survives untouched (it resolves to the renamed bare pipe).+ assert pipes["run_seq"]["steps"][0]["pipe"] == "nsfix_loop.hello"++ @pytest.mark.parametrize(+ "sibling_mthds",+ [_XFILE_SIBLING_SAME_DOMAIN_MTHDS, _XFILE_SIBLING_OTHER_DOMAIN_MTHDS],+ )+ async def test_strip_namespace_bails_on_cross_file_collision(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ sibling_mthds: str,+ ) -> None:+ """A rename whose bare code is declared by ANY sibling bundle is never applied.++ The raise-site collision gate only sees the target file, so the loop's cross-file guard+ must drop the fix — same domain (duplicate declaration) and other domain (bare-code+ ambiguity) alike. The loop bails loudly with the collision reason and the target file's+ bytes are untouched — no unrepairable state is ever written.+ """+ load_empty_library()+ bundle_path = tmp_path / "target.mthds"+ bundle_path.write_text(_XFILE_TARGET_MTHDS, encoding="utf-8")+ (tmp_path / "sibling.mthds").write_text(sibling_mthds, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[tmp_path])++ assert result.is_valid is False+ assert result.fixes_applied == []+ assert result.bail_reason is not None+ assert "cross-file collision" in result.bail_reason+ assert "'hola'" in result.bail_reason+ assert result.remaining_errors+ assert bundle_path.read_text(encoding="utf-8") == _XFILE_TARGET_MTHDS++ async def test_typoed_main_pipe_tail_is_never_stripped(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A dotted ``main_pipe`` whose tail matches no declaration gets NO fix: file untouched.++ Stripping would rewrite ``main_pipe`` to a nonexistent pipe — a SAFE-labeled fix mutating+ the file while leaving the bundle invalid with a different error. The categorizer's+ document-level gate suppresses the enrichment, so the loop has nothing to apply.+ """+ load_empty_library()+ bundle_path = tmp_path / "typo_tail.mthds"+ bundle_path.write_text(_MAIN_PIPE_TYPO_TAIL_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is False+ assert result.fixes_applied == []+ assert result.files_written == []+ assert bundle_path.read_text(encoding="utf-8") == _MAIN_PIPE_TYPO_TAIL_MTHDS++ async def test_dotted_declaration_main_pipe_still_converges(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """``main_pipe`` naming a dotted-only declaration converges: the rename materializes the+ bare target and the paired ``main_pipe`` strip applies in the same round.+ """+ load_empty_library()+ bundle_path = tmp_path / "dotted_conv.mthds"+ bundle_path.write_text(_MAIN_PIPE_DOTTED_DECL_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace", "strip-namespace"]+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ pipes = cast("dict[str, Any]", parsed["pipe"])+ assert "hello" in pipes+ assert "nsfix_conv_loop.hello" not in pipes+ assert parsed["main_pipe"] == "hello"++ async def test_main_pipe_set_key_dropped_with_its_blocked_rename(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """When the declaration rename is dropped as cross-file colliding, the paired root+ ``main_pipe`` set_key is dropped WITH it — never an orphaned ``main_pipe`` write.++ The categorizer cannot see cross-file state (its second disjunct is satisfied here: the+ dotted declaration exists), so this suppression must live in the loop's collision split.+ """+ load_empty_library()+ bundle_path = tmp_path / "target.mthds"+ bundle_path.write_text(_XFILE_MAIN_PIPE_TARGET_MTHDS, encoding="utf-8")+ (tmp_path / "sibling.mthds").write_text(_XFILE_MAIN_PIPE_SIBLING_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[tmp_path])++ assert result.is_valid is False+ assert result.fixes_applied == []+ assert result.files_written == []+ assert result.bail_reason is not None+ assert "cross-file collision" in result.bail_reason+ assert "'hello'" in result.bail_reason+ # No orphaned main_pipe was ever written: the target is byte-identical.+ assert bundle_path.read_text(encoding="utf-8") == _XFILE_MAIN_PIPE_TARGET_MTHDS++ async def test_main_pipe_strip_kept_when_target_already_declares_bare_code(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A sibling's same bare code must not block stripping ``main_pipe`` when the target file+ already declares that bare pipe locally.++ The orphan guard exists for the dotted-declaration case where a blocked rename would leave+ ``main_pipe`` pointing to a pipe the target never declares. Here ``hello`` is already local,+ so dropping the root ``main_pipe`` set_key would be an over-conservative no-fix.+ """+ load_empty_library()+ bundle_path = tmp_path / "target.mthds"+ bundle_path.write_text(_LOCAL_MAIN_PIPE_WITH_SIBLING_SAME_CODE_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ (libs_dir / "sibling.mthds").write_text(_LOCAL_MAIN_PIPE_SIBLING_SAME_CODE_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir])++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace"]+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve()]+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert parsed["main_pipe"] == "hello"+ assert "hello" in parsed["pipe"]++ async def test_strip_namespace_proceeds_past_unrelated_sibling(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A sibling declaring only unrelated pipe codes does not block the rename (no over-dropping)."""+ load_empty_library()+ bundle_path = tmp_path / "target.mthds"+ bundle_path.write_text(_XFILE_TARGET_MTHDS, encoding="utf-8")+ (tmp_path / "sibling.mthds").write_text(_XFILE_SIBLING_UNRELATED_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[tmp_path])++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace"]+ assert result.bail_reason is None+ pipes = _pipes(bundle_path)+ assert "hola" in pipes+ assert "nsfix_xfile.hola" not in pipes++ async def test_strip_namespace_proceeds_past_sibling_signature_header(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A sibling ``PipeSignature`` header is not a hard collision.++ Additive multi-file loading allows a concrete definition to replace a matching signature.+ The cross-file guard must therefore ignore typeless contract-only sections when deciding+ whether a stripped concrete declaration would collide with a sibling file.+ """+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_SINGLE_PASS_MTHDS.replace('output = "Idea"\n', 'output = "Idea[]"\n'), encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ concrete_path = libs_dir / "concrete.mthds"+ concrete_path.write_text(_XFILE_SIGNATURE_TARGET_MTHDS, encoding="utf-8")+ (libs_dir / "signature.mthds").write_text(_XFILE_SIGNATURE_SIBLING_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir])++ assert result.is_valid is True+ assert result.bail_reason is None+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace"]+ assert [Path(written) for written in result.files_written] == [concrete_path.resolve()]+ parsed = tomlkit.loads(concrete_path.read_text(encoding="utf-8")).unwrap()+ pipes = cast("dict[str, Any]", parsed["pipe"])+ assert "hello" in pipes+ assert "nsfix_xsig.hello" not in pipes++ async def test_multi_file_cascade_fixes_each_declaring_file(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Errors declared in the sibling and the entry are each fixed IN their declaring file.++ The sibling's error surfaces first (library dirs load before the entry file), so the loop+ must patch the sibling file, re-validate, then patch the entry — a cross-file cascade.+ Both files are written and reported in ``files_written``.+ """+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MULTI_FILE_ENTRY_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_MULTI_FILE_SIBLING_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir])++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output", "match-sequence-output"]+ assert result.bail_reason is None+ assert [Path(written) for written in result.files_written] == [sibling_path.resolve(), bundle_path.resolve()]+ assert _pipes(bundle_path)["entry_seq"]["output"] == "Idea[]"+ assert _pipes(sibling_path)["sibling_seq"]["output"] == "Notion[]"++ async def test_same_pipe_code_across_domains_patches_the_declaring_file_only(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """REGRESSION (spike corruption scenario): the same pipe code in two domains across two+ files — the fix patches the sibling that declares the broken pipe, never the entry file's+ same-named, perfectly valid table.+ """+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_SAME_CODE_ENTRY_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_SAME_CODE_SIBLING_MTHDS, encoding="utf-8")++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir])++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert [Path(written) for written in result.files_written] == [sibling_path.resolve()]+ # The sibling's broken sequence now matches its last step; the entry file is untouched.+ assert _pipes(sibling_path)["list_ideas"]["output"] == "Notion[]"+ assert bundle_path.read_text(encoding="utf-8") == _SAME_CODE_ENTRY_MTHDS++ async def test_already_valid_bundle_is_a_no_op(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A valid bundle needs no apply round: zero iterations, zero fixes, bytes untouched."""+ load_empty_library()+ bundle_path = tmp_path / "valid.mthds"+ valid_text = _SINGLE_PASS_MTHDS.replace('output = "Idea"\n', 'output = "Idea[]"\n')+ bundle_path.write_text(valid_text, encoding="utf-8")++ result = await fix_bundle_file(bundle_path)++ assert result.is_valid is True+ assert result.iterations == 0+ assert result.fixes_applied == []+ assert bundle_path.read_text(encoding="utf-8") == valid_textdiff --git a/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py b/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.pynew file mode 100644index 000000000..93cc304e0--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py@@ -0,0 +1,165 @@+"""Pin: a native-concept redeclaration carries structured error data (autofix enrichment).++Declaring a concept whose code collides with a native Pipelex concept (`Text`, `Number`, …) is+illegal. The ``validate_concept_keys`` before-validator knows the offending code at detection+time; these tests pin that the blueprint error data carries a dedicated+``NATIVE_CONCEPT_REDECLARATION`` ``error_type`` and the offending ``concept_code`` as a structured+field — across every authoring form (table, table + structure sub-table, string shorthand, dotted)+— instead of leaving the code buried in the message text. This enriched fact is what the fix+planner translates into a ``strip-native-concept-redecl`` suggested fix.+"""++from collections.abc import Callable++import pytest++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validate_bundle import validate_bundle++_REDECL_TABLE_MTHDS = """+domain = "nativefix_table"+main_pipe = "make_report"++[concept.Report]+description = "A report."++# Illegal: redeclares the native Text concept as a table.+[concept.Text]+description = "Redeclared native Text."++[pipe.make_report]+type = "PipeLLM"+description = "Make a report."+inputs = { topic = "Text" }+output = "Report"+prompt = "Write a report about $topic"+"""++_REDECL_TABLE_STRUCTURE_MTHDS = """+domain = "nativefix_struct"+main_pipe = "make_report"++[concept.Report]+description = "A report."++# Illegal: redeclares the native Text concept, with a structure sub-table.+[concept.Text]+description = "Redeclared native Text."++[concept.Text.structure]+body = { type = "text", description = "The body." }++[pipe.make_report]+type = "PipeLLM"+description = "Make a report."+inputs = { topic = "Text" }+output = "Report"+prompt = "Write a report about $topic"+"""++_REDECL_STRING_SHORTHAND_MTHDS = """+domain = "nativefix_inline"+main_pipe = "make_note"++[concept]+Note = "A short note."+# Illegal: redeclares the native Text concept as a string shorthand.+Text = "Redeclared native Text."++[pipe.make_note]+type = "PipeLLM"+description = "Make a note."+inputs = { topic = "Text" }+output = "Note"+prompt = "Write a note about $topic"+"""++_REDECL_DOTTED_MTHDS = """+domain = "nativefix_dotted"+main_pipe = "make_memo"++concept.Memo = "A memo."+# Illegal: redeclares the native Number concept via a dotted key.+concept.Number = "Redeclared native Number."++[pipe.make_memo]+type = "PipeLLM"+description = "Make a memo."+inputs = { count = "Number" }+output = "Memo"+prompt = "Write a memo with $count items"+"""+++async def _redeclaration_error(mthds_content: str) -> PipelexBundleBlueprintValidationErrorData:+ """Validate a redeclaration bundle and return the first native-redeclaration blueprint error."""+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[mthds_content])+ matching = [+ error_data+ for error_data in exc_info.value.pipelex_bundle_blueprint_validation_errors+ if error_data.error_type == PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ ]+ assert matching, (+ f"Expected a NATIVE_CONCEPT_REDECLARATION error, got "+ f"{[(e.error_type, e.concept_code) for e in exc_info.value.pipelex_bundle_blueprint_validation_errors]}"+ )+ return matching[0]++[email protected](loop_scope="class")+class TestNativeConceptRedeclEnrichment:+ @pytest.mark.parametrize(+ ("mthds_content", "expected_concept_code"),+ [+ (_REDECL_TABLE_MTHDS, "Text"),+ (_REDECL_TABLE_STRUCTURE_MTHDS, "Text"),+ (_REDECL_STRING_SHORTHAND_MTHDS, "Text"),+ (_REDECL_DOTTED_MTHDS, "Number"),+ ],+ )+ async def test_redeclaration_carries_concept_code(+ self,+ load_empty_library: Callable[[], str],+ mthds_content: str,+ expected_concept_code: str,+ ) -> None:+ """Every authoring form of a native-concept redeclaration carries the offending code."""+ load_empty_library()+ error_data = await _redeclaration_error(mthds_content)+ assert error_data.concept_code == expected_concept_code++ async def test_invalid_concept_code_is_not_a_redeclaration(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A syntactically invalid concept code is a different failure — not a native redeclaration.++ Only the native-collision raise site is typed; the invalid-syntax branch stays a bare+ ``ValueError`` (uncategorized), so it must never masquerade as a fixable redeclaration.+ """+ load_empty_library()+ invalid_code_mthds = """+domain = "nativefix_invalid"+main_pipe = "noop"++[concept]+"not a valid code" = "Bad concept code."++[pipe.noop]+type = "PipeLLM"+description = "Noop."+inputs = { topic = "Text" }+output = "Text"+prompt = "Do nothing with $topic"+"""+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[invalid_code_mthds])+ redeclaration_errors = [+ error_data+ for error_data in exc_info.value.pipelex_bundle_blueprint_validation_errors+ if error_data.error_type == PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION+ ]+ assert not redeclaration_errorsdiff --git a/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py b/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.pynew file mode 100644index 000000000..93f9027d9--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py@@ -0,0 +1,271 @@+"""Pin: PipeSequence output-mismatch errors carry the expected output ref (autofix enrichment).++The validator already knows the correct sequence output at detection time — the last+step's effective output. These tests pin that ``INADEQUATE_OUTPUT_CONCEPT`` /+``INADEQUATE_OUTPUT_MULTIPLICITY`` raised by ``PipeSequence.validate_output_with_library``+carry it as ``expected_output_ref`` on the categorized error data, in full bundle+representation: concept (bare code when same-domain or native, qualified otherwise) ++multiplicity (honoring the sub-pipe ``output_multiplicity`` override) + presence marker.+This enriched fact is what the fix planner translates into a ``match-sequence-output``+suggested fix.+"""++from collections.abc import Callable++import pytest++from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validate_bundle import validate_bundle++_WRONG_CONCEPT_MTHDS = """+domain = "seqfix_concept"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence declaring an incompatible output concept (Number vs the last step's Summary)."+inputs = { text = "Text" }+output = "Number"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_WRONG_MULTIPLICITY_MTHDS = """+domain = "seqfix_mult"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++_OVERRIDE_MULTIPLICITY_MTHDS = """+domain = "seqfix_override"+main_pipe = "pick_three"++[concept]+Idea = "An idea."++[pipe.gen_idea]+type = "PipeLLM"+description = "Generate one idea."+inputs = { topic = "Text" }+output = "Idea"+prompt = "One idea about $topic"++[pipe.pick_three]+type = "PipeSequence"+description = "Sequence whose last step carries an output_multiplicity override."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_idea", result = "ideas", nb_output = 3 },+]+"""++_OPTIONAL_MARKER_MTHDS = """+domain = "seqfix_optional"+main_pipe = "gated_check"++[concept]+Verdict = "A verdict."++[pipe.check]+type = "PipeLLM"+description = "Check the doc."+inputs = { doc = "Text" }+output = "Verdict"+prompt = "Check $doc"++[pipe.gate]+type = "PipeCondition"+description = "Gate that may continue with no output."+inputs = { doc = "Text" }+output = "Verdict?"+expression = "doc"+default_outcome = "continue"++[pipe.gate.outcomes]+go = "check"++[pipe.gated_check]+type = "PipeSequence"+description = "Sequence declaring the wrong concept while the last step's output is optional."+inputs = { doc = "Text" }+output = "Number"+steps = [+ { pipe = "gate", result = "verdict" },+]+"""++_TAINTED_OPTIONAL_BOUNDARY_MTHDS = """+domain = "seqfix_tainted_boundary"+main_pipe = "make_summary"++[concept]+Summary = "A summary."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize text."+inputs = { text = "Text" }+output = "Summary"+prompt = "Summarize $text"++[pipe.make_summary]+type = "PipeSequence"+description = "Lift over optional input while declaring the wrong output concept."+inputs = { text = "Text?" }+output = "Number?"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_PLURAL_OUTPUT_WITH_OPTIONAL_DECLARATION_MTHDS = """+domain = "seqfix_plural_presence"+main_pipe = "make_ideas"++[concept]+Idea = "An idea."++[pipe.write_idea]+type = "PipeLLM"+description = "Write one idea."+inputs = { topic = "Text" }+output = "Idea"+prompt = "Write one idea about $topic"++[pipe.make_ideas]+type = "PipeSequence"+description = "Declare an optional wrong concept while the last step produces a list."+inputs = { topic = "Text" }+output = "Number?"+steps = [+ { pipe = "write_idea", result = "ideas", nb_output = 3 },+]+"""+++async def _enriched_error_data_for(+ mthds_content: str,+ *,+ error_type: PipeValidationErrorType,+) -> PipesAndConceptValidationErrorData:+ """Validate one invalid bundle and return its single enriched pipe-validation error data."""+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[mthds_content])+ matching = [error_data for error_data in exc_info.value.pipe_validation_error_data if error_data.error_type == error_type]+ assert matching, f"Expected a {error_type} error, got {[(e.error_type, e.pipe_code) for e in exc_info.value.pipe_validation_error_data]}"+ return matching[0]++[email protected](loop_scope="class")+class TestSequenceOutputEnrichment:+ async def test_wrong_concept_carries_expected_output_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A concept mismatch carries the last step's output as the expected ref, bare same-domain code."""+ load_empty_library()+ error_data = await _enriched_error_data_for(_WRONG_CONCEPT_MTHDS, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT)+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_output_ref == "Summary"++ async def test_wrong_multiplicity_carries_expected_output_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A multiplicity mismatch carries the last step's output ref including its `[]` suffix."""+ load_empty_library()+ error_data = await _enriched_error_data_for(_WRONG_MULTIPLICITY_MTHDS, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert error_data.pipe_code == "list_ideas"+ assert error_data.expected_output_ref == "Idea[]"++ async def test_sub_pipe_multiplicity_override_wins_in_expected_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """The sub-pipe's ``nb_output`` override defines the effective expected multiplicity (`[3]`)."""+ load_empty_library()+ error_data = await _enriched_error_data_for(_OVERRIDE_MULTIPLICITY_MTHDS, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert error_data.pipe_code == "pick_three"+ assert error_data.expected_output_ref == "Idea[3]"++ async def test_optional_marker_rides_expected_output_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A last step with an optional (`?`) output keeps its presence marker in the expected ref."""+ load_empty_library()+ error_data = await _enriched_error_data_for(_OPTIONAL_MARKER_MTHDS, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT)+ assert error_data.pipe_code == "gated_check"+ assert error_data.expected_output_ref == "Verdict?"++ async def test_sequence_taint_preserves_optional_boundary_in_expected_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A lifted singular last step keeps the sequence boundary's valid optional marker."""+ load_empty_library()+ error_data = await _enriched_error_data_for(+ _TAINTED_OPTIONAL_BOUNDARY_MTHDS,+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ )+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_output_ref == "Summary?"++ async def test_sequence_taint_adds_optional_boundary_to_plain_expected_ref(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """Taint makes the singular expected ref optional even when the wrong declaration is plain."""+ load_empty_library()+ mthds_content = _TAINTED_OPTIONAL_BOUNDARY_MTHDS.replace('output = "Number?"', 'output = "Number"')+ error_data = await _enriched_error_data_for(+ mthds_content,+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ )+ assert error_data.pipe_code == "make_summary"+ assert error_data.expected_output_ref == "Summary?"++ async def test_plural_expected_output_drops_optional_presence_marker(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A multiplicity override never combines the plural expected ref with `?`."""+ load_empty_library()+ error_data = await _enriched_error_data_for(+ _PLURAL_OUTPUT_WITH_OPTIONAL_DECLARATION_MTHDS,+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ )+ assert error_data.pipe_code == "make_ideas"+ assert error_data.expected_output_ref == "Idea[3]"diff --git a/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py b/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.pynew file mode 100644index 000000000..cc4b2c12d--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py@@ -0,0 +1,239 @@+"""Pin: a strippable same-domain over-qualified pipe code carries structured error data (autofix).++Writing a pipe declaration key or ``main_pipe`` as ``<own-domain>.<code>`` is invalid syntax+(pipe codes must be bare snake_case). The two snake_case-enforcing before-validators know both the+offending code and its bare form at detection time; these tests pin that the blueprint error data+carries ``INVALID_PIPE_CODE_SYNTAX`` with the ``stripped_pipe_code`` enrichment — and that+``pipe_code`` discriminates the two raise sites (the offending dotted key for a declaration rename,+``None`` for a ``main_pipe`` value strip). That enriched fact is what the ``strip-namespace`` planner+translates into a fix. Only *safely* strippable codes get enriched: a collision with an existing bare+declaration, a cross-package prefix, or a malformed bare tail all stay un-enriched (unfixable).+"""++from collections.abc import Callable++import pytest++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validate_bundle import validate_bundle++# A same-domain over-qualified DECLARATION key; main_pipe is a valid bare pipe, so the only error is+# the dotted declaration. The qualified step ref survives (it resolves) — not an error.+_DOTTED_DECL_MTHDS = """+domain = "nsfix_decl"+main_pipe = "run_seq"++[pipe."nsfix_decl.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "nsfix_decl.hello", result = "greeting" },+]+"""++# A same-domain over-qualified MAIN_PIPE; all declarations are bare, so the only error is main_pipe.+_DOTTED_MAIN_PIPE_MTHDS = """+domain = "nsfix_main"+main_pipe = "nsfix_main.hello"++[pipe.hello]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++# Collision: a bare `hello` already occupies the key the dotted one would rename to → not strippable.+_COLLISION_MTHDS = """+domain = "nsfix_coll"+main_pipe = "hello"++[pipe.hello]+type = "PipeLLM"+description = "Bare hello."+output = "Text"+prompt = "Bare"++[pipe."nsfix_coll.hello"]+type = "PipeLLM"+description = "Dotted hello."+output = "Text"+prompt = "Dotted"+"""++# Retarget hazard: ``main_pipe`` names the DOTTED declaration while a bare one also exists. The+# declaration rename is collision-blocked, so stripping ``main_pipe`` would silently retarget it+# from the dotted declaration the author referenced to the unrelated bare pipe — the categorizer+# drops the ``main_pipe`` enrichment too (document-level gate).+_MAIN_PIPE_RETARGET_MTHDS = """+domain = "nsfix_ret"+main_pipe = "nsfix_ret.hello"++[pipe.hello]+type = "PipeLLM"+description = "Bare hello."+output = "Text"+prompt = "Bare"++[pipe."nsfix_ret.hello"]+type = "PipeLLM"+description = "Dotted hello."+output = "Text"+prompt = "Dotted"+"""++# Typo'd tail: ``main_pipe`` is dotted but NEITHER the dotted code NOR its bare tail exists as a+# declaration key. Stripping would rewrite ``main_pipe`` to a pipe that does not exist — the fix+# advertised as SAFE would mutate the file and leave a different unfixable error — so the+# enrichment must be suppressed (checkpoint-C item 1, first disjunct-pair failure).+_MAIN_PIPE_TYPO_TAIL_MTHDS = """+domain = "nsfix_typo"+main_pipe = "nsfix_typo.helo"++[pipe.hello]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++# Convergent happy path: ``main_pipe`` names a dotted DECLARATION and no bare form exists. The+# declaration's own strip-namespace rename will materialize the bare target, so stripping+# ``main_pipe`` stays safe — the two fixes converge in one round.+_MAIN_PIPE_DOTTED_DECL_MTHDS = """+domain = "nsfix_conv"+main_pipe = "nsfix_conv.hello"++[pipe."nsfix_conv.hello"]+type = "PipeLLM"+description = "Say hello."+output = "Text"+prompt = "Say hello"+"""++# Cross-package prefix (not the bundle's own domain) → never stripped (would break a real qualified ref).+_CROSS_DOMAIN_MTHDS = """+domain = "nsfix_cross"+main_pipe = "run_seq"++[pipe."otherpkg.hello"]+type = "PipeLLM"+description = "From another package."+output = "Text"+prompt = "Hello"++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "otherpkg.hello", result = "greeting" },+]+"""++# Dotted, same-domain, but the bare tail is itself invalid snake_case → not strippable.+_BAD_BARE_MTHDS = """+domain = "nsfix_bad"+main_pipe = "run_seq"++[pipe."nsfix_bad.Bad-Code"]+type = "PipeLLM"+description = "Bad bare tail."+output = "Text"+prompt = "Hello"++[pipe.run_seq]+type = "PipeSequence"+description = "Run it."+output = "Text"+steps = [+ { pipe = "run_seq", result = "greeting" },+]+"""+++async def _syntax_errors(mthds_content: str) -> list[PipelexBundleBlueprintValidationErrorData]:+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[mthds_content])+ return [+ error_data+ for error_data in exc_info.value.pipelex_bundle_blueprint_validation_errors+ if error_data.error_type == PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX+ ]++[email protected](loop_scope="class")+class TestStripNamespaceEnrichment:+ async def test_dotted_declaration_carries_rename_enrichment(self, load_empty_library: Callable[[], str]) -> None:+ """A same-domain dotted declaration key carries the offending code + its bare form."""+ load_empty_library()+ errors = await _syntax_errors(_DOTTED_DECL_MTHDS)+ strippable = [error for error in errors if error.stripped_pipe_code is not None]+ assert len(strippable) == 1+ assert strippable[0].pipe_code == "nsfix_decl.hello"+ assert strippable[0].stripped_pipe_code == "hello"++ async def test_dotted_main_pipe_carries_strip_enrichment_without_pipe_code(self, load_empty_library: Callable[[], str]) -> None:+ """A same-domain dotted ``main_pipe`` carries the bare form and NO ``pipe_code`` (root set_key)."""+ load_empty_library()+ errors = await _syntax_errors(_DOTTED_MAIN_PIPE_MTHDS)+ strippable = [error for error in errors if error.stripped_pipe_code is not None]+ assert len(strippable) == 1+ assert strippable[0].pipe_code is None+ assert strippable[0].stripped_pipe_code == "hello"++ async def test_main_pipe_strip_suppressed_when_it_would_retarget(self, load_empty_library: Callable[[], str]) -> None:+ """``main_pipe`` naming a dotted declaration that coexists with its bare form: both the+ declaration error and the ``main_pipe`` error stay un-enriched — stripping ``main_pipe``+ would retarget it to the unrelated bare pipe.+ """+ load_empty_library()+ errors = await _syntax_errors(_MAIN_PIPE_RETARGET_MTHDS)+ main_pipe_errors = [error for error in errors if error.pipe_code is None]+ assert main_pipe_errors, "expected the main_pipe INVALID_PIPE_CODE_SYNTAX error"+ assert all(error.stripped_pipe_code is None for error in errors)++ async def test_main_pipe_strip_suppressed_for_typoed_tail(self, load_empty_library: Callable[[], str]) -> None:+ """``main_pipe`` dotted with a typo'd tail (neither the dotted code nor the bare tail is a+ declaration key): the enrichment must be suppressed — stripping would rewrite ``main_pipe``+ to a pipe that does not exist, mutating the file for nothing.+ """+ load_empty_library()+ errors = await _syntax_errors(_MAIN_PIPE_TYPO_TAIL_MTHDS)+ main_pipe_errors = [error for error in errors if error.pipe_code is None]+ assert main_pipe_errors, "expected the main_pipe INVALID_PIPE_CODE_SYNTAX error"+ assert all(error.stripped_pipe_code is None for error in main_pipe_errors)++ async def test_main_pipe_strip_enriched_when_dotted_declaration_will_rename(self, load_empty_library: Callable[[], str]) -> None:+ """``main_pipe`` naming a dotted declaration with NO bare form: still enriched — the+ declaration's paired rename materializes the bare target, so the strip converges.+ """+ load_empty_library()+ errors = await _syntax_errors(_MAIN_PIPE_DOTTED_DECL_MTHDS)+ main_pipe_errors = [error for error in errors if error.pipe_code is None]+ assert main_pipe_errors, "expected the main_pipe INVALID_PIPE_CODE_SYNTAX error"+ assert [error.stripped_pipe_code for error in main_pipe_errors] == ["hello"]++ @pytest.mark.parametrize(+ "mthds_content",+ [_COLLISION_MTHDS, _CROSS_DOMAIN_MTHDS, _BAD_BARE_MTHDS],+ )+ async def test_unstrippable_syntax_errors_are_not_enriched(+ self,+ load_empty_library: Callable[[], str],+ mthds_content: str,+ ) -> None:+ """Collision, cross-package prefix, and a malformed bare tail stay un-enriched (unfixable)."""+ load_empty_library()+ errors = await _syntax_errors(mthds_content)+ assert errors, "expected an INVALID_PIPE_CODE_SYNTAX error"+ assert all(error.stripped_pipe_code is None for error in errors)diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_category_framing.py b/tests/integration/pipelex/pipeline/test_validate_bundle_category_framing.pyindex 803f6aba4..3e508ab8a 100644--- a/tests/integration/pipelex/pipeline/test_validate_bundle_category_framing.py+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_category_framing.py@@ -1,12 +1,15 @@-"""Pin: ValidationError surfacing through the helper carries category-specific copy.--The shared helper ``_translate_to_validate_bundle_error`` is invoked from four-entry points with two distinct categories — ``"pipe"`` from-``validate_bundle*`` and ``"concept"`` from ``load_concepts_only*``. A pydantic-``ValidationError`` raised during model construction surfaces as a single-``ValidateBundleError``; the helper's category controls the user-facing-framing so a concept-side validation error is not framed as a pipe-validation-error (which it would be without the parameter).+"""Pin: a pydantic ValidationError surfacing through the helper produces a clean summary (disease C).++The shared helper ``_translate_to_validate_bundle_error`` is invoked from four entry points —+``validate_bundle*`` (``category="pipe"``) and ``load_concepts_only*`` (``category="concept"``).+A pydantic ``ValidationError`` raised during model construction surfaces as a single+``ValidateBundleError`` whose top-line ``message`` must NOT leak the pydantic repr+(``Value errors: '<field>': Value error, …``) nor the old ``Could not load blueprints/concepts+because of:`` framing prefix that rode on it. Instead the message is the clean, author-facing+summary the constructor derives from the structured error items (``ValidateBundleError.__init__``+→ ``_summarize_bundle_validation_message``) — the same text a consumer reads off the first+``validation_errors[]`` item. This is verified identically for all four entry points because the+clean-summary invariant is category-independent."""import tempfile@@ -45,9 +48,22 @@ name = { type = "text", description = "Customer name" }"""+def _assert_clean_summary(exc: ValidateBundleError) -> None:+ """The top-line message is the clean item summary — no pydantic-repr / framing leak."""+ # Disease C: none of the pre-summary leak fragments survive on the top-line.+ assert "Value error" not in exc.message+ assert "Validation error(s)" not in exc.message+ assert "Could not load blueprints because of" not in exc.message+ assert "Could not load concepts because of" not in exc.message+ # The summary is derived from the structured items: a single item projects its message verbatim.+ items = list(exc.to_error_report().validation_errors or [])+ assert items, "an invalid verdict must carry structured items"+ assert exc.message == items[0].message++@pytest.mark.asyncio(loop_scope="class")class TestValidateBundleCategoryFraming:- async def test_validate_bundle_frames_validation_error_as_pipe(+ async def test_validate_bundle_message_is_clean_summary(self,load_empty_library: Callable[[], str],mocker: MockerFixture,@@ -57,10 +73,9 @@ class TestValidateBundleCategoryFraming:with pytest.raises(ValidateBundleError) as exc_info:await validate_bundle(mthds_contents=[_VALID_MTHDS])- assert "Could not load blueprints because of" in exc_info.value.message- assert "Could not load concepts" not in exc_info.value.message+ _assert_clean_summary(exc_info.value)- async def test_validate_bundles_from_directory_frames_validation_error_as_pipe(+ async def test_validate_bundles_from_directory_message_is_clean_summary(self,load_empty_library: Callable[[], str],mocker: MockerFixture,@@ -72,10 +87,9 @@ class TestValidateBundleCategoryFraming:(Path(tmp_dir) / "test.mthds").write_text(_VALID_MTHDS, encoding="utf-8")with pytest.raises(ValidateBundleError) as exc_info:await validate_bundles_from_directory(directory=Path(tmp_dir))- assert "Could not load blueprints because of" in exc_info.value.message- assert "Could not load concepts" not in exc_info.value.message+ _assert_clean_summary(exc_info.value)- async def test_load_concepts_only_frames_validation_error_as_concept(+ async def test_load_concepts_only_message_is_clean_summary(self,load_empty_library: Callable[[], str],mocker: MockerFixture,@@ -85,10 +99,9 @@ class TestValidateBundleCategoryFraming:with pytest.raises(ValidateBundleError) as exc_info:load_concepts_only(mthds_contents=[_VALID_MTHDS])- assert "Could not load concepts because of" in exc_info.value.message- assert "Could not load blueprints" not in exc_info.value.message+ _assert_clean_summary(exc_info.value)- async def test_load_concepts_only_from_directory_frames_validation_error_as_concept(+ async def test_load_concepts_only_from_directory_message_is_clean_summary(self,load_empty_library: Callable[[], str],mocker: MockerFixture,@@ -100,5 +113,4 @@ class TestValidateBundleCategoryFraming:(Path(tmp_dir) / "test.mthds").write_text(_VALID_MTHDS, encoding="utf-8")with pytest.raises(ValidateBundleError) as exc_info:load_concepts_only_from_directory(directory=Path(tmp_dir))- assert "Could not load concepts because of" in exc_info.value.message- assert "Could not load blueprints" not in exc_info.value.message+ _assert_clean_summary(exc_info.value)diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.pyindex f15fcdabf..53c675af6 100644--- a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py@@ -1,21 +1,31 @@-"""Integration: ``validate_bundle`` threads per-content ``mthds_sources`` into ``blueprint.source``.--The API submits sourceless bundle text (``mthds_contents: list[str]``), so without-a per-item source the in-memory load path sets ``blueprint.source = None`` and-cross-file diagnostics misfire. ``validate_bundle(mthds_sources=...)`` pairs each-content with its logical source, so the loaded blueprint — and any-``ValidateBundleError`` it raises — carries a real ``source`` the consumer can map-to the owning file. The CLI's on-disk path keeps using real file paths and is-unaffected.+"""Integration: ``validate_bundle`` threads a real ``source`` onto its structured errors.++Two channels are pinned here:++- The API submits sourceless bundle text (``mthds_contents: list[str]``), so without+ a per-item source the in-memory load path sets ``blueprint.source = None`` and+ cross-file diagnostics misfire. ``validate_bundle(mthds_sources=...)`` pairs each+ content with its logical source, so the loaded blueprint — and any+ ``ValidateBundleError`` it raises — carries a real ``source`` the consumer can map+ to the owning file. The CLI's on-disk path keeps using real file paths and is+ unaffected.+- Pipe-channel errors (``PipeValidationError`` raised during library validation)+ don't know their file at the raise site; the translate funnel backfills+ ``file_path`` from the library manager's pipe-source map (keyed by the full+ ``domain.pipe_code`` ref) so the categorized item — and the suggested fix riding+ it — names the declaring ``.mthds`` file even in multi-file libraries."""from collections.abc import Callable+from pathlib import Pathimport pytest+from pytest_mock import MockerFixture-from pipelex.base_exceptions import PipelexUnexpectedError, ValidationErrorCategory+from pipelex.base_exceptions import PipelexUnexpectedError, ValidationErrorCategory, ValidationErrorItem+from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorTypefrom pipelex.pipeline.exceptions import ValidateBundleError-from pipelex.pipeline.validate_bundle import validate_bundle+from pipelex.pipeline.validate_bundle import _backfill_pipe_error_source, validate_bundle # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]_VALID_MTHDS = """domain = "testapp"@@ -45,9 +55,104 @@ domain = "testapp"description = "the table header above is never closed""""+# Deliberate INADEQUATE_OUTPUT_MULTIPLICITY: the sequence declares a single Idea while its last+# step yields a list — a pipe-channel error raised during library validation, far from any file.+_ENTRY_SEQ_MISMATCH_MTHDS = """domain = "srcthread_entry"+main_pipe = "list_ideas"++[concept]+Idea = "An idea."++[pipe.gen_ideas]+type = "PipeLLM"+description = "Generate ideas."+inputs = { topic = "Text" }+output = "Idea[]"+prompt = "Generate ideas about $topic"++[pipe.list_ideas]+type = "PipeSequence"+description = "Sequence declaring a single output while the last step yields a list."+inputs = { topic = "Text" }+output = "Idea"+steps = [+ { pipe = "gen_ideas", result = "ideas" },+]+"""++# Same deliberate mismatch, declared by a *sibling* library file (different domain), so the+# pipe-channel error must carry the sibling's path — not the entry file's.+_SIBLING_SEQ_MISMATCH_MTHDS = _ENTRY_SEQ_MISMATCH_MTHDS.replace("srcthread_entry", "srcthread_sibling")++_ENTRY_INPUT_DRIFT_MTHDS = """domain = "srcthread_input_entry"+main_pipe = "make_summary"++[concept]+Summary = "A summary of a text."++[pipe.write_summary]+type = "PipeLLM"+description = "Summarize the text."+inputs = { text = "Text", style = "Text" }+output = "Summary"+prompt = "Summarize $text in style $style"++[pipe.make_summary]+type = "PipeSequence"+description = "Sequence with drifted inputs."+inputs = { text = "Number", note = "Text" }+output = "Summary"+steps = [+ { pipe = "write_summary", result = "summary" },+]+"""++_SIBLING_INPUT_DRIFT_MTHDS = _ENTRY_INPUT_DRIFT_MTHDS.replace("srcthread_input_entry", "srcthread_input_sibling")++_VALID_ENTRY_MTHDS = """domain = "srcthread_valid"+main_pipe = "say_hi"++[pipe.say_hi]+type = "PipeLLM"+description = "Say hi."+output = "Text"+prompt = "Say hi"+"""+++def _pipe_channel_items(exc: ValidateBundleError, *, error_type: PipeValidationErrorType) -> list[ValidationErrorItem]:+ report = exc.to_error_report()+ assert report.validation_errors is not None+ return [item for item in report.validation_errors if item.category == ValidationErrorCategory.PIPE_VALIDATION and item.error_type == error_type]+++def _input_drift_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:+ report = exc.to_error_report()+ assert report.validation_errors is not None+ input_drift_types = {+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH,+ }+ return [+ item for item in report.validation_errors if item.category == ValidationErrorCategory.PIPE_VALIDATION and item.error_type in input_drift_types+ ]+@pytest.mark.asyncio(loop_scope="class")class TestValidateBundleSourceThreading:+ async def test_old_injected_manager_path_source_is_normalized(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """Managers implementing the former ``Path`` return contract remain compatible."""+ source_path = tmp_path / "legacy.mthds"+ manager = mocker.Mock()+ manager.get_pipe_source.return_value = source_path+ mocker.patch("pipelex.pipeline.validate_bundle.get_library_manager", return_value=manager)+ pipe_error = PipeValidationError(message="invalid", domain_code="demo", pipe_code="broken")++ _backfill_pipe_error_source(pipe_error)++ assert pipe_error.file_path == str(source_path)+async def test_valid_bundle_blueprint_carries_threaded_source(self,load_empty_library: Callable[[], str],@@ -116,3 +221,147 @@ class TestValidateBundleSourceThreading:load_empty_library()with pytest.raises(PipelexUnexpectedError, match="must be a per-item source list matching mthds_contents"):await validate_bundle(mthds_contents=[_VALID_MTHDS], mthds_sources=["a.mthds", "b.mthds"])++ async def test_pipe_channel_error_carries_entry_file_source(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A pipe-channel error on an entry-file pipe carries the entry file as ``source``.++ The raise site (``PipeSequence.validate_output_with_library``) doesn't know the file;+ the translate funnel must backfill it from the library manager's pipe-source map so the+ suggested fix riding the item is addressable to a file.+ """+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_ENTRY_SEQ_MISMATCH_MTHDS, encoding="utf-8")++ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_file_path=bundle_path)++ items = _pipe_channel_items(exc_info.value, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert items, "expected a pipe-channel INADEQUATE_OUTPUT_MULTIPLICITY item"+ for item in items:+ assert item.source is not None, "pipe-channel item must carry the declaring file as source"+ assert Path(item.source).resolve() == bundle_path.resolve()+ assert item.suggested_fix is not None+ assert item.suggested_fix.source == item.source++ async def test_pipe_channel_error_carries_sibling_file_source(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A pipe-channel error on a pipe declared by a sibling library file names the sibling.++ This is what makes multi-file fix targeting possible: the fix must patch the declaring+ file, never the entry file's same-named table.+ """+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_VALID_ENTRY_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_SIBLING_SEQ_MISMATCH_MTHDS, encoding="utf-8")++ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[libs_dir])++ items = _pipe_channel_items(exc_info.value, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert items, "expected a pipe-channel INADEQUATE_OUTPUT_MULTIPLICITY item"+ for item in items:+ assert item.source is not None, "sibling-declared pipe error must carry the sibling file as source"+ assert Path(item.source).resolve() == sibling_path.resolve()+ assert item.suggested_fix is not None+ assert item.suggested_fix.source == item.source++ async def test_input_drift_error_carries_entry_file_source(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A fixable input-drift pipe-channel error carries the entry file as ``source``."""+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_ENTRY_INPUT_DRIFT_MTHDS, encoding="utf-8")++ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_file_path=bundle_path)++ items = _input_drift_items(exc_info.value)+ assert items, "expected a pipe-channel controller-input-drift item"+ for item in items:+ assert item.source is not None+ assert Path(item.source).resolve() == bundle_path.resolve()+ assert item.suggested_fix is not None+ assert item.suggested_fix.fix_code == "sync-controller-inputs"+ assert item.suggested_fix.source == item.source++ async def test_input_drift_error_carries_sibling_file_source(+ self,+ tmp_path: Path,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A fixable input-drift error in a sibling library file names that sibling file."""+ load_empty_library()+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_VALID_ENTRY_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_SIBLING_INPUT_DRIFT_MTHDS, encoding="utf-8")++ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[libs_dir])++ items = _input_drift_items(exc_info.value)+ assert items, "expected a pipe-channel controller-input-drift item"+ for item in items:+ assert item.source is not None+ assert Path(item.source).resolve() == sibling_path.resolve()+ assert item.suggested_fix is not None+ assert item.suggested_fix.fix_code == "sync-controller-inputs"+ assert item.suggested_fix.source == item.source++ async def test_pipe_channel_lookup_miss_leaves_source_absent(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """When the pipe-source map has no entry (sourceless in-memory content), ``source`` stays unset.++ The backfill must only set what it can prove — a lookup miss falls back to the source-less+ conservative path, never a guess.+ """+ load_empty_library()+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[_ENTRY_SEQ_MISMATCH_MTHDS])++ items = _pipe_channel_items(exc_info.value, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert items, "expected a pipe-channel INADEQUATE_OUTPUT_MULTIPLICITY item"+ for item in items:+ assert item.source is None++ async def test_pipe_channel_error_preserves_logical_source(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A pipe-channel error on an in-memory bundle keeps its logical URI source verbatim.++ The backfill reads the source from the library manager's pipe-source map. A logical+ source like ``api://bundle-0.mthds`` (passed via ``mthds_sources``) must survive the+ round-trip unchanged — never mangled to ``api:/bundle-0.mthds`` by a ``Path`` coercion —+ so API/MCP clients can map the diagnostic and its suggested fix back to the submitted+ bundle.+ """+ load_empty_library()+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_contents=[_ENTRY_SEQ_MISMATCH_MTHDS], mthds_sources=["api://bundle-0.mthds"])++ items = _pipe_channel_items(exc_info.value, error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY)+ assert items, "expected a pipe-channel INADEQUATE_OUTPUT_MULTIPLICITY item"+ for item in items:+ assert item.source == "api://bundle-0.mthds"+ assert item.suggested_fix is not None+ assert item.suggested_fix.source == "api://bundle-0.mthds"diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.pyindex a8f6bccec..cd5814ac0 100644--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py@@ -67,8 +67,15 @@ class TestPipeSequenceOutputMultiplicity:with pytest.raises(PipeValidationError) as exc_info:sequence_pipe.validate_with_libraries()- error_message = str(exc_info.value).lower()+ error_str = str(exc_info.value)+ error_message = error_str.lower()assert "multiplicity" in error_message, f"Error should mention multiplicity mismatch, got: {exc_info.value}"+ # The message must speak author syntax (Text vs Text[3]) and name the concrete fix, never the+ # internal repr (`multiplicity=None/True`).+ assert "multiplicity=" not in error_str, f"Message leaks internal repr: {error_str}"+ assert "declares its output as 'Text'" in error_str, error_str+ assert "yields 'Text[3]'" in error_str, error_str+ assert "Update the sequence's output to 'Text[3]'" in error_str, error_strdef test_no_multiplicity_matching_passes(self,diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.pynew file mode 100644index 000000000..5a0409b3e--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py@@ -0,0 +1,84 @@+"""Unit tests for resolve_bundle_target: shared path→bundle resolution for agent CLI bundle commands.++Pins that ``~`` is expanded for both the ``path`` argument and each ``--library-dir`` entry, so+home-relative inputs resolve like every other CLI path argument instead of being treated as literal+filenames/directories.+"""++from pathlib import Path++import pytest+import typer++from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_target+++class TestResolveBundleTarget:+ def test_file_mode_expands_tilde(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """A ``~/foo.mthds`` file argument resolves to its absolute path, never the literal ``~`` form."""+ monkeypatch.setenv("HOME", str(tmp_path))+ bundle_file = tmp_path / "foo.mthds"+ bundle_file.write_text('domain = "x"\n', encoding="utf-8")++ bundle_path, library_dir = resolve_bundle_target("~/foo.mthds", library_dir=None)++ assert bundle_path == str(bundle_file)+ assert "~" not in bundle_path+ assert library_dir is None++ def test_directory_mode_expands_tilde_and_injects_expanded_dir(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """A ``~/pkg`` directory argument resolves its default bundle and injects the expanded dir into library_dir."""+ monkeypatch.setenv("HOME", str(tmp_path))+ pkg_dir = tmp_path / "pkg"+ pkg_dir.mkdir()+ bundle_file = pkg_dir / DEFAULT_BUNDLE_FILE_NAME+ bundle_file.write_text('domain = "x"\n', encoding="utf-8")++ bundle_path, library_dir = resolve_bundle_target("~/pkg", library_dir=None)++ assert bundle_path == str(bundle_file)+ assert library_dir == [str(pkg_dir)]++ def test_library_dir_entries_expand_tilde(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """A home-relative ``--library-dir`` entry is expanded to its absolute path in the returned list."""+ monkeypatch.setenv("HOME", str(tmp_path))+ bundle_file = tmp_path / "foo.mthds"+ bundle_file.write_text('domain = "x"\n', encoding="utf-8")++ _, library_dir = resolve_bundle_target("~/foo.mthds", library_dir=["~/mylibs"])++ assert library_dir == [str(tmp_path / "mylibs")]++ def test_ambiguous_directory_error_names_candidates_in_sorted_order(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """Ambiguous-directory diagnostics are stable across filesystem iteration order."""+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ try:+ (tmp_path / "b.mthds").write_text('domain = "b"\n', encoding="utf-8")+ (tmp_path / "a.mthds").write_text('domain = "a"\n', encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path), library_dir=None)+ finally:+ set_agent_cli_error_format(CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 2+ err = capsys.readouterr().err+ assert "(a.mthds, b.mthds)" in err++ def test_directory_refuses_auto_detected_symlink(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """Directory mode must not turn an external symlink target into an implicitly writable entry file."""+ outside_bundle = tmp_path.parent / f"{tmp_path.name}-outside.mthds"+ outside_bundle.write_text('domain = "outside"\n', encoding="utf-8")+ (tmp_path / DEFAULT_BUNDLE_FILE_NAME).symlink_to(outside_bundle)++ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ try:+ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path), library_dir=None)+ finally:+ set_agent_cli_error_format(CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 2+ assert "Refusing to auto-detect symlinked bundle" in capsys.readouterr().errdiff --git a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py b/tests/unit/pipelex/cli/agent_cli/test_fix_format.pynew file mode 100644index 000000000..c554f697b--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py@@ -0,0 +1,224 @@+"""Unit tests for the agent CLI fix command format and argument handling."""++from __future__ import annotations++import json+from typing import TYPE_CHECKING++import pytest+import typer++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat+from pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmd+from pipelex.pipeline.fixes.fix_loop import FixBundleResult+from pipelex.suggested_fix import FixSafety, SuggestedFix++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++FIX_BUNDLE_MODULE = "pipelex.cli.agent_cli.commands.fix.bundle_cmd"+++def _applied_fix(source: str) -> SuggestedFix:+ return SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output of pipe 'list_ideas' to 'Idea[]'",+ safety=FixSafety.SAFE,+ source=source,+ ops=[],+ )+++def _invalid_item(source: str) -> ValidationErrorItem:+ return ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="INADEQUATE_OUTPUT_CONCEPT",+ message="output mismatch",+ source=source,+ )+++def _patch_command(+ mocker: MockerFixture,+ *,+ result: FixBundleResult,+) -> None:+ mocker.patch(f"{FIX_BUNDLE_MODULE}.make_pipelex_for_agent_cli")+ mocker.patch(f"{FIX_BUNDLE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_BUNDLE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(return_value=result))+++class TestFixFormat:+ def test_fix_markdown_is_default(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=True,+ iterations=1,+ fixes_applied=[_applied_fix(str(bundle_path))],+ files_written=[str(bundle_path.resolve())],+ remaining_errors=[],+ )+ _patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path))++ out = capsys.readouterr().out+ assert out.startswith("# Fix applied - bundle is valid")+ assert "`match-sequence-output`" in out+ with pytest.raises(json.JSONDecodeError):+ json.loads(out)++ def test_fix_json_with_format_json(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ )+ _patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ parsed = json.loads(capsys.readouterr().out)+ assert parsed["success"] is True+ assert parsed["is_valid"] is True+ assert parsed["bundle_path"] == str(bundle_path.resolve())++ def test_non_runnable_success_exits_one_after_json_payload(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ ) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ pending_signatures=["fix_format.pending_pipe"],+ is_runnable=False,+ )+ _patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.err == ""+ parsed = json.loads(captured.out)+ assert parsed["success"] is True+ assert parsed["is_valid"] is True+ assert parsed["is_runnable"] is False+ assert parsed["pending_signatures"] == ["fix_format.pending_pipe"]++ def test_allow_signatures_tolerates_non_runnable_success(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ ) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ pending_signatures=["fix_format.pending_pipe"],+ is_runnable=False,+ )+ _patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path), allow_signatures=True, output_format=CliOutputFormat.JSON)++ parsed = json.loads(capsys.readouterr().out)+ assert parsed["success"] is True+ assert parsed["is_runnable"] is False+ assert parsed["pending_signatures"] == ["fix_format.pending_pipe"]++ def test_still_invalid_emits_json_error(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=False,+ iterations=1,+ fixes_applied=[_applied_fix(str(bundle_path))],+ files_written=[str(bundle_path.resolve())],+ remaining_errors=[_invalid_item(str(bundle_path))],+ bail_reason="no safe fixes remain",+ )+ _patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ parsed = json.loads(capsys.readouterr().err)+ assert parsed["error"] is True+ assert parsed["error_type"] == "FixBundleError"+ assert parsed["is_valid"] is False+ assert parsed["bail_reason"] == "no safe fixes remain"+ assert parsed["remaining_errors"][0]["source"] == str(bundle_path)++ def test_still_invalid_markdown_renders_prose(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ """Default (markdown) still-invalid renders the remaining errors as prose on stderr, not a JSON dump."""+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=False,+ iterations=1,+ fixes_applied=[_applied_fix(str(bundle_path))],+ files_written=[str(bundle_path.resolve())],+ remaining_errors=[_invalid_item(str(bundle_path))],+ bail_reason="no safe fixes remain",+ )+ _patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path)) # default output_format is markdown++ assert exc_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.out == ""+ assert captured.err.startswith("# Fix incomplete - bundle still invalid")+ assert "## Applied Fixes" in captured.err+ assert "**Stopped:** no safe fixes remain" in captured.err+ assert "## Pipe validation errors" in captured.err+ with pytest.raises(json.JSONDecodeError):+ json.loads(captured.err)++ def test_select_and_ignore_are_mutually_exclusive(self, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(+ path="unused.mthds",+ select_codes_raw=["match-sequence-output"],+ ignore_codes_raw=["strip-namespace"],+ output_format=CliOutputFormat.JSON,+ )++ assert exc_info.value.exit_code == 2+ parsed = json.loads(capsys.readouterr().err)+ assert parsed["error_type"] == "ArgumentError"+ assert "mutually exclusive" in parsed["message"]++ def test_unknown_fix_code_is_rejected(self, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path="unused.mthds", select_codes_raw=["typo-rule"], output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 2+ parsed = json.loads(capsys.readouterr().err)+ assert parsed["error_type"] == "ArgumentError"+ assert parsed["unknown_fix_codes"] == ["typo-rule"]+ assert "match-sequence-output" in parsed["known_fix_codes"]diff --git a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.pynew file mode 100644index 000000000..1c74c2754--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py@@ -0,0 +1,115 @@+"""Unit tests for the agent-CLI bundle-validation failure surface (``agent_error_validate_bundle``).++Markdown renders the structured items as prose with a fix-aware footer; JSON keeps the exact+structured envelope (``is_valid`` / ``bundle_path`` / ``validation_errors`` + the unchanged hint).+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING++import pytest+import typer++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.cli.agent_cli.commands.agent_output import (+ CliOutputFormat,+ _render_validate_bundle_markdown, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ agent_error_validate_bundle,+ set_agent_cli_error_format,+)+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.suggested_fix import FixSafety, SuggestedFix++if TYPE_CHECKING:+ from collections.abc import Iterator+ from pathlib import Path+++def _fixable_item(*, source: Path) -> ValidationErrorItem:+ return ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="inadequate_output_multiplicity",+ pipe_code="brainstorm",+ domain_code="story_studio",+ source=str(source),+ message="the sequence declares 'StoryIdea' but its last step yields 'StoryIdea[]'.",+ suggested_fix=SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step",+ safety=FixSafety.SAFE,+ source=str(source),+ ops=[],+ ),+ )+++class TestValidateBundleErrorFormat:+ @pytest.fixture(autouse=True)+ def _reset_error_format(self) -> Iterator[None]:+ # The error format is a process-global ContextVar; reset it after each test so a markdown+ # test can't leak into a later JSON-default test (mirrors the app callback's per-invocation reset).+ yield+ set_agent_cli_error_format(CliOutputFormat.JSON)++ def test_markdown_renders_prose_and_fix_aware_footer(self, tmp_path: Path) -> None:+ """Markdown renders a heading, the bundle, prose items with the 💡 fix line, and a fix-aware footer."""+ bundle_path = tmp_path / "bundle.mthds"+ markdown = _render_validate_bundle_markdown(+ [_fixable_item(source=bundle_path)],+ bundle_path=bundle_path,+ library_dirs=[tmp_path / "libs"],+ allow_signatures=False,+ )++ assert markdown.startswith("# Bundle validation failed")+ assert f"**Bundle:** `{bundle_path}`" in markdown+ assert "1. **Inadequate Output Multiplicity**" in markdown+ assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown+ # Disease E: the boilerplate hint is replaced by a fix-aware footer naming the exact command with -L echoed.+ assert "Check the validation_errors array" not in markdown+ assert f"💡 1 of these errors can be fixed automatically — run: `pipelex-agent fix bundle {bundle_path} -L {tmp_path / 'libs'}`" in markdown++ def test_markdown_no_fix_footer_when_nothing_fixable(self, tmp_path: Path) -> None:+ """With no suggested fix, the footer points at the messages instead of naming a fix command."""+ item = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="something is wrong")++ markdown = _render_validate_bundle_markdown([item], bundle_path=tmp_path / "b.mthds", library_dirs=None, allow_signatures=False)++ assert "no automatic fix" in markdown+ assert "pipelex-agent fix bundle" not in markdown++ def test_markdown_dispatch_emits_prose_to_stderr(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:+ """In markdown mode the dispatcher prints prose (not JSON) to stderr and exits 1."""+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ exc = ValidateBundleError(message="Could not load blueprints because of: bad stuff")++ with pytest.raises(typer.Exit) as exc_info:+ agent_error_validate_bundle(exc, bundle_path=tmp_path / "b.mthds")++ assert exc_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.out == ""+ assert captured.err.startswith("# Bundle validation failed")+ with pytest.raises(json.JSONDecodeError):+ json.loads(captured.err)++ def test_json_dispatch_emits_unchanged_structured_envelope(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:+ """In JSON mode the dispatcher emits the byte-stable structured envelope hooks branch on."""+ set_agent_cli_error_format(CliOutputFormat.JSON)+ bundle_path = tmp_path / "b.mthds"+ exc = ValidateBundleError(message="no details")++ with pytest.raises(typer.Exit) as exc_info:+ agent_error_validate_bundle(exc, bundle_path=bundle_path)++ assert exc_info.value.exit_code == 1+ parsed = json.loads(capsys.readouterr().err)+ assert parsed["error"] is True+ assert parsed["error_type"] == "ValidateBundleError"+ assert parsed["is_valid"] is False+ assert parsed["bundle_path"] == str(bundle_path)+ # The message-only residual makes the structured-info invariant total; the hint stays the JSON boilerplate.+ assert parsed["validation_errors"] == [{"category": "blueprint_validation", "message": "no details"}]+ assert parsed["hint"] == "Check the validation_errors array for specific issues"diff --git a/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py b/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.pynew file mode 100644index 000000000..a700fc2ea--- /dev/null+++ b/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py@@ -0,0 +1,162 @@+"""Unit tests for the ``--diff`` temp-copy sandbox (mirror + copy→original mapping)."""++from __future__ import annotations++from typing import TYPE_CHECKING++from pipelex.cli.commands.fix._diff_sandbox import mirror_bundle_for_preview # noqa: PLC2701++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture+++class TestDiffSandbox:+ def _sandbox_root(self, tmp_path: Path) -> Path:+ sandbox_root = tmp_path / "sandbox"+ sandbox_root.mkdir()+ return sandbox_root++ def test_entry_only_copies_entry_with_frozen_empty_load_scope(self, tmp_path: Path) -> None:+ entry = tmp_path / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=None, sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.entry_path != entry.resolve()+ assert sandbox.entry_path.read_text(encoding="utf-8") == 'domain = "demo"\n'+ assert sandbox.library_dirs == []+ assert sandbox.writable_library_dirs == []+ assert sandbox.to_original(str(sandbox.entry_path)) == str(entry.resolve())++ def test_explicit_empty_dirs_stay_empty(self, tmp_path: Path) -> None:+ entry = tmp_path / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs == []+ assert sandbox.writable_library_dirs == []++ def test_entry_under_library_dir_maps_inside_the_dir_copy(self, tmp_path: Path) -> None:+ """Directory mode: the sandbox entry must be the file INSIDE the mirrored dir, or pipes load twice."""+ bundle_dir = tmp_path / "pipeline_01"+ bundle_dir.mkdir()+ entry = bundle_dir / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ (bundle_dir / "sibling.mthds").write_text('domain = "sibling"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[bundle_dir], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ copy_dir = sandbox.library_dirs[0]+ assert sandbox.entry_path == copy_dir / "bundle.mthds"+ assert (copy_dir / "sibling.mthds").is_file()+ assert sandbox.to_original(str(copy_dir / "sibling.mthds")) == str((bundle_dir / "sibling.mthds").resolve())+ assert sandbox.writable_library_dirs == [copy_dir]++ def test_equivalent_explicit_dirs_share_one_canonical_copy(self, tmp_path: Path) -> None:+ bundle_dir = tmp_path / "bundle"+ bundle_dir.mkdir()+ entry = bundle_dir / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(+ entry,+ library_dirs=[bundle_dir, bundle_dir / "."],+ sandbox_root=self._sandbox_root(tmp_path),+ )++ assert sandbox.library_dirs is not None+ assert len(sandbox.library_dirs) == 1+ assert sandbox.writable_library_dirs == sandbox.library_dirs++ def test_ambient_entry_uses_same_read_only_canonical_copy(self, tmp_path: Path, mocker: MockerFixture) -> None:+ bundle_dir = tmp_path / "bundle"+ bundle_dir.mkdir()+ entry = bundle_dir / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ mocker.patch(+ "pipelex.cli.commands.fix._diff_sandbox.resolve_library_dirs",+ return_value=([bundle_dir], "PIPELEXPATH"),+ )++ sandbox = mirror_bundle_for_preview(entry, library_dirs=None, sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ assert sandbox.entry_path == sandbox.library_dirs[0] / entry.name+ assert sandbox.writable_library_dirs == []++ def test_entry_outside_library_dirs_gets_standalone_copy(self, tmp_path: Path) -> None:+ entry = tmp_path / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ (libs_dir / "helper.mthds").write_text('domain = "helper"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[libs_dir], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ assert sandbox.entry_path.read_text(encoding="utf-8") == 'domain = "demo"\n'+ assert not sandbox.entry_path.is_relative_to(sandbox.library_dirs[0])+ assert sandbox.to_original(str(sandbox.entry_path)) == str(entry.resolve())+ assert sandbox.to_original(str(sandbox.library_dirs[0] / "helper.mthds")) == str((libs_dir / "helper.mthds").resolve())++ def test_missing_library_dir_mirrors_as_empty_copy_without_crashing(self, tmp_path: Path) -> None:+ """A non-existent -L dir must not crash copytree: the real loader skips it, so the sandbox mirrors it as an empty dir."""+ entry = tmp_path / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ missing_dir = tmp_path / "typo_dir"++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[missing_dir], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ # The missing dir is preserved 1:1 (so is_single_file matches the real run) as an empty copy.+ copy_dir = sandbox.library_dirs[0]+ assert copy_dir.is_dir()+ assert list(copy_dir.iterdir()) == []+ # The entry lives outside the missing dir, so it gets a standalone copy.+ assert sandbox.entry_path.read_text(encoding="utf-8") == 'domain = "demo"\n'+ assert sandbox.to_original(str(copy_dir / "would_be.mthds")) == str((missing_dir / "would_be.mthds").resolve())++ def test_paths_outside_the_sandbox_pass_through(self, tmp_path: Path) -> None:+ entry = tmp_path / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ ambient_file = tmp_path / "ambient.mthds"+ ambient_file.write_text('domain = "ambient"\n', encoding="utf-8")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=None, sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.to_original(str(ambient_file)) == str(ambient_file.resolve())++ def test_copy_uses_loader_exclusions(self, tmp_path: Path) -> None:+ bundle_dir = tmp_path / "bundle"+ bundle_dir.mkdir()+ entry = bundle_dir / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ excluded_dir = bundle_dir / ".venv"+ excluded_dir.mkdir()+ (excluded_dir / "large.bin").write_bytes(b"must not be copied")++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[bundle_dir], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ assert not (sandbox.library_dirs[0] / ".venv").exists()++ def test_copy_preserves_external_directory_symlink(self, tmp_path: Path) -> None:+ bundle_dir = tmp_path / "bundle"+ bundle_dir.mkdir()+ entry = bundle_dir / "bundle.mthds"+ entry.write_text('domain = "demo"\n', encoding="utf-8")+ external_dir = tmp_path / "external"+ external_dir.mkdir()+ (external_dir / "large.bin").write_bytes(b"must not be copied")+ (bundle_dir / "linked").symlink_to(external_dir, target_is_directory=True)++ sandbox = mirror_bundle_for_preview(entry, library_dirs=[bundle_dir], sandbox_root=self._sandbox_root(tmp_path))++ assert sandbox.library_dirs is not None+ copied_link = sandbox.library_dirs[0] / "linked"+ assert copied_link.is_symlink()+ assert copied_link.readlink() == external_dirdiff --git a/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.pynew file mode 100644index 000000000..cc2327032--- /dev/null+++ b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py@@ -0,0 +1,423 @@+"""Unit tests for the human ``pipelex fix bundle`` rendering and argument handling.++Mirrors the agent-side ``test_fix_format.py``: the fix loop is patched with a canned+``FixBundleResult`` per verdict arm, and the Rich output is recorded through a plain-text+console. Covers all verdict arms of D5.4 plus the ``--select``/``--ignore`` validation.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+import typer+from rich.console import Console++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.cli.commands.fix._diff_sandbox import PreviewSandbox # noqa: PLC2701+from pipelex.cli.commands.fix._fix_core import _remap_result_to_originals # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+from pipelex.cli.commands.fix.bundle_cmd import fix_bundle_cmd+from pipelex.pipeline.fixes.fix_loop import FixBundleResult+from pipelex.suggested_fix import FixSafety, SuggestedFix++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++FIX_CORE_MODULE = "pipelex.cli.commands.fix._fix_core"+++def _applied_fix(source: str | None) -> SuggestedFix:+ return SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output of pipe 'list_ideas' to 'Idea[]' to match its last step",+ safety=FixSafety.SAFE,+ source=source,+ ops=[],+ )+++def _remaining_item(source: str) -> ValidationErrorItem:+ return ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="MISSING_CONCEPT",+ pipe_code="say_hi",+ message="concept 'MissingConcept' is not declared",+ source=source,+ )+++def _fixable_remaining_item(source: str) -> ValidationErrorItem:+ """A remaining error that still carries a suggested fix — e.g. skipped by --select/--ignore or left out of write scope."""+ return ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="INADEQUATE_OUTPUT_CONCEPT",+ pipe_code="list_ideas",+ message="output concept does not match the last step",+ source=source,+ suggested_fix=_applied_fix(source),+ )+++class TestFixBundleHumanFormat:+ @pytest.fixture+ def console(self, mocker: MockerFixture) -> Console:+ """Recorded plain-text console patched into the fix core module."""+ recorded_console = Console(width=500, record=True, color_system=None)+ mocker.patch(f"{FIX_CORE_MODULE}.get_console", return_value=recorded_console)+ return recorded_console++ def _patch_command(self, mocker: MockerFixture, *, result: FixBundleResult) -> None:+ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")+ mocker.patch(f"{FIX_CORE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(return_value=result))++ def _bundle_file(self, tmp_path: Path) -> Path:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_human_format"\n', encoding="utf-8")+ return bundle_path++ def test_fixed_valid_names_every_change_and_exits_zero(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=True,+ iterations=1,+ fixes_applied=[_applied_fix(str(bundle_path))],+ files_written=[str(bundle_path.resolve())],+ remaining_errors=[],+ pending_signatures=[],+ is_runnable=True,+ )+ self._patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path))++ output = console.export_text()+ assert "✅ Bundle fixed — valid" in output+ assert f"Bundle: {bundle_path}" in output+ assert "1. Set output of pipe 'list_ideas' to 'Idea[]' to match its last step (match-sequence-output)" in output+ assert "Files written:" in output+ assert str(bundle_path.resolve()) in output+ assert "Iterations: 1" in output++ def test_fix_sourced_at_another_file_names_that_file(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:+ bundle_path = self._bundle_file(tmp_path)+ library_file = tmp_path / "library.mthds"+ library_file.write_text('domain = "library"\n', encoding="utf-8")+ result = FixBundleResult(+ is_valid=True,+ iterations=1,+ fixes_applied=[_applied_fix(str(library_file))],+ files_written=[str(library_file.resolve())],+ remaining_errors=[],+ pending_signatures=[],+ is_runnable=True,+ )+ self._patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path))++ output = console.export_text()+ assert f"(match-sequence-output) — {library_file}" in output++ def test_already_valid_exits_zero(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ pending_signatures=[],+ is_runnable=True,+ )+ self._patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path))++ output = console.export_text()+ assert "✅ Bundle already valid" in output+ assert "Applied fixes:" not in output+ assert "Iterations:" not in output++ def test_valid_not_runnable_without_allow_signatures_exits_one(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ pending_signatures=["fix_human_format.pending_pipe"],+ is_runnable=False,+ )+ self._patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "NOT yet runnable" in output+ assert "fix_human_format.pending_pipe" in output+ assert "--allow-signatures" in output++ def test_valid_not_runnable_with_allow_signatures_exits_zero(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=True,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[],+ pending_signatures=["fix_human_format.pending_pipe"],+ is_runnable=False,+ )+ self._patch_command(mocker, result=result)++ fix_bundle_cmd(path=str(bundle_path), allow_signatures=True)++ output = console.export_text()+ assert "✅ Bundle already valid" in output+ assert "Pending PipeSignature placeholder(s): fix_human_format.pending_pipe" in output+ assert "NOT yet runnable" not in output++ def test_still_invalid_shows_partial_progress_bail_reason_and_remaining_errors(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ ) -> None:+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=False,+ iterations=2,+ fixes_applied=[_applied_fix(str(bundle_path))],+ files_written=[str(bundle_path.resolve())],+ remaining_errors=[_remaining_item(str(bundle_path))],+ bail_reason="no progress: every proposed fix fingerprint was already applied",+ )+ self._patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "❌ Bundle could not be fully fixed" in output+ assert "1. Set output of pipe 'list_ideas' to 'Idea[]' to match its last step (match-sequence-output)" in output+ assert "Stopped: no progress" in output+ assert "Remaining errors:" in output+ assert "Pipe Validation Errors:" in output+ assert "concept 'MissingConcept' is not declared" in output+ assert "💡 Tip:" in output+ # The remaining error has no suggested fix, so the manual-edit tip is correct here.+ assert "no deterministic safe fix" in output++ def test_still_invalid_with_a_suggested_fix_remaining_does_not_claim_no_safe_fix(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ ) -> None:+ """A remaining error still showing a 💡 suggested fix (skipped/out-of-scope) must not be told it has 'no deterministic safe fix'."""+ bundle_path = self._bundle_file(tmp_path)+ result = FixBundleResult(+ is_valid=False,+ iterations=0,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[_fixable_remaining_item(str(bundle_path))],+ )+ self._patch_command(mocker, result=result)++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "💡 Suggested fix:" in output+ assert "no deterministic safe fix" not in output+ assert "still show a suggested fix" in output++ def test_diff_preview_pending_signatures_uses_conditional_phrasing(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ ) -> None:+ """--diff on a bundle that would converge to valid-but-not-runnable must not assert the on-disk bundle IS valid."""+ bundle_path = self._bundle_file(tmp_path)++ def fake_loop(entry_path: Path, **_kwargs: object) -> FixBundleResult:+ entry_path.write_text('domain = "fix_human_format"\nmain_pipe = "list_ideas"\n', encoding="utf-8")+ return FixBundleResult(+ is_valid=True,+ iterations=1,+ fixes_applied=[_applied_fix(str(entry_path))],+ files_written=[str(entry_path.resolve())],+ remaining_errors=[],+ pending_signatures=["fix_human_format.pending_pipe"],+ is_runnable=False,+ )++ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")+ mocker.patch(f"{FIX_CORE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(side_effect=fake_loop))++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), diff=True)++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "would be valid but still NOT runnable" in output+ assert "fix_human_format.pending_pipe" in output+ assert "Bundle is valid but NOT yet runnable" not in output++ def test_preview_result_remaps_filesystem_error_paths_without_rewriting_semantic_paths(self, tmp_path: Path) -> None:+ """Remaining diagnostics must not retain deleted sandbox paths in structured fields or messages."""+ original_path = (tmp_path / "bundle.mthds").resolve()+ sandbox_path = (tmp_path / "pipelex-fix-preview-test" / "entry" / "bundle.mthds").resolve()+ sandbox = PreviewSandbox(+ entry_path=sandbox_path,+ library_dirs=[],+ writable_library_dirs=[],+ dir_mappings=[],+ entry_mapping=(sandbox_path, original_path),+ )+ filesystem_item = ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ message=f"Validation failed in file '{sandbox_path}'",+ source=str(sandbox_path),+ field_path=str(sandbox_path),+ )+ semantic_item = ValidationErrorItem(+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,+ message="Output declaration is invalid",+ source=str(sandbox_path),+ field_path="pipe → output",+ )+ result = FixBundleResult(+ is_valid=False,+ iterations=0,+ fixes_applied=[],+ remaining_errors=[filesystem_item, semantic_item],+ )++ remapped = _remap_result_to_originals(result, sandbox=sandbox)++ assert remapped.remaining_errors[0].source == str(original_path)+ assert remapped.remaining_errors[0].field_path == str(original_path)+ assert remapped.remaining_errors[0].message == f"Validation failed in file '{original_path}'"+ assert remapped.remaining_errors[1].source == str(original_path)+ assert remapped.remaining_errors[1].field_path == "pipe → output"++ @pytest.mark.usefixtures("console")+ def test_file_not_found_exits_two(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = self._bundle_file(tmp_path)+ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")+ mocker.patch(f"{FIX_CORE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(side_effect=FileNotFoundError("missing")))++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 2+ assert "bundle file not found" in capsys.readouterr().err++ @pytest.mark.usefixtures("console")+ def test_unexpected_exception_exits_two(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = self._bundle_file(tmp_path)+ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")+ mocker.patch(f"{FIX_CORE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(side_effect=RuntimeError("boom")))++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 2+ assert "Failed to fix: boom" in capsys.readouterr().err++ @pytest.mark.usefixtures("console")+ def test_setup_failure_exits_two_and_tears_down(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ bundle_path = self._bundle_file(tmp_path)+ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli", side_effect=RuntimeError("setup exploded"))+ teardown_mock = mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")++ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path))++ assert exc_info.value.exit_code == 2+ assert "Failed to fix: setup exploded" in capsys.readouterr().err+ teardown_mock.assert_called_once_with()++ def test_diff_previews_changes_without_writing_and_labels_would_be(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ console: Console,+ ) -> None:+ """--diff runs the loop against a sandbox copy: the diff and labels name the ORIGINAL path, the original is untouched."""+ bundle_path = self._bundle_file(tmp_path)+ original_content = bundle_path.read_text(encoding="utf-8")++ def fake_loop(entry_path: Path, **_kwargs: object) -> FixBundleResult:+ entry_path.write_text('domain = "fix_human_format"\nmain_pipe = "list_ideas"\n', encoding="utf-8")+ return FixBundleResult(+ is_valid=True,+ iterations=1,+ fixes_applied=[_applied_fix(str(entry_path))],+ files_written=[str(entry_path.resolve())],+ remaining_errors=[],+ pending_signatures=[],+ is_runnable=True,+ )++ mocker.patch(f"{FIX_CORE_MODULE}.make_pipelex_for_cli")+ mocker.patch(f"{FIX_CORE_MODULE}.Pipelex.teardown_if_needed")+ mocker.patch(f"{FIX_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())+ mocker.patch(f"{FIX_CORE_MODULE}.tag")+ mocker.patch(f"{FIX_CORE_MODULE}.fix_bundle_file", new=mocker.AsyncMock(side_effect=fake_loop))++ fix_bundle_cmd(path=str(bundle_path), diff=True)++ assert bundle_path.read_text(encoding="utf-8") == original_content+ output = console.export_text()+ assert "Preview (--diff): no files were written." in output+ assert f"--- {bundle_path.resolve()}" in output+ assert f"+++ {bundle_path.resolve()} (fixed)" in output+ assert '+main_pipe = "list_ideas"' in output+ assert "✅ Fix preview — these fixes would make the bundle valid" in output+ assert "Fixes that would be applied:" in output+ assert "Files that would be written:" in output+ assert f"- {bundle_path.resolve()}" in output+ assert "Files written:" not in output.replace("Files that would be written:", "")++ def test_select_and_ignore_are_mutually_exclusive(self, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(+ path="unused.mthds",+ select_codes_raw=["match-sequence-output"],+ ignore_codes_raw=["strip-namespace"],+ )++ assert exc_info.value.exit_code == 2+ assert "mutually exclusive" in capsys.readouterr().err++ def test_unknown_fix_code_is_rejected_listing_known_codes(self, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path="unused.mthds", select_codes_raw=["typo-rule"])++ assert exc_info.value.exit_code == 2+ err = capsys.readouterr().err+ assert "unknown fix rule code(s): typo-rule" in err+ assert "match-sequence-output" in errdiff --git a/tests/unit/pipelex/cli/commands/test_bundle_path_resolver.py b/tests/unit/pipelex/cli/commands/test_bundle_path_resolver.pynew file mode 100644index 000000000..55545087b--- /dev/null+++ b/tests/unit/pipelex/cli/commands/test_bundle_path_resolver.py@@ -0,0 +1,130 @@+"""Unit tests for the human CLI shared bundle-path resolver.++``pipelex validate bundle`` and ``pipelex fix bundle`` resolve their ``path`` argument through+this one helper — fix must patch exactly the file validate judged — so its semantics are pinned+here once for both commands.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+import typer++from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME+from pipelex.cli.commands.bundle_path_resolver import resolve_bundle_target++if TYPE_CHECKING:+ from pathlib import Path++_HINT = " To fix a bundle, pass a .mthds file or directory: pipelex fix bundle <path>"+++class TestHumanBundlePathResolver:+ def test_mthds_file_is_taken_as_is(self, tmp_path: Path) -> None:+ bundle_file = tmp_path / "my_bundle.mthds"+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")++ bundle_path, library_dir = resolve_bundle_target(str(bundle_file), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert bundle_path == str(bundle_file)+ assert library_dir is None++ def test_tilde_in_path_is_expanded(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HOME", str(tmp_path))+ bundle_file = tmp_path / "my_bundle.mthds"+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")++ bundle_path, _ = resolve_bundle_target("~/my_bundle.mthds", library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert bundle_path == str(bundle_file)++ def test_tilde_in_library_dir_is_expanded(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HOME", str(tmp_path))+ bundle_file = tmp_path / "my_bundle.mthds"+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()++ _, library_dir = resolve_bundle_target(str(bundle_file), library_dir=["~/libs"], command="fix", not_a_bundle_hint=_HINT)++ assert library_dir == [str(libs_dir)]++ def test_directory_with_default_bundle_name_auto_detects_and_injects_dir(self, tmp_path: Path) -> None:+ bundle_file = tmp_path / DEFAULT_BUNDLE_FILE_NAME+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")+ (tmp_path / "sibling.mthds").write_text('domain = "sibling"\n', encoding="utf-8")++ bundle_path, library_dir = resolve_bundle_target(str(tmp_path), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert bundle_path == str(bundle_file)+ assert library_dir == [str(tmp_path)]++ def test_directory_with_single_mthds_falls_back_to_it(self, tmp_path: Path) -> None:+ bundle_file = tmp_path / "only_one.mthds"+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")++ bundle_path, library_dir = resolve_bundle_target(str(tmp_path), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert bundle_path == str(bundle_file)+ assert library_dir == [str(tmp_path)]++ @pytest.mark.parametrize("bundle_name", [DEFAULT_BUNDLE_FILE_NAME, "only_one.mthds"])+ def test_directory_refuses_auto_detected_symlink(self, tmp_path: Path, capsys: pytest.CaptureFixture[str], bundle_name: str) -> None:+ outside_bundle = tmp_path.parent / f"{tmp_path.name}-outside.mthds"+ outside_bundle.write_text('domain = "outside"\n', encoding="utf-8")+ (tmp_path / bundle_name).symlink_to(outside_bundle)++ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert exc_info.value.exit_code == 2+ assert "refusing to auto-detect symlinked bundle" in capsys.readouterr().err++ def test_directory_is_prepended_to_existing_library_dirs_without_duplication(self, tmp_path: Path) -> None:+ bundle_file = tmp_path / DEFAULT_BUNDLE_FILE_NAME+ bundle_file.write_text('domain = "demo"\n', encoding="utf-8")+ other_dir = tmp_path / "libs"+ other_dir.mkdir()++ _, library_dir = resolve_bundle_target(str(tmp_path), library_dir=[str(other_dir)], command="fix", not_a_bundle_hint=_HINT)+ assert library_dir == [str(tmp_path), str(other_dir)]++ _, library_dir_again = resolve_bundle_target(+ str(tmp_path),+ library_dir=[str(tmp_path), str(other_dir)],+ command="fix",+ not_a_bundle_hint=_HINT,+ )+ assert library_dir_again == [str(tmp_path), str(other_dir)]++ def test_empty_directory_exits_2(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert exc_info.value.exit_code == 2+ assert "Failed to fix: no .mthds bundle file found" in capsys.readouterr().err++ def test_ambiguous_directory_exits_2_naming_the_candidates(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ (tmp_path / "b.mthds").write_text('domain = "b"\n', encoding="utf-8")+ (tmp_path / "a.mthds").write_text('domain = "a"\n', encoding="utf-8")++ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert exc_info.value.exit_code == 2+ err = capsys.readouterr().err+ assert "multiple .mthds files found" in err+ assert "(a.mthds, b.mthds)" in err+ assert f"pipelex fix bundle {tmp_path / 'a.mthds'}" in err++ def test_not_a_bundle_path_exits_2_with_command_hint(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ resolve_bundle_target(str(tmp_path / "nope.txt"), library_dir=None, command="fix", not_a_bundle_hint=_HINT)++ assert exc_info.value.exit_code == 2+ err = capsys.readouterr().err+ assert "Failed to fix:" in err+ assert "is not a .mthds file or directory" in err+ assert "pipelex fix bundle <path>" in errdiff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.pyindex 1edaf7409..6a63e217a 100644--- a/tests/unit/pipelex/cli/test_agent_output_drift.py+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py@@ -42,6 +42,7 @@ _NON_PIPELEX_ERROR_KEYS: frozenset[str] = frozenset("PipelineRequestError", # mthds API client package"ArgumentError", # synthetic error_type label"BinaryNotFoundError", # synthetic error_type label+ "FixBundleError", # synthetic error_type label"GraphSpecParseError", # synthetic error_type label"BundleError", # synthetic error_type label"InitConfigError", # synthetic error_type labeldiff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.pyindex 3159d3483..7938b52fd 100644--- a/tests/unit/pipelex/cli/test_error_handlers_more.py+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py@@ -188,8 +188,13 @@ class TestErrorHandlersExtended:assert "Dry Run Error:" in outputassert "dry run exploded" in output- def test_handle_validate_bundle_error_minimal_skips_sections(self, console: Console) -> None:- """With no detail lists and no bundle path, only the banner and tip render."""+ def test_handle_validate_bundle_error_minimal_renders_fallback_residual(self, console: Console) -> None:+ """A message-only error renders the fallback residual item, so the message is never lost.++ The item routing surfaces the shared builder's fallback residual (one blueprint-validation+ item carrying the error message) — previously a parse-level failure showed no detail at all+ in human output.+ """exc = ValidateBundleError(message="validation failed")with pytest.raises(typer.Exit):@@ -198,7 +203,8 @@ class TestErrorHandlersExtended:output = console.export_text()assert "❌ Bundle validation failed" in outputassert "Bundle:" not in output- assert "Blueprint Validation Errors:" not in output+ assert "Blueprint Validation Errors:" in output+ assert "→ validation failed" in outputassert "Pipe Validation Errors:" not in outputassert "Dry Run Error:" not in outputassert "💡 Tip:" in outputdiff --git a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.pynew file mode 100644index 000000000..5a89e106e--- /dev/null+++ b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py@@ -0,0 +1,191 @@+"""Phase-B pins for the ``💡 Suggested fix:`` surfacing in human ``pipelex validate`` output.++``handle_validate_bundle_error`` now routes through the shared ``ValidationErrorItem``s (the+one builder that attaches ``suggested_fix``), so these tests pin: the per-error suggested-fix+line, the actionable ``pipelex fix bundle`` footer (which replaces the generic tip), the+factory-error section (rendered for the first time by the item routing — a deliberate+behavior change), and the dry-run message staying visible alongside categorized errors.+"""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++import pytest+import typer+from rich.console import Console++from pipelex.cli.error_handlers import handle_validate_bundle_error+from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++def _fixable_pipe_error(*, source: str | None = None) -> PipesAndConceptValidationErrorData:+ """An enriched INADEQUATE_OUTPUT_CONCEPT — the fix planner derives ``match-sequence-output`` from it."""+ return PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="demo",+ pipe_code="list_ideas",+ message="output concept mismatch",+ field_path="pipes.list_ideas.output",+ expected_output_ref="Idea[]",+ source=source,+ )+++def _non_fixable_pipe_error() -> PipesAndConceptValidationErrorData:+ """The same error type without the enrichment — structurally suppressed by the planner."""+ return PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="demo",+ pipe_code="other_pipe",+ message="output concept mismatch",+ field_path="pipes.other_pipe.output",+ )+++class TestValidateSuggestedFixRendering:+ @pytest.fixture+ def console(self, mocker: MockerFixture) -> Console:+ """Recorded console patched into the error handlers module."""+ recorded_console = Console(width=200, record=True, color_system=None)+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ return recorded_console++ def test_fixable_error_renders_suggested_fix_line_and_actionable_footer(self, console: Console) -> None:+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="methods/demo.mthds")])++ with pytest.raises(typer.Exit) as exc_info:+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))++ assert exc_info.value.exit_code == 1+ output = console.export_text()+ assert "💡 Suggested fix: Set output of pipe 'list_ideas' to 'Idea[]' to match its last step" in output+ assert "1 of these errors can be fixed automatically" in output+ assert "pipelex fix bundle methods/demo.mthds" in output+ # The actionable footer replaces the generic tip — two stacked 💡 tips would be noise.+ assert "💡 Tip:" not in output++ def test_footer_echoes_library_dirs(self, console: Console) -> None:+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="methods/demo.mthds")])++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(+ exc,+ bundle_path=Path("methods/demo.mthds"),+ library_dirs=[Path("libs"), Path("shared")],+ )++ output = console.export_text()+ assert "pipelex fix bundle methods/demo.mthds -L libs -L shared" in output++ def test_footer_preserves_allow_signatures(self, console: Console) -> None:+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error()])++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(+ exc,+ bundle_path=Path("methods/demo.mthds"),+ allow_signatures=True,+ )++ output = console.export_text()+ assert "pipelex fix bundle methods/demo.mthds --allow-signatures" in output++ def test_footer_shell_quotes_paths_with_spaces(self, console: Console) -> None:+ """A path with a space must stay one argument when the footer command is copy-pasted."""+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="my methods/demo.mthds")])++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(+ exc,+ bundle_path=Path("my methods/demo.mthds"),+ library_dirs=[Path("shared libs")],+ )++ output = console.export_text()+ assert "pipelex fix bundle 'my methods/demo.mthds' -L 'shared libs'" in output++ def test_ambient_source_is_not_advertised_as_applicable(self, console: Console, tmp_path: Path, mocker: MockerFixture) -> None:+ bundle_path = tmp_path / "entry.mthds"+ ambient_dir = tmp_path / "ambient"+ ambient_dir.mkdir()+ ambient_source = ambient_dir / "library.mthds"+ exc = ValidateBundleError(+ message="validation failed",+ pipe_validation_errors=[_fixable_pipe_error(source=str(ambient_source))],+ )+ mocker.patch("pipelex.pipeline.validation_render.resolve_library_dirs", return_value=([ambient_dir], "PIPELEXPATH"))++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc, bundle_path=bundle_path, library_dirs=None)++ output = console.export_text()+ assert "can be fixed automatically" not in output+ assert "pipelex fix bundle" not in output+ assert "💡 Tip:" in output++ def test_non_fixable_errors_keep_generic_tip_and_no_fix_line(self, console: Console) -> None:+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_non_fixable_pipe_error()])++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))++ output = console.export_text()+ assert "💡 Suggested fix:" not in output+ assert "can be fixed automatically" not in output+ assert "💡 Tip:" in output++ def test_fixable_count_sums_only_fixable_items(self, console: Console) -> None:+ exc = ValidateBundleError(+ message="validation failed",+ pipe_validation_errors=[_fixable_pipe_error(), _non_fixable_pipe_error()],+ )++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))++ output = console.export_text()+ assert "1 of these errors can be fixed automatically" in output++ def test_factory_errors_are_now_rendered(self, console: Console) -> None:+ """Pinned behavior change: the raw-list renderer silently skipped factory errors; the item routing shows them."""+ factory_error = PipeFactoryErrorData(+ error_type=PipeFactoryErrorType.UNKNOWN_CONCEPT,+ domain_code="demo",+ pipe_code="say_hi",+ missing_concept_code="MissingConcept",+ declared_concepts=["Idea", "Report"],+ message="concept 'MissingConcept' is not declared in domain 'demo'",+ )+ exc = ValidateBundleError(message="validation failed", pipe_factory_errors=[factory_error])++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))++ output = console.export_text()+ assert "Pipe Factory Errors:" in output+ assert "1. Unknown Concept" in output+ assert "Missing Concept: MissingConcept" in output+ assert "concept 'MissingConcept' is not declared in domain 'demo'" in output+ assert "Declared Concepts: Idea, Report" in output++ def test_dry_run_message_stays_visible_alongside_categorized_errors(self, console: Console) -> None:+ """The wire builder suppresses the dry-run residual when categorized errors exist; the human surface keeps it."""+ exc = ValidateBundleError(+ message="validation failed",+ pipe_validation_errors=[_non_fixable_pipe_error()],+ dry_run_error_message="dry run exploded",+ )++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))++ output = console.export_text()+ assert "Dry Run Error:" in output+ assert "dry run exploded" in outputdiff --git a/tests/unit/pipelex/core/pipes/test_handle_pipe_errors_suffix.py b/tests/unit/pipelex/core/pipes/test_handle_pipe_errors_suffix.pynew file mode 100644index 000000000..f19e1bfd5--- /dev/null+++ b/tests/unit/pipelex/core/pipes/test_handle_pipe_errors_suffix.py@@ -0,0 +1,62 @@+from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType+from pipelex.core.pipes.handle_pipe_errors import categorize_pipe_validation_with_libraries_error+++class TestRequiredProvidedSuffix:+ """The ``(required: …, provided: …)`` suffix the pipe categorizer appends to the message.++ Two rules: it is suppressed entirely for multiplicity errors (identical concept on both sides+ by definition), and for the cases where it stays the required refs render as joined author-syntax+ refs — never a Python ``['x']`` list repr whose brackets masquerade as ``[]`` multiplicity syntax.+ """++ def test_multiplicity_error_suppresses_the_suffix(self) -> None:+ base_message = "output multiplicity mismatch: 'brainstorm' declares 'StoryIdea' but yields 'StoryIdea[]'."+ pipe_error = PipeValidationError(+ message=base_message,+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,+ domain_code="story_studio",+ pipe_code="brainstorm",+ required_concept_codes=["story_studio.StoryIdea"],+ provided_concept_code="story_studio.StoryIdea",+ )++ error_data = categorize_pipe_validation_with_libraries_error(pipe_error)++ # Equality proves no suffix was appended (the base message already speaks author syntax,+ # `StoryIdea` vs `StoryIdea[]`, so its own `[]` is the legitimate multiplicity marker).+ assert error_data.message == base_message+ assert "required:" not in error_data.message+ assert "provided:" not in error_data.message++ def test_concept_error_renders_author_syntax_suffix(self) -> None:+ pipe_error = PipeValidationError(+ message="PipeSequence concept mismatch",+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="recipe_maker",+ pipe_code="make_recipe",+ required_concept_codes=["recipe_maker.Recipe"],+ provided_concept_code="recipe_maker.Draft",+ )++ error_data = categorize_pipe_validation_with_libraries_error(pipe_error)++ assert error_data.message == "PipeSequence concept mismatch (required: recipe_maker.Recipe, provided: recipe_maker.Draft)"+ # No Python list repr leaking through.+ assert "['" not in error_data.message+ assert "']" not in error_data.message++ def test_multiple_required_refs_join_without_brackets(self) -> None:+ pipe_error = PipeValidationError(+ message="PipeCompose input mismatch",+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="doc_shop",+ pipe_code="compose_doc",+ required_concept_codes=["native.Text", "native.Html"],+ provided_concept_code="doc_shop.Draft",+ )++ error_data = categorize_pipe_validation_with_libraries_error(pipe_error)++ assert "(required: native.Text, native.Html, provided: doc_shop.Draft)" in error_data.message+ assert "[" not in error_data.messagediff --git a/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py b/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.pynew file mode 100644index 000000000..15b777dbc--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py@@ -0,0 +1,134 @@+"""Unit tests for the blueprint-channel fix planner — enriched blueprint error data in, fix out.++``plan_fix_for_blueprint_validation_error`` is a pure translation keyed on ``error_type`` ++structured fields. The ``strip-native-concept-redecl`` rule fires only when the enrichment is+present — a ``NATIVE_CONCEPT_REDECLARATION`` error_type plus the offending ``concept_code`` set+by the single ``validate_concept_keys`` raise site — so other blueprint errors are suppressed+structurally. ``DELETE_KEY`` on ``["concept"]`` covers every authoring form (table, inline, dotted+all normalize to a ``concept.<Code>`` key).+"""++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error+from pipelex.suggested_fix import FixOpKind, FixSafety+++def _blueprint_error_data(+ *,+ error_type: PipeValidationErrorType | None = PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION,+ concept_code: str | None = "Text",+ source: str | None = "main.mthds",+) -> PipelexBundleBlueprintValidationErrorData:+ return PipelexBundleBlueprintValidationErrorData(+ error_type=error_type,+ domain_code="nativefix",+ source=source,+ concept_code=concept_code,+ message="Cannot declare a concept named 'Text' because it is natively available in Pipelex.",+ )+++def _strip_namespace_error_data(+ *,+ pipe_code: str | None,+ stripped_pipe_code: str | None,+ source: str | None = "main.mthds",+) -> PipelexBundleBlueprintValidationErrorData:+ return PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,+ domain_code="greetings",+ source=source,+ pipe_code=pipe_code,+ stripped_pipe_code=stripped_pipe_code,+ message="Pipe code 'greetings.hello' is not a valid pipe code. Must be in snake_case.",+ )+++class TestBlueprintFixPlanner:+ def test_native_redeclaration_yields_strip_fix(self) -> None:+ """An enriched native-redeclaration error yields a SAFE delete_key of the concept."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data())+ assert fix is not None+ assert fix.fix_code == "strip-native-concept-redecl"+ assert fix.safety == FixSafety.SAFE+ assert fix.source == "main.mthds"+ assert len(fix.ops) == 1+ the_op = fix.ops[0]+ assert the_op.kind == FixOpKind.DELETE_KEY+ assert the_op.table_path == ["concept"]+ assert the_op.key == "Text"+ assert the_op.value is None+ assert "Text" in fix.description++ def test_fix_carries_the_offending_concept_code(self) -> None:+ """The deleted key is exactly the offending code, whatever it is."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(concept_code="Number"))+ assert fix is not None+ assert fix.ops[0].key == "Number"++ def test_source_is_threaded_onto_the_fix(self) -> None:+ """A blueprint error's ``source`` rides the fix so the loop can target the declaring file."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(source="sibling.mthds"))+ assert fix is not None+ assert fix.source == "sibling.mthds"++ def test_missing_source_still_yields_fix(self) -> None:+ """A single-file validation has no source; the fix still applies (source=None)."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(source=None))+ assert fix is not None+ assert fix.source is None++ def test_missing_concept_code_yields_none(self) -> None:+ """Without the offending code there is no key to delete → no fix."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(concept_code=None))+ assert fix is None++ def test_non_redeclaration_error_type_yields_none(self) -> None:+ """The planner is keyed on error_type: other blueprint errors never produce this fix."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX))+ assert fix is None++ def test_uncategorized_error_type_yields_none(self) -> None:+ """A blueprint error with no error_type (uncategorized residual) yields no fix."""+ fix = plan_fix_for_blueprint_validation_error(_blueprint_error_data(error_type=None))+ assert fix is None++ def test_dotted_declaration_yields_position_preserving_rename(self) -> None:+ """A strippable dotted declaration (pipe_code + stripped) yields a rename_table_key op."""+ error_data = _strip_namespace_error_data(pipe_code="greetings.hello", stripped_pipe_code="hello")+ fix = plan_fix_for_blueprint_validation_error(error_data)+ assert fix is not None+ assert fix.fix_code == "strip-namespace"+ assert fix.safety == FixSafety.SAFE+ assert len(fix.ops) == 1+ op = fix.ops[0]+ assert op.kind == FixOpKind.RENAME_TABLE_KEY+ assert op.table_path == ["pipe"]+ assert op.key == "greetings.hello"+ assert op.new_key == "hello"++ def test_dotted_main_pipe_yields_root_set_key(self) -> None:+ """A strippable main_pipe strip (no pipe_code) yields a set_key of main_pipe at the root."""+ error_data = _strip_namespace_error_data(pipe_code=None, stripped_pipe_code="hello")+ fix = plan_fix_for_blueprint_validation_error(error_data)+ assert fix is not None+ assert fix.fix_code == "strip-namespace"+ assert len(fix.ops) == 1+ op = fix.ops[0]+ assert op.kind == FixOpKind.SET_KEY+ assert op.table_path == []+ assert op.key == "main_pipe"+ assert op.value == "hello"++ def test_unstrippable_syntax_error_yields_none(self) -> None:+ """An INVALID_PIPE_CODE_SYNTAX error without ``stripped_pipe_code`` is not fixable."""+ error_data = _strip_namespace_error_data(pipe_code="Bad-Code", stripped_pipe_code=None)+ assert plan_fix_for_blueprint_validation_error(error_data) is None++ def test_strip_namespace_source_is_threaded(self) -> None:+ """The blueprint error's ``source`` rides the strip-namespace fix."""+ error_data = _strip_namespace_error_data(pipe_code="greetings.hello", stripped_pipe_code="hello", source="sibling.mthds")+ fix = plan_fix_for_blueprint_validation_error(error_data)+ assert fix is not None+ assert fix.source == "sibling.mthds"diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier.pynew file mode 100644index 000000000..05224affd--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier.py@@ -0,0 +1,137 @@+"""Unit tests for the tomlkit fix applier — golden format-preservation tests.++The applier mutates a tomlkit DOM in place (never rebuilds containers), so the comments,+ordering, and table style of untouched content survive by construction; ``serialize_and_format``+then hands the result to the MTHDS formatter for the one canonical style. The golden files are+that canonical output, and the byte-comparison is the regression net for the whole apply → format+pipeline; idempotence and the guarded skip (a missing target path is reported, not raised) are+pinned alongside on the raw DOM.+"""++from pathlib import Path++import pytest+import tomlkit+from pytest_mock import MockerFixture++from pipelex.base_exceptions import PipelexUnexpectedError+from pipelex.pipeline.fixes.applier import FixOpOutcome, apply_fix_ops, serialize_and_format+from pipelex.suggested_fix import FixOp, FixOpKind++_FIXTURE_PATH = Path("tests/data/fixes/sequence_wrong_output.mthds")+_GOLDEN_PATH = Path("tests/data/fixes/sequence_wrong_output.golden.mthds")+++def _dumps(toml_doc: tomlkit.TOMLDocument) -> str:+ """One typed funnel over tomlkit's weakly-typed ``dumps`` (narrow ignore, not file-level)."""+ return tomlkit.dumps(toml_doc) # pyright: ignore[reportUnknownMemberType]+++def _set_output_op(*, pipe_code: str = "list_ideas", value: str = "Idea[]") -> FixOp:+ return FixOp(kind=FixOpKind.SET_KEY, table_path=["pipe", pipe_code], key="output", value=value)+++class TestFixApplier:+ def test_set_key_matches_golden_bytes(self) -> None:+ """Applying the set_key op then formatting yields output byte-equal to the golden file."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ assert serialize_and_format(toml_doc) == _GOLDEN_PATH.read_text(encoding="utf-8")++ def test_apply_twice_is_idempotent(self) -> None:+ """Applying the same op twice yields the same bytes as applying it once."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ apply_fix_ops(toml_doc, ops=[_set_output_op()])+ once = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ assert _dumps(toml_doc) == once++ def test_missing_table_path_is_skipped_not_raised(self) -> None:+ """An op targeting a table absent from the DOM (e.g. a synthetic pipe) is skipped and reported."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ source_bytes = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=[_set_output_op(pipe_code="synthetic_pipe_not_in_file")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ assert applications[0].detail is not None+ assert "pipe" in applications[0].detail+ assert _dumps(toml_doc) == source_bytes++ def test_delete_key_removes_key_preserving_rest(self) -> None:+ """delete_key removes exactly the addressed key; everything else survives byte-for-byte."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ delete_op = FixOp(kind=FixOpKind.DELETE_KEY, table_path=["pipe", "gen_ideas"], key="prompt")+ applications = apply_fix_ops(toml_doc, ops=[delete_op])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ dumped = _dumps(toml_doc)+ assert "Generate ideas about $topic" not in dumped+ assert 'inputs = { topic = "Text" } # inline table style' in dumped+ assert "# The sequence below declares the wrong output on purpose." in dumped++ def test_delete_key_missing_is_skipped(self) -> None:+ """delete_key on an absent key is skipped and reported, not raised."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ delete_op = FixOp(kind=FixOpKind.DELETE_KEY, table_path=["pipe", "gen_ideas"], key="not_a_key")+ applications = apply_fix_ops(toml_doc, ops=[delete_op])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]++ def test_delete_table_on_scalar_leaf_is_skipped(self) -> None:+ """delete_table whose final segment names a scalar (a drifted target) is skipped, not deleted."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ source_bytes = _dumps(toml_doc)+ delete_op = FixOp(kind=FixOpKind.DELETE_TABLE, table_path=["pipe", "gen_ideas", "prompt"])+ applications = apply_fix_ops(toml_doc, ops=[delete_op])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ assert applications[0].detail is not None+ assert _dumps(toml_doc) == source_bytes++ def test_delete_table_removes_whole_table(self) -> None:+ """delete_table removes the addressed table and its keys; sibling tables survive."""+ toml_doc = tomlkit.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))+ delete_op = FixOp(kind=FixOpKind.DELETE_TABLE, table_path=["pipe", "gen_ideas"])+ applications = apply_fix_ops(toml_doc, ops=[delete_op])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ dumped = _dumps(toml_doc)+ assert "[pipe.gen_ideas]" not in dumped+ assert "[pipe.list_ideas]" in dumped++ def test_set_output_on_whole_pipe_inline_table_survives_format(self) -> None:+ """A pipe authored as a single-line inline table is a valid, rarer form. Setting its+ output mutates that nested inline table in place; the format pass must reflow it without+ crashing on the nested inputs table nor corrupting it into multi-line block form.+ """+ source = '[pipe]\nlist_ideas = { type = "PipeSequence", inputs = { topic = "Text" }, output = "Idea" }\n'+ toml_doc = tomlkit.loads(source)+ applications = apply_fix_ops(toml_doc, ops=[_set_output_op()])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ reloaded = tomlkit.loads(serialize_and_format(toml_doc)).unwrap()["pipe"]["list_ideas"]+ assert reloaded["output"] == "Idea[]"+ assert reloaded["inputs"] == {"topic": "Text"}++ def test_serialize_and_format_raises_on_syntax_diagnostic(self, mocker: MockerFixture) -> None:+ """A syntax diagnostic from the formatter means the applier emitted malformed TOML: raise+ loudly (never write it out), keeping the diagnostic's message and position for debugging.+ """+ mocker.patch(+ "pipelex.pipeline.fixes.applier.format_mthds",+ return_value={+ "formatted": "broken",+ "changed": False,+ "diagnostics": [+ {+ "kind": "syntax",+ "severity": "error",+ "message": "expected value",+ "location": None,+ "range": {"start_offset": 0, "end_offset": 1, "start_line": 3, "start_col": 5, "end_line": 3, "end_col": 6},+ }+ ],+ },+ )+ with pytest.raises(PipelexUnexpectedError) as exc_info:+ serialize_and_format(tomlkit.loads("a = 1\n"))+ message = str(exc_info.value)+ assert "malformed TOML" in message+ assert "expected value" in message+ assert "line 3:5" in messagediff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.pynew file mode 100644index 000000000..f4a4d1b46--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py@@ -0,0 +1,126 @@+"""Golden format-preservation tests for the sync-controller-inputs op shapes.++The multi-op diff (set_key updates + adds, delete_key removals) mutates the ``inputs``+table in place, in both its inline and block authoring forms; the no-table case creates+the whole mapping as one inline table (kept attached to its pipe, not a detached block).+Goldens are the MTHDS-formatter canonical bytes: the applier mutates, ``serialize_and_format``+reflows inline-table spacing via ``pipelex_tools.format_mthds`` (the same engine ``plxt``+runs on save), so the fix output is stable under the formatter.+"""++from pathlib import Path++import tomlkit++from pipelex.pipeline.fixes.applier import FixOpOutcome, apply_fix_ops, serialize_and_format+from pipelex.suggested_fix import FixOp, FixOpKind++_FIXES_DIR = Path("tests/data/fixes")+_INPUTS_TABLE_PATH = ["pipe", "make_summary", "inputs"]+++def _dumps(toml_doc: tomlkit.TOMLDocument) -> str:+ """One typed funnel over tomlkit's weakly-typed ``dumps`` (narrow ignore, not file-level)."""+ return tomlkit.dumps(toml_doc) # pyright: ignore[reportUnknownMemberType]+++def _load(name: str) -> tomlkit.TOMLDocument:+ return tomlkit.loads((_FIXES_DIR / f"{name}.mthds").read_text(encoding="utf-8"))+++def _golden(name: str) -> str:+ return (_FIXES_DIR / f"{name}.golden.mthds").read_text(encoding="utf-8")+++_INLINE_OPS = [+ FixOp(kind=FixOpKind.SET_KEY, table_path=_INPUTS_TABLE_PATH, key="text", value="Text"),+ FixOp(kind=FixOpKind.SET_KEY, table_path=_INPUTS_TABLE_PATH, key="style", value="Text"),+ FixOp(kind=FixOpKind.DELETE_KEY, table_path=_INPUTS_TABLE_PATH, key="note"),+]++_BLOCK_OPS = [+ FixOp(kind=FixOpKind.SET_KEY, table_path=_INPUTS_TABLE_PATH, key="text", value="Text"),+ FixOp(kind=FixOpKind.DELETE_KEY, table_path=_INPUTS_TABLE_PATH, key="note"),+]++_MISSING_TABLE_OPS = [+ FixOp(kind=FixOpKind.ENSURE_TABLE, table_path=_INPUTS_TABLE_PATH),+ FixOp(kind=FixOpKind.SET_KEY, table_path=_INPUTS_TABLE_PATH, key="text", value="Text"),+]+++class TestFixApplierInputsSync:+ def test_inline_inputs_diff_matches_golden_bytes(self) -> None:+ """Add + update + delete on an inline inputs table, then format, yields the golden bytes."""+ toml_doc = _load("controller_inputs_inline")+ applications = apply_fix_ops(toml_doc, ops=_INLINE_OPS)+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 3+ assert serialize_and_format(toml_doc) == _golden("controller_inputs_inline")++ def test_block_inputs_diff_matches_golden_bytes(self) -> None:+ """Update + delete on a block [pipe.x.inputs] table preserves surrounding comments."""+ toml_doc = _load("controller_inputs_block")+ applications = apply_fix_ops(toml_doc, ops=_BLOCK_OPS)+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 2+ assert serialize_and_format(toml_doc) == _golden("controller_inputs_block")++ def test_missing_inputs_table_created_as_inline_table(self) -> None:+ """With no inputs declared, one set_key writes the whole mapping as an inline table."""+ toml_doc = _load("controller_inputs_missing_table")+ applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED] * 2+ assert serialize_and_format(toml_doc) == _golden("controller_inputs_missing_table")++ def test_explicit_empty_block_keeps_its_comment(self) -> None:+ """Ensuring an existing empty block mutates it in place instead of replacing it."""+ source = """[pipe.make_summary]+type = "PipeSequence"+output = "Text"++[pipe.make_summary.inputs]+# keep this author note+"""+ toml_doc = tomlkit.loads(source)+ applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)++ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]+ formatted = serialize_and_format(toml_doc)+ assert "# keep this author note" in formatted+ assert 'text = "Text"' in formatted++ def test_inline_diff_applied_twice_is_idempotent(self) -> None:+ """Re-applying the same diff yields the same bytes."""+ toml_doc = _load("controller_inputs_inline")+ apply_fix_ops(toml_doc, ops=_INLINE_OPS)+ once = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=_INLINE_OPS)+ set_outcomes = [application.outcome for application in applications[:2]]+ delete_outcome = applications[2].outcome+ assert set_outcomes == [FixOpOutcome.APPLIED] * 2+ assert delete_outcome == FixOpOutcome.SKIPPED+ assert _dumps(toml_doc) == once++ def test_missing_table_creation_applied_twice_is_idempotent(self) -> None:+ """Re-applying the whole-table set_key yields the same bytes."""+ toml_doc = _load("controller_inputs_missing_table")+ apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)+ once = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=_MISSING_TABLE_OPS)+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]+ assert _dumps(toml_doc) == once++ def test_dotted_input_key_survives_format(self) -> None:+ """A quoted dotted input key (`"cv.name"`, a supported sub-attribute name) stays a flat+ quoted entry through the format pass, not split into a nested table. Deleting an unrelated+ sibling (with a bare ``cv`` root also present) must neither crash nor corrupt the file.+ """+ source = '[pipe.make_summary]\ntype = "PipeSequence"\ninputs = { "cv.name" = "Text", cv = "Curriculum", note = "Text" }\n'+ toml_doc = tomlkit.loads(source)+ applications = apply_fix_ops(toml_doc, ops=[FixOp(kind=FixOpKind.DELETE_KEY, table_path=_INPUTS_TABLE_PATH, key="note")])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ formatted = serialize_and_format(toml_doc)+ assert '"cv.name" = "Text"' in formatted+ assert "note" not in formatted+ # The dotted key stays a flat string entry, not a nested `cv = { name = ... }` table.+ reloaded = tomlkit.loads(formatted).unwrap()+ assert reloaded["pipe"]["make_summary"]["inputs"] == {"cv.name": "Text", "cv": "Curriculum"}diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.pynew file mode 100644index 000000000..13450adda--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py@@ -0,0 +1,100 @@+"""Golden format-preservation tests for the ``strip-native-concept-redecl`` delete op.++One ``DELETE_KEY`` on ``["concept"]`` strips a redeclared native concept across every authoring+form — a ``[concept.X]`` table (with a ``[concept.X.structure]`` sub-table), an ``X = "…"`` string+shorthand under ``[concept]``, and a dotted ``concept.X`` — because tomlkit represents all three as+a ``concept`` table keyed by the code. The goldens are the canonical apply → format output; the+byte-comparison pins that surviving concepts, comments, and pipes are untouched and that deleting a+table also removes its nested structure sub-table.+"""++from pathlib import Path++import pytest+import tomlkit++from pipelex.pipeline.fixes.applier import FixOpOutcome, apply_fix_ops, serialize_and_format+from pipelex.suggested_fix import FixOp, FixOpKind++_DATA = Path("tests/data/fixes")+++def _dumps(toml_doc: tomlkit.TOMLDocument) -> str:+ """One typed funnel over tomlkit's weakly-typed ``dumps`` (narrow ignore, not file-level)."""+ return tomlkit.dumps(toml_doc) # pyright: ignore[reportUnknownMemberType]+++def _delete_concept_op(*, key: str) -> FixOp:+ return FixOp(kind=FixOpKind.DELETE_KEY, table_path=["concept"], key=key)+++class TestFixApplierNativeConcept:+ @pytest.mark.parametrize(+ ("fixture_stem", "concept_code"),+ [+ ("native_redecl_table", "Text"),+ ("native_redecl_inline", "Text"),+ ("native_redecl_dotted", "Number"),+ ],+ )+ def test_strip_matches_golden_bytes(self, fixture_stem: str, concept_code: str) -> None:+ """Deleting the redeclared concept then formatting yields the golden bytes, every form."""+ toml_doc = tomlkit.loads((_DATA / f"{fixture_stem}.mthds").read_text(encoding="utf-8"))+ applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key=concept_code)])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ golden = (_DATA / f"{fixture_stem}.golden.mthds").read_text(encoding="utf-8")+ assert serialize_and_format(toml_doc) == golden++ def test_delete_removes_table_and_its_structure_subtable(self) -> None:+ """Deleting a ``[concept.Text]`` table also drops its ``[concept.Text.structure]`` sub-table."""+ toml_doc = tomlkit.loads((_DATA / "native_redecl_table.mthds").read_text(encoding="utf-8"))+ apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])+ dumped = _dumps(toml_doc)+ assert "[concept.Text]" not in dumped+ assert "structure" not in dumped+ # Sibling concept and its comment survive.+ assert "[concept.Report]" in dumped+ assert "must survive the fix untouched" in dumped++ def test_apply_twice_is_idempotent(self) -> None:+ """Re-applying the delete finds the key already gone — the bytes do not change."""+ toml_doc = tomlkit.loads((_DATA / "native_redecl_inline.mthds").read_text(encoding="utf-8"))+ apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])+ once = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ assert _dumps(toml_doc) == once++ def test_leading_comment_on_deleted_table_reflows_onto_successor(self) -> None:+ """Known artifact (pinned): a standalone comment sitting directly above a deleted+ ``[concept.X]`` table reflows onto the next element (tomlkit trivia behavior;+ ``format_mthds`` does not reposition it). The guarantee is that comments on *untouched*+ content survive — a comment sitting on the deleted concept is the only thing that can+ dangle. Pinned so the behavior is explicit rather than a silent surprise; see+ ``wip/autofix/deferred-checkpoint-b-review-items.md``.+ """+ source = (+ "[concept.Report]\n"+ 'description = "A report."\n'+ "\n"+ "# describes the redeclared concept below\n"+ "[concept.Text]\n"+ 'description = "Redeclared native Text."\n'+ "\n"+ "[pipe.make_report]\n"+ 'type = "PipeLLM"\n'+ )+ toml_doc = tomlkit.loads(source)+ apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Text")])+ dumped = _dumps(toml_doc)+ assert "[concept.Text]" not in dumped+ # The comment reflowed onto the successor table — it no longer annotates the deleted concept.+ assert "# describes the redeclared concept below\n[pipe.make_report]" in dumped++ def test_delete_missing_concept_is_skipped(self) -> None:+ """Stripping a concept absent from the document is reported as skipped, not raised."""+ toml_doc = tomlkit.loads((_DATA / "native_redecl_inline.mthds").read_text(encoding="utf-8"))+ source_bytes = _dumps(toml_doc)+ applications = apply_fix_ops(toml_doc, ops=[_delete_concept_op(key="Number")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ assert _dumps(toml_doc) == source_bytesdiff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.pynew file mode 100644index 000000000..866954c28--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py@@ -0,0 +1,212 @@+"""Golden format-preservation tests for the ``strip-namespace`` rename op.++``RENAME_TABLE_KEY`` on ``["pipe"]`` renames a same-domain over-qualified declaration key to its+bare form *in place* — via tomlkit's position-preserving ``Container._replace`` — so the pipe keeps+its position among siblings and its comments (a ``del`` + re-add would send it to the bottom). Paired+with a root ``SET_KEY`` that strips ``main_pipe``, the golden byte-comparison pins that surrounding+pipes, comments, and the qualified step reference (which still resolves) are untouched. Collision and+idempotence are guarded skips, never raises.+"""++from pathlib import Path+from typing import Any, cast++import tomlkit++from pipelex.pipeline.fixes.applier import FixOpOutcome, apply_fix_ops, serialize_and_format+from pipelex.suggested_fix import FixOp, FixOpKind++_DATA = Path("tests/data/fixes")+++def _dumps(toml_doc: tomlkit.TOMLDocument) -> str:+ """One typed funnel over tomlkit's weakly-typed ``dumps`` (narrow ignore, not file-level)."""+ return tomlkit.dumps(toml_doc) # pyright: ignore[reportUnknownMemberType]+++def _rename_op(*, key: str, new_key: str) -> FixOp:+ return FixOp(kind=FixOpKind.RENAME_TABLE_KEY, table_path=["pipe"], key=key, new_key=new_key)+++def _strip_main_pipe_op(*, value: str) -> FixOp:+ return FixOp(kind=FixOpKind.SET_KEY, table_path=[], key="main_pipe", value=value)+++_STRIP_OPS = [+ _rename_op(key="namespacefix.hello", new_key="hello"),+ _strip_main_pipe_op(value="run_seq"),+]++_COLLISION_MTHDS = """domain = "coll"+main_pipe = "hello"++[pipe.hello]+type = "PipeLLM"+description = "Bare hello."+output = "Text"+prompt = "Bare"++[pipe."coll.hello"]+type = "PipeLLM"+description = "Dotted hello."+output = "Text"+prompt = "Dotted"+"""++# ``[pipe.*]`` sections interleaved with a ``[concept.*]`` section (a legal, common layout:+# concepts declared next to the pipes that use them) — tomlkit resolves ``doc["pipe"]`` to an+# ``OutOfOrderTableProxy`` instead of a ``Table``.+_INTERLEAVED_MTHDS = """domain = "inter"++[pipe."inter.hello"]+type = "PipeLLM"+description = "Dotted hello."+output = "Text"+prompt = "Dotted"++[concept.Greeting]+description = "A greeting."++[pipe.other]+type = "PipeLLM"+description = "Other."+output = "Text"+prompt = "Other"+"""++# The offending pipe's header ``[pipe."inter.hello"]`` and its own block ``.inputs`` sub-table land+# in *different* out-of-order chunks (split by the intervening ``[concept.*]``), so the dotted key+# ``inter.hello`` appears in TWO of the proxy's underlying sub-tables — the shape the first-match+# rename used to orphan.+_INTERLEAVED_NESTED_MTHDS = """domain = "inter"++[pipe."inter.hello"]+type = "PipeLLM"+description = "Dotted hello."+output = "Text"+prompt = "Ask about $doc."++[concept.Greeting]+description = "A greeting."++[pipe."inter.hello".inputs]+doc = "Text"++[pipe.other]+type = "PipeLLM"+description = "Other."+output = "Text"+prompt = "Other"+"""++# The whole ``pipe`` section as one inline table — tomlkit resolves ``doc["pipe"]`` to an+# ``InlineTable`` instead of a ``Table``.+_INLINE_MTHDS = """domain = "inl"+pipe = { "inl.hello" = { type = "PipeLLM", description = "Dotted.", output = "Text", prompt = "Dotted" } }+"""+++class TestFixApplierStripNamespace:+ def test_strip_matches_golden_bytes(self) -> None:+ """Renaming the dotted declaration + stripping main_pipe, then formatting, yields the golden."""+ toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))+ applications = apply_fix_ops(toml_doc, ops=_STRIP_OPS)+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED, FixOpOutcome.APPLIED]+ golden = (_DATA / "strip_namespace_rename.golden.mthds").read_text(encoding="utf-8")+ assert serialize_and_format(toml_doc) == golden++ def test_rename_preserves_position_and_comments(self) -> None:+ """The renamed pipe stays between its siblings, keeping its leading and trailing comments."""+ toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))+ apply_fix_ops(toml_doc, ops=_STRIP_OPS)+ dumped = _dumps(toml_doc)+ assert '[pipe."namespacefix.hello"]' not in dumped+ assert "[pipe.hello]" in dumped+ # Position: renamed pipe is still between first_pipe and run_seq.+ assert dumped.index("[pipe.first_pipe]") < dumped.index("[pipe.hello]") < dumped.index("[pipe.run_seq]")+ # Comments survive (leading standalone + trailing inline).+ assert "over-qualified with its own domain prefix" in dumped+ assert "trailing comment stays on this line" in dumped+ # The qualified step reference is left untouched (it still resolves to the bare pipe).+ assert 'pipe = "namespacefix.hello"' in dumped++ def test_apply_twice_is_idempotent(self) -> None:+ """Re-applying finds the dotted key already renamed / main_pipe already stripped — bytes hold."""+ toml_doc = tomlkit.loads((_DATA / "strip_namespace_rename.mthds").read_text(encoding="utf-8"))+ apply_fix_ops(toml_doc, ops=_STRIP_OPS)+ once = serialize_and_format(toml_doc)+ second = apply_fix_ops(toml_doc, ops=_STRIP_OPS)+ assert [application.outcome for application in second] == [FixOpOutcome.SKIPPED, FixOpOutcome.APPLIED]+ assert serialize_and_format(toml_doc) == once++ def test_rename_skips_on_collision(self) -> None:+ """Renaming to a key already declared separately is skipped, not applied (no clobber)."""+ toml_doc = tomlkit.loads(_COLLISION_MTHDS)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="coll.hello", new_key="hello")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ dumped = _dumps(toml_doc)+ # Both declarations survive untouched — nothing was clobbered.+ assert '[pipe."coll.hello"]' in dumped+ assert "[pipe.hello]" in dumped++ def test_rename_skips_when_key_absent(self) -> None:+ """A rename whose source key is not present is a guarded skip (e.g. a stale op)."""+ toml_doc = tomlkit.loads(_COLLISION_MTHDS)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="coll.ghost", new_key="ghost")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]++ def test_rename_applies_on_interleaved_pipe_sections(self) -> None:+ """Interleaved ``[pipe.*]``/``[concept.*]`` sections (an ``OutOfOrderTableProxy``) rename in place."""+ toml_doc = tomlkit.loads(_INTERLEAVED_MTHDS)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ dumped = _dumps(toml_doc)+ assert '[pipe."inter.hello"]' not in dumped+ assert "[pipe.hello]" in dumped+ # Position: the renamed pipe stays before the concept section, which stays before [pipe.other].+ assert dumped.index("[pipe.hello]") < dumped.index("[concept.Greeting]") < dumped.index("[pipe.other]")+ # The whole document still formats cleanly (no malformed TOML out of the proxy rename).+ assert "[pipe.hello]" in serialize_and_format(toml_doc)++ def test_rename_skips_on_collision_across_interleaved_sections(self) -> None:+ """A collision with a bare key living in a *different* ``[pipe.*]`` section is still a skip."""+ interleaved_collision = _INTERLEAVED_MTHDS.replace("[pipe.other]", "[pipe.hello]")+ toml_doc = tomlkit.loads(interleaved_collision)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])+ assert [application.outcome for application in applications] == [FixOpOutcome.SKIPPED]+ dumped = _dumps(toml_doc)+ assert '[pipe."inter.hello"]' in dumped++ def test_rename_carries_nested_subtable_across_interleaved_chunks(self) -> None:+ """A dotted pipe whose header and block ``.inputs`` land in *different* out-of-order chunks+ renames in both — the pipe keeps its nested content and no phantom dotted key survives.++ Regression: the first-match rename renamed only the header chunk, orphaning the ``.inputs``+ sub-table under the still-invalid ``inter.hello`` key while reporting the op as APPLIED.+ """+ toml_doc = tomlkit.loads(_INTERLEAVED_NESTED_MTHDS)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inter.hello", new_key="hello")])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ # Pre-format dump: the dotted key is gone everywhere and BOTH the header and the nested+ # sub-table now sit under the bare name.+ dumped = _dumps(toml_doc)+ assert '"inter.hello"' not in dumped+ assert "[pipe.hello]" in dumped+ assert "[pipe.hello.inputs]" in dumped+ # Semantic check on the re-parsed, formatted output: the renamed pipe kept its header fields+ # and its inputs, under exactly the two bare keys.+ pipe_section = cast("dict[str, Any]", tomlkit.loads(serialize_and_format(toml_doc))["pipe"])+ assert "inter.hello" not in pipe_section+ assert set(pipe_section.keys()) == {"hello", "other"}+ assert pipe_section["hello"]["description"] == "Dotted hello."+ assert pipe_section["hello"]["inputs"]["doc"] == "Text"++ def test_rename_applies_on_inline_pipe_table(self) -> None:+ """An inline ``pipe = {...}`` section (an ``InlineTable``) renames in place."""+ toml_doc = tomlkit.loads(_INLINE_MTHDS)+ applications = apply_fix_ops(toml_doc, ops=[_rename_op(key="inl.hello", new_key="hello")])+ assert [application.outcome for application in applications] == [FixOpOutcome.APPLIED]+ dumped = _dumps(toml_doc)+ assert '"inl.hello"' not in dumped+ assert "hello" in dumped+ assert "hello" in serialize_and_format(toml_doc)diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_file_transaction.py b/tests/unit/pipelex/pipeline/fixes/test_fix_file_transaction.pynew file mode 100644index 000000000..3cdef5b87--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_file_transaction.py@@ -0,0 +1,166 @@+"""Regression tests for autofix's optimistic, atomic file commit."""++from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.pipeline.exceptions import FixTransactionError, FixWriteConflictError+from pipelex.pipeline.fixes.fix_loop import (+ _assert_snapshot_unchanged, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+ _bind_fixes_to_snapshots, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+ _commit_file_updates, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+ _FileSnapshot, # pyright: ignore[reportPrivateUsage]+ _PendingFileUpdate, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+ _read_file_snapshot, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+ _snapshot_loaded_sources, # pyright: ignore[reportPrivateUsage] # noqa: PLC2701+)+from pipelex.suggested_fix import FixSafety, SuggestedFix+++class TestFixFileTransaction:+ def test_symlink_retarget_during_validation_is_rejected(self, tmp_path: Path) -> None:+ first_target = tmp_path / "first.mthds"+ second_target = tmp_path / "second.mthds"+ first_target.write_text("first\n", encoding="utf-8")+ second_target.write_text("second\n", encoding="utf-8")+ source_link = tmp_path / "library.mthds"+ source_link.symlink_to(first_target)+ snapshots = _snapshot_loaded_sources(entry_source_path=source_link, effective_dirs=[])+ fix = SuggestedFix(fix_code="test", description="test", safety=FixSafety.SAFE, source=str(source_link), ops=[])+ source_link.unlink()+ source_link.symlink_to(second_target)++ with pytest.raises(FixWriteConflictError, match="retargeted"):+ _bind_fixes_to_snapshots([fix], entry_source_path=source_link, snapshots_by_source=snapshots)++ def test_concurrent_edit_is_not_overwritten(self, tmp_path: Path) -> None:+ target = tmp_path / "bundle.mthds"+ target.write_text("original\n", encoding="utf-8")+ snapshot = _read_file_snapshot(target)+ target.write_text("user edit\n", encoding="utf-8")++ with pytest.raises(FixWriteConflictError, match="file changed"):+ _commit_file_updates([_PendingFileUpdate(snapshot=snapshot, new_content="fixed\n")])++ assert target.read_text(encoding="utf-8") == "user edit\n"+ assert list(tmp_path.glob(".*.pipelex-fix-*.tmp")) == []++ def test_failed_atomic_replace_preserves_original(self, tmp_path: Path, mocker: MockerFixture) -> None:+ target = tmp_path / "bundle.mthds"+ target.write_text("original\n", encoding="utf-8")+ snapshot = _read_file_snapshot(target)+ mocker.patch.object(Path, "replace", side_effect=OSError("replace failed"))++ with pytest.raises(OSError, match="replace failed"):+ _commit_file_updates([_PendingFileUpdate(snapshot=snapshot, new_content="fixed\n")])++ assert target.read_text(encoding="utf-8") == "original\n"+ assert list(tmp_path.glob(".*.pipelex-fix-*.tmp")) == []++ def test_multi_file_replace_failure_rolls_back_prior_targets(self, tmp_path: Path, mocker: MockerFixture) -> None:+ first_path = tmp_path / "first.mthds"+ second_path = tmp_path / "second.mthds"+ third_path = tmp_path / "third.mthds"+ first_path.write_text("first original\n", encoding="utf-8")+ second_path.write_text("second original\n", encoding="utf-8")+ third_path.write_text("third original\n", encoding="utf-8")+ updates = [+ _PendingFileUpdate(snapshot=_read_file_snapshot(first_path), new_content="first fixed\n"),+ _PendingFileUpdate(snapshot=_read_file_snapshot(second_path), new_content="second fixed\n"),+ _PendingFileUpdate(snapshot=_read_file_snapshot(third_path), new_content="third fixed\n"),+ ]+ original_replace = Path.replace+ replacement_count = 0+ rollback_targets: list[str] = []++ def fail_third_replacement(source_path: Path, target_path: Path) -> Path:+ nonlocal replacement_count+ if ".pipelex-fix-new." in source_path.name:+ replacement_count += 1+ if replacement_count == 3:+ msg = "third replace failed"+ raise OSError(msg)+ elif ".pipelex-fix-rollback." in source_path.name:+ rollback_targets.append(target_path.name)+ return original_replace(source_path, target_path)++ mocker.patch.object(Path, "replace", new=fail_third_replacement)++ with pytest.raises(OSError, match="third replace failed"):+ _commit_file_updates(updates)++ assert first_path.read_text(encoding="utf-8") == "first original\n"+ assert second_path.read_text(encoding="utf-8") == "second original\n"+ assert third_path.read_text(encoding="utf-8") == "third original\n"+ assert rollback_targets == ["second.mthds", "first.mthds"]+ assert list(tmp_path.glob(".*.pipelex-fix-*.tmp")) == []++ def test_rollback_does_not_overwrite_edit_after_prior_commit(self, tmp_path: Path, mocker: MockerFixture) -> None:+ first_path = tmp_path / "first.mthds"+ second_path = tmp_path / "second.mthds"+ third_path = tmp_path / "third.mthds"+ first_path.write_text("first original\n", encoding="utf-8")+ second_path.write_text("second original\n", encoding="utf-8")+ third_path.write_text("third original\n", encoding="utf-8")+ updates = [+ _PendingFileUpdate(snapshot=_read_file_snapshot(first_path), new_content="first fixed\n"),+ _PendingFileUpdate(snapshot=_read_file_snapshot(second_path), new_content="second fixed\n"),+ _PendingFileUpdate(snapshot=_read_file_snapshot(third_path), new_content="third fixed\n"),+ ]+ assertion_count = 0++ def inject_edit_before_third_commit(snapshot: _FileSnapshot) -> None:+ nonlocal assertion_count+ assertion_count += 1+ if assertion_count == 3:+ second_path.write_text("concurrent user edit\n", encoding="utf-8")+ msg = "injected third-file conflict"+ raise FixWriteConflictError(msg)+ _assert_snapshot_unchanged(snapshot)++ mocker.patch("pipelex.pipeline.fixes.fix_loop._assert_snapshot_unchanged", new=inject_edit_before_third_commit)++ with pytest.raises(FixTransactionError, match="rollback was incomplete") as exc_info:+ _commit_file_updates(updates)++ assert first_path.read_text(encoding="utf-8") == "first original\n"+ assert second_path.read_text(encoding="utf-8") == "concurrent user edit\n"+ assert third_path.read_text(encoding="utf-8") == "third original\n"+ assert str(second_path) in str(exc_info.value)+ assert "inspect the named files before retrying" in str(exc_info.value)+ assert list(tmp_path.glob(".*.pipelex-fix-*.tmp")) == []++ def test_cleanup_failure_reports_committed_outcome(self, tmp_path: Path, mocker: MockerFixture) -> None:+ target = tmp_path / "bundle.mthds"+ target.write_text("original\n", encoding="utf-8")+ snapshot = _read_file_snapshot(target)+ original_unlink = Path.unlink++ def fail_temp_cleanup(path: Path, *, missing_ok: bool = False) -> None:+ if ".pipelex-fix-rollback." in path.name:+ msg = "cleanup failed"+ raise OSError(msg)+ original_unlink(path, missing_ok=missing_ok)++ mocker.patch.object(Path, "unlink", new=fail_temp_cleanup)++ with pytest.raises(FixTransactionError, match=r"target changes were committed.*cleanup failed"):+ _commit_file_updates([_PendingFileUpdate(snapshot=snapshot, new_content="fixed\n")])++ assert target.read_text(encoding="utf-8") == "fixed\n"++ def test_cleanup_failure_does_not_mask_commit_failure(self, tmp_path: Path, mocker: MockerFixture) -> None:+ target = tmp_path / "bundle.mthds"+ target.write_text("original\n", encoding="utf-8")+ snapshot = _read_file_snapshot(target)++ mocker.patch.object(Path, "replace", side_effect=OSError("primary replace failure"))+ mocker.patch.object(Path, "unlink", side_effect=OSError("secondary cleanup failure"))++ with pytest.raises(OSError, match="primary replace failure") as exc_info:+ _commit_file_updates([_PendingFileUpdate(snapshot=snapshot, new_content="fixed\n")])++ assert target.read_text(encoding="utf-8") == "original\n"+ assert len(exc_info.value.__notes__) == 1+ assert "secondary cleanup failure" in exc_info.value.__notes__[0]diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.pynew file mode 100644index 000000000..a5da92f1e--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py@@ -0,0 +1,78 @@+"""Unit test for the convergence loop's no-progress bail — it exits loudly, never spins.++The validator is stubbed to keep raising the same enriched error whose fix op targets a+pipe table absent from the file (the synthetic-pipe case): the applier skips the op, the+next iteration proposes the same fix fingerprint, and the loop bails with the reason+reported instead of burning through max_iterations.+"""++from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.fixes.fix_loop import fix_bundle_file++_MINIMAL_MTHDS = """domain = "seqfix_bail"+main_pipe = "declared_pipe"++[pipe.declared_pipe]+type = "PipeLLM"+description = "A pipe that exists in the file."+inputs = { topic = "Text" }+output = "Text"+prompt = "Write about $topic"+"""+++def _synthetic_pipe_error() -> ValidateBundleError:+ """An enriched output-mismatch error on a pipe with no TOML table in the file."""+ return ValidateBundleError(+ message="Pipe validation failed",+ pipe_validation_errors=[+ PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,+ domain_code="seqfix_bail",+ pipe_code="synthetic_pipe_not_in_file",+ message="output mismatch",+ field_path="",+ expected_output_ref="Text[]",+ ),+ ],+ )++[email protected](loop_scope="class")+class TestFixLoopBail:+ async def test_repeated_fingerprint_bails_loudly(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """The same fix fingerprint proposed twice ends the loop with a reported bail reason."""+ bundle_path = tmp_path / "bail.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ validate_mock = mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=_synthetic_pipe_error(),+ )++ result = await fix_bundle_file(bundle_path, max_iterations=5)++ assert result.is_valid is False+ assert result.bail_reason is not None+ # The bail reason states the no-progress stop in author terms (naming the re-proposed+ # fix's description), never leaking the internal fingerprint string.+ assert result.bail_reason.startswith("no progress:")+ assert "fingerprint" not in result.bail_reason+ # One apply round happened (all ops skipped), then the repeat was detected: the loop+ # validated twice, not five times.+ assert result.iterations == 1+ assert result.fixes_applied == []+ assert validate_mock.await_count == 2+ assert [item.error_type for item in result.remaining_errors] == [PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY]+ # The file was never touched: the op's target table does not exist.+ assert bundle_path.read_text(encoding="utf-8") == _MINIMAL_MTHDSdiff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.pynew file mode 100644index 000000000..148b96bb1--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py@@ -0,0 +1,482 @@+"""Unit pins for the fix loop's multi-file scoping: the resolved-dirs single-file gate (D3.2),+the write-scope policy (D3.3), and per-file fix grouping (D3.4).++``validate_bundle`` — and, for the ambient-resolution cases, ``resolve_library_dirs`` — are+patched at the loop's namespace so each case pins exactly one scoping decision: which files the+loop is willing to patch, and where a fix actually lands. The rules under test:++- Single-file is derived from the RESOLVED dirs: an explicit ``[]`` is genuinely single-file+ (source-less fixes apply); a ``None`` that falls through to ambient dirs is multi-file+ (source-less fixes conservatively dropped).+- Write scope is the entry file plus per-call ``library_dirs`` only; files loaded via ambient+ resolution are read-only, and a run whose every fix targets a read-only file bails loudly.+"""++from pathlib import Path++import pytest+import tomlkit+from pytest_mock import MockerFixture++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.fixes.fix_loop import fix_bundle_file++_MINIMAL_MTHDS = """domain = "seqfix_scoping"+main_pipe = "list_ideas"++[pipe.list_ideas]+type = "PipeLLM"+description = "A pipe whose code could collide with a same-named pipe in another domain."+inputs = { topic = "Text" }+output = "Text"+prompt = "Write about $topic"+"""++_NATIVE_REDECL_MTHDS = """domain = "nativefix_scoping"+main_pipe = "greet"++[concept.Text]+description = "Redeclared native Text."++[pipe.greet]+type = "PipeLLM"+description = "Greet."+inputs = { name = "Text" }+output = "Text"+prompt = "Greet $name"+"""++_SIBLING_MTHDS = """domain = "seqfix_scoping_sibling"++[pipe.sibling_pipe]+type = "PipeLLM"+description = "A sibling pipe with its own output mismatch."+inputs = { topic = "Text" }+output = "Text"+prompt = "Write about $topic"+"""++_DOTTED_SHARED_A_MTHDS = """domain = "rebuild_a"++[pipe."rebuild_a.shared"]+type = "PipeLLM"+description = "A dotted declaration that strips to a bare shared code."+inputs = { topic = "Text" }+output = "Text"+prompt = "Write about $topic"+"""++_DOTTED_SHARED_B_MTHDS = """domain = "rebuild_b"++[pipe."rebuild_b.shared"]+type = "PipeLLM"+description = "Another dotted declaration that strips to the same bare shared code."+inputs = { topic = "Text" }+output = "Text"+prompt = "Write about $topic"+"""+++def _seq_output_error_data(*, pipe_code: str, source: str | None) -> PipesAndConceptValidationErrorData:+ """One enriched output-mismatch error datum — plans a ``match-sequence-output`` fix."""+ return PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="seqfix_scoping",+ source=source,+ pipe_code=pipe_code,+ message=f"pipe '{pipe_code}' output mismatch",+ field_path=source or "",+ expected_output_ref="Idea[]",+ )+++def _seq_output_error(*, pipe_code: str, source: str | None) -> ValidateBundleError:+ return ValidateBundleError(+ message="Pipe validation failed",+ pipe_validation_errors=[_seq_output_error_data(pipe_code=pipe_code, source=source)],+ )+++def _strip_namespace_error(*, pipe_code: str, stripped_pipe_code: str, source: str) -> ValidateBundleError:+ return ValidateBundleError(+ message="Blueprint validation failed",+ pipelex_bundle_blueprint_validation_errors=[+ PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,+ source=source,+ pipe_code=pipe_code,+ stripped_pipe_code=stripped_pipe_code,+ message=f"Pipe code '{pipe_code}' should be '{stripped_pipe_code}'",+ ),+ ],+ )++[email protected](loop_scope="class")+class TestFixLoopMultiFileScoping:+ async def test_sourceless_fix_not_applied_under_library_dirs(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """With explicit library_dirs, a source-less fix is dropped: the file must not be touched."""+ bundle_path = tmp_path / "scoping.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ library_dir = tmp_path / "library"+ library_dir.mkdir()+ validate_mock = mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=_seq_output_error(pipe_code="list_ideas", source=None),+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[library_dir], max_iterations=3)++ assert result.is_valid is False+ assert result.iterations == 0+ assert result.fixes_applied == []+ assert result.files_written == []+ assert validate_mock.await_count == 1+ assert [item.error_type for item in result.remaining_errors] == [PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT]+ # The pipe table [pipe.list_ideas] DOES exist in this file — without the scoping+ # guard the applier would have patched it. The file must be byte-identical.+ assert bundle_path.read_text(encoding="utf-8") == _MINIMAL_MTHDS++ async def test_explicit_empty_library_dirs_is_single_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``library_dirs=[]`` resolves to no dirs — genuinely single-file, so a source-less fix applies."""+ bundle_path = tmp_path / "scoping.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_seq_output_error(pipe_code="list_ideas", source=None), None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[], max_iterations=3)++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve()]+ fixed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert fixed["pipe"]["list_ideas"]["output"] == "Idea[]"++ async def test_none_falling_through_to_ambient_dirs_is_multi_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``library_dirs=None`` resolving to ambient dirs is multi-file: a source-less fix is dropped."""+ bundle_path = tmp_path / "scoping.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ ambient_dir = tmp_path / "ambient"+ ambient_dir.mkdir()+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.resolve_library_dirs",+ return_value=([ambient_dir], "instance default"),+ )+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=_seq_output_error(pipe_code="list_ideas", source=None),+ )++ result = await fix_bundle_file(bundle_path, library_dirs=None, max_iterations=3)++ assert result.is_valid is False+ assert result.fixes_applied == []+ assert result.files_written == []+ assert bundle_path.read_text(encoding="utf-8") == _MINIMAL_MTHDS++ async def test_none_resolving_to_nothing_is_single_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``library_dirs=None`` with nothing configured anywhere resolves single-file: fixes apply."""+ bundle_path = tmp_path / "scoping.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.resolve_library_dirs",+ return_value=([], "none configured"),+ )+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_seq_output_error(pipe_code="list_ideas", source=None), None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=None, max_iterations=3)++ assert result.is_valid is True+ assert result.iterations == 1+ fixed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert fixed["pipe"]["list_ideas"]["output"] == "Idea[]"++ async def test_sourceful_blueprint_fix_applies_under_library_dirs(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """A fix whose ``source`` equals the file being fixed IS applied under library_dirs."""+ bundle_path = tmp_path / "native_redecl.mthds"+ bundle_path.write_text(_NATIVE_REDECL_MTHDS, encoding="utf-8")+ library_dir = tmp_path / "library"+ library_dir.mkdir()+ redeclaration_error = ValidateBundleError(+ message="Blueprint validation failed",+ pipelex_bundle_blueprint_validation_errors=[+ PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION,+ domain_code="nativefix_scoping",+ source=str(bundle_path),+ concept_code="Text",+ message="Cannot declare a concept named 'Text' because it is natively available in Pipelex.",+ ),+ ],+ )+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[redeclaration_error, None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[library_dir], max_iterations=3)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-native-concept-redecl"]+ # The redeclared concept is gone from the declaring file.+ assert "[concept.Text]" not in bundle_path.read_text(encoding="utf-8")++ async def test_sourced_fix_under_explicit_library_dir_writes_the_sibling(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """A fix sourced at a sibling under a per-call ``-L`` dir patches the sibling, not the entry."""+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_SIBLING_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_seq_output_error(pipe_code="sibling_pipe", source=str(sibling_path)), None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir], max_iterations=3)++ assert result.is_valid is True+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert [Path(written) for written in result.files_written] == [sibling_path.resolve()]+ fixed_sibling = tomlkit.loads(sibling_path.read_text(encoding="utf-8")).unwrap()+ assert fixed_sibling["pipe"]["sibling_pipe"]["output"] == "Idea[]"+ assert bundle_path.read_text(encoding="utf-8") == _MINIMAL_MTHDS++ async def test_fix_sourced_at_ambient_file_bails_out_of_scope(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """A fix sourced at a file loaded via ambient resolution is read-only: loud bail, no write.++ The user did not pass that directory to THIS command, so the loop must not write there —+ and the outcome must be actionable, naming the out-of-scope file and the -L remedy.+ """+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ ambient_dir = tmp_path / "ambient"+ ambient_dir.mkdir()+ ambient_sibling = ambient_dir / "ambient_sibling.mthds"+ ambient_sibling.write_text(_SIBLING_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.resolve_library_dirs",+ return_value=([ambient_dir], "instance default"),+ )+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=_seq_output_error(pipe_code="sibling_pipe", source=str(ambient_sibling)),+ )++ result = await fix_bundle_file(bundle_path, library_dirs=None, max_iterations=3)++ assert result.is_valid is False+ assert result.fixes_applied == []+ assert result.files_written == []+ assert result.bail_reason is not None+ assert "outside write scope" in result.bail_reason+ assert str(ambient_sibling.resolve()) in result.bail_reason+ assert "-L" in result.bail_reason+ assert ambient_sibling.read_text(encoding="utf-8") == _SIBLING_MTHDS+ # The remaining errors still carry the suggested fix (with its source) for the consumer.+ assert result.remaining_errors+ assert result.remaining_errors[0].suggested_fix is not None+ assert result.remaining_errors[0].suggested_fix.source == str(ambient_sibling)++ async def test_entry_file_sourced_fix_is_always_writable(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """A fix sourced at the entry file itself applies even when it was loaded via ambient dirs."""+ ambient_dir = tmp_path / "ambient"+ ambient_dir.mkdir()+ bundle_path = ambient_dir / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.resolve_library_dirs",+ return_value=([ambient_dir], "instance default"),+ )+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_seq_output_error(pipe_code="list_ideas", source=str(bundle_path)), None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=None, max_iterations=3)++ assert result.is_valid is True+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve()]+ fixed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert fixed["pipe"]["list_ideas"]["output"] == "Idea[]"++ async def test_mixed_scope_applies_in_scope_and_reports_out_of_scope(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """In-scope fixes proceed even when other fixes target read-only files (no all-or-nothing)."""+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ ambient_dir = tmp_path / "ambient"+ ambient_dir.mkdir()+ ambient_sibling = ambient_dir / "ambient_sibling.mthds"+ ambient_sibling.write_text(_SIBLING_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.resolve_library_dirs",+ return_value=([ambient_dir], "instance default"),+ )+ entry_error = _seq_output_error_data(pipe_code="list_ideas", source=str(bundle_path))+ ambient_error = _seq_output_error_data(pipe_code="sibling_pipe", source=str(ambient_sibling))+ both_errors = ValidateBundleError(message="bundle invalid", pipe_validation_errors=[entry_error, ambient_error])+ only_ambient_left = ValidateBundleError(message="bundle invalid", pipe_validation_errors=[ambient_error])+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[both_errors, only_ambient_left],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=None, max_iterations=3)++ assert result.is_valid is False+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve()]+ fixed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert fixed["pipe"]["list_ideas"]["output"] == "Idea[]"+ assert ambient_sibling.read_text(encoding="utf-8") == _SIBLING_MTHDS+ assert result.bail_reason is not None+ assert "outside write scope" in result.bail_reason++ async def test_one_iteration_groups_fixes_per_target_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """Two fixes targeting two files in ONE iteration each land in their own file (D3.4 grouping)."""+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ sibling_path = libs_dir / "sibling.mthds"+ sibling_path.write_text(_SIBLING_MTHDS, encoding="utf-8")+ entry_error = _seq_output_error_data(pipe_code="list_ideas", source=str(bundle_path))+ sibling_error = _seq_output_error_data(pipe_code="sibling_pipe", source=str(sibling_path))+ both_errors = ValidateBundleError(message="bundle invalid", pipe_validation_errors=[entry_error, sibling_error])+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[both_errors, None],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir], max_iterations=3)++ assert result.is_valid is True+ assert result.iterations == 1+ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output", "match-sequence-output"]+ assert [Path(written) for written in result.files_written] == [bundle_path.resolve(), sibling_path.resolve()]+ fixed_entry = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ fixed_sibling = tomlkit.loads(sibling_path.read_text(encoding="utf-8")).unwrap()+ assert fixed_entry["pipe"]["list_ideas"]["output"] == "Idea[]"+ assert fixed_sibling["pipe"]["sibling_pipe"]["output"] == "Idea[]"++ async def test_collision_scan_rebuilds_after_each_written_round(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """A rename from round one blocks a sibling rename proposed in round two.++ If the cross-file map were cached before the loop, the second ``strip-namespace`` fix+ would not see that round one already created ``[pipe.shared]`` in a sibling bundle.+ """+ bundle_path = tmp_path / "entry.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ libs_dir = tmp_path / "libs"+ libs_dir.mkdir()+ first_path = libs_dir / "a_first.mthds"+ first_path.write_text(_DOTTED_SHARED_A_MTHDS, encoding="utf-8")+ second_path = libs_dir / "b_second.mthds"+ second_path.write_text(_DOTTED_SHARED_B_MTHDS, encoding="utf-8")+ validate_mock = mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[+ _strip_namespace_error(pipe_code="rebuild_a.shared", stripped_pipe_code="shared", source=str(first_path)),+ _strip_namespace_error(pipe_code="rebuild_b.shared", stripped_pipe_code="shared", source=str(second_path)),+ ],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[libs_dir], max_iterations=3)++ assert result.is_valid is False+ assert result.iterations == 1+ assert validate_mock.await_count == 2+ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-namespace"]+ assert [Path(written) for written in result.files_written] == [first_path.resolve()]+ assert result.bail_reason is not None+ assert "cross-file collision" in result.bail_reason+ assert "'shared'" in result.bail_reason+ fixed_first = tomlkit.loads(first_path.read_text(encoding="utf-8")).unwrap()+ unchanged_second = tomlkit.loads(second_path.read_text(encoding="utf-8")).unwrap()+ assert "shared" in fixed_first["pipe"]+ assert "rebuild_a.shared" not in fixed_first["pipe"]+ assert "rebuild_b.shared" in unchanged_second["pipe"]++ async def test_max_iterations_none_reads_the_config_default(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``max_iterations=None`` resolves to ``builder_config.fix_loop_max_attempts`` (D3.5)."""+ bundle_path = tmp_path / "scoping.mthds"+ bundle_path.write_text(_MINIMAL_MTHDS, encoding="utf-8")+ fake_config = mocker.MagicMock()+ fake_config.pipelex.builder_config.fix_loop_max_attempts = 1+ mocker.patch("pipelex.pipeline.fixes.fix_loop.get_config", return_value=fake_config)+ # The error persists past the single allowed apply round: the loop must run exactly one+ # round then take its final-validation verdict and bail on max_iterations.+ validate_mock = mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[+ _seq_output_error(pipe_code="list_ideas", source=None),+ _seq_output_error(pipe_code="list_ideas", source=None),+ ],+ )++ result = await fix_bundle_file(bundle_path, library_dirs=[])++ assert result.is_valid is False+ assert result.iterations == 1+ assert result.bail_reason is not None+ assert "max_iterations (1)" in result.bail_reason+ assert validate_mock.await_count == 2diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.pynew file mode 100644index 000000000..d23a84891--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py@@ -0,0 +1,144 @@+"""Unit pins for the fix loop's rule filters: keyword-only ``select_codes`` / ``ignore_codes``.++The filters select *behavior* (which rules may write to disk), applied inside the loop's+safe-fix collection so every consumer — the agent CLI's ``--select``/``--ignore`` today, the+human CLI later — inherits identical semantics. Validation of the codes themselves (unknown+code → loud rejection) is the CLI layer's job, not the loop's.+"""++from pathlib import Path++import pytest+import tomlkit+from pytest_mock import MockerFixture++from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData+from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.fixes.fix_loop import fix_bundle_file++_BUNDLE_MTHDS = """domain = "selectfix"+main_pipe = "list_ideas"++[concept.Idea]+description = "An idea."++[pipe.list_ideas]+type = "PipeLLM"+description = "List ideas."+inputs = { topic = "Text" }+output = "Idea"+prompt = "Write about $topic"+"""+++def _two_rule_error() -> ValidateBundleError:+ """One error per channel: a pipe-channel output mismatch AND a blueprint-channel native+ concept redeclaration — planning two fixes with two distinct fix codes.+ """+ output_error = PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ domain_code="selectfix",+ pipe_code="list_ideas",+ message="output mismatch",+ field_path="",+ expected_output_ref="Idea[]",+ )+ redeclaration_error = PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION,+ domain_code="selectfix",+ concept_code="Idea",+ message="Cannot redeclare native concept 'Idea'.",+ )+ return ValidateBundleError(+ message="bundle invalid",+ pipelex_bundle_blueprint_validation_errors=[redeclaration_error],+ pipe_validation_errors=[output_error],+ )++[email protected](loop_scope="class")+class TestFixLoopSelectIgnore:+ async def test_select_applies_only_the_selected_rule(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``select_codes`` keeps only the named rules: the other planned fix is never applied."""+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_BUNDLE_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_two_rule_error(), _two_rule_error()],+ )++ result = await fix_bundle_file(+ bundle_path,+ library_dirs=[],+ max_iterations=1,+ select_codes=["match-sequence-output"],+ )++ assert [fix.fix_code for fix in result.fixes_applied] == ["match-sequence-output"]+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert parsed["pipe"]["list_ideas"]["output"] == "Idea[]"+ # The ignored rule's target is untouched: the concept declaration survives.+ assert "Idea" in parsed["concept"]++ async def test_ignore_drops_the_named_rule(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """``ignore_codes`` drops the named rules and keeps the rest."""+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_BUNDLE_MTHDS, encoding="utf-8")+ mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=[_two_rule_error(), _two_rule_error()],+ )++ result = await fix_bundle_file(+ bundle_path,+ library_dirs=[],+ max_iterations=1,+ ignore_codes=["match-sequence-output"],+ )++ assert [fix.fix_code for fix in result.fixes_applied] == ["strip-native-concept-redecl"]+ parsed = tomlkit.loads(bundle_path.read_text(encoding="utf-8")).unwrap()+ assert parsed["pipe"]["list_ideas"]["output"] == "Idea"+ assert "Idea" not in parsed.get("concept", {})++ async def test_everything_filtered_out_is_a_plain_no_fix_result(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ ) -> None:+ """When the filters drop every fix, the result is the ordinary no-applicable-fixes shape."""+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(_BUNDLE_MTHDS, encoding="utf-8")+ validate_mock = mocker.patch(+ "pipelex.pipeline.fixes.fix_loop.validate_bundle",+ side_effect=_two_rule_error(),+ )++ result = await fix_bundle_file(+ bundle_path,+ library_dirs=[],+ max_iterations=3,+ select_codes=["strip-namespace"],+ )++ assert result.is_valid is False+ assert result.iterations == 0+ assert result.fixes_applied == []+ assert result.files_written == []+ assert validate_mock.await_count == 1+ assert bundle_path.read_text(encoding="utf-8") == _BUNDLE_MTHDS+ # The dropped fixes still ride the remaining errors for the consumer to see.+ assert [item.suggested_fix.fix_code for item in result.remaining_errors if item.suggested_fix is not None] == [+ "strip-native-concept-redecl",+ "match-sequence-output",+ ]diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.pynew file mode 100644index 000000000..69a36a739--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py@@ -0,0 +1,201 @@+"""Unit tests for the fix planner — enriched error data in, ``SuggestedFix`` out.++The planner is a pure translation keyed on ``error_type`` + structured fields (never+message strings). Each rule only fires when its enrichment is present — set only at the+raise sites that know the correct value — so the same error types raised elsewhere are+suppressed structurally: ``expected_output_ref`` for ``match-sequence-output`` (PipeSequence+raise sites only), ``expected_inputs``/``declared_inputs`` for ``sync-controller-inputs``+(controller input-drift sites only).+"""++import pytest++from pipelex.core.exceptions import PipesAndConceptValidationErrorData+from pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.pipeline.fixes.planner import plan_fix_for_pipe_validation_error+from pipelex.suggested_fix import FixOpKind, FixSafety+++def _error_data(+ *,+ error_type: PipeValidationErrorType,+ pipe_code: str | None = "list_ideas",+ expected_output_ref: str | None = "Idea[]",+ source: str | None = "main.mthds",+) -> PipesAndConceptValidationErrorData:+ return PipesAndConceptValidationErrorData(+ error_type=error_type,+ domain_code="testapp",+ source=source,+ pipe_code=pipe_code,+ message="output mismatch",+ field_path="",+ expected_output_ref=expected_output_ref,+ )+++def _input_drift_error_data(+ *,+ error_type: PipeValidationErrorType = PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ pipe_code: str | None = "make_summary",+ expected_inputs: dict[str, str] | None = None,+ declared_inputs: dict[str, str] | None = None,+ source: str | None = "main.mthds",+) -> PipesAndConceptValidationErrorData:+ return PipesAndConceptValidationErrorData(+ error_type=error_type,+ domain_code="testapp",+ source=source,+ pipe_code=pipe_code,+ message="input drift",+ field_path="",+ expected_inputs=expected_inputs,+ declared_inputs=declared_inputs,+ )+++class TestFixPlanner:+ def test_concept_mismatch_yields_match_sequence_output_fix(self) -> None:+ """An enriched INADEQUATE_OUTPUT_CONCEPT yields a SAFE set_key fix on the pipe's output."""+ fix = plan_fix_for_pipe_validation_error(_error_data(error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT))+ assert fix is not None+ assert fix.fix_code == "match-sequence-output"+ assert fix.safety == FixSafety.SAFE+ assert fix.source == "main.mthds"+ assert len(fix.ops) == 1+ the_op = fix.ops[0]+ assert the_op.kind == FixOpKind.SET_KEY+ assert the_op.table_path == ["pipe", "list_ideas"]+ assert the_op.key == "output"+ assert the_op.value == "Idea[]"++ def test_multiplicity_mismatch_yields_fix_with_expected_ref_value(self) -> None:+ """An enriched INADEQUATE_OUTPUT_MULTIPLICITY yields the same fix, carrying the expected ref."""+ fix = plan_fix_for_pipe_validation_error(+ _error_data(error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY, expected_output_ref="Idea[3]")+ )+ assert fix is not None+ assert fix.fix_code == "match-sequence-output"+ assert fix.ops[0].value == "Idea[3]"++ def test_missing_expected_ref_yields_none(self) -> None:+ """No enriched expected ref (PipeParallel / PipeCondition / operator raise sites) → no fix."""+ fix = plan_fix_for_pipe_validation_error(_error_data(error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT, expected_output_ref=None))+ assert fix is None++ def test_missing_pipe_code_yields_none(self) -> None:+ """Without a pipe locator there is no TOML table to patch → no fix."""+ fix = plan_fix_for_pipe_validation_error(_error_data(error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT, pipe_code=None))+ assert fix is None++ def test_unrelated_error_type_yields_none(self) -> None:+ """The planner is keyed on error_type: other types never produce this fix."""+ fix = plan_fix_for_pipe_validation_error(_error_data(error_type=PipeValidationErrorType.UNRESOLVED_CONCEPT))+ assert fix is None++ def test_missing_source_still_yields_fix(self) -> None:+ """A single-file validation has no source on the error data; the fix still applies (source=None)."""+ fix = plan_fix_for_pipe_validation_error(_error_data(error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT, source=None))+ assert fix is not None+ assert fix.source is None++ @pytest.mark.parametrize(+ "error_type",+ [+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH,+ ],+ )+ def test_input_drift_yields_sync_controller_inputs_fix(self, error_type: PipeValidationErrorType) -> None:+ """Each enriched input-drift error type yields one SAFE sync-controller-inputs fix."""+ fix = plan_fix_for_pipe_validation_error(+ _input_drift_error_data(+ error_type=error_type,+ expected_inputs={"text": "Text"},+ declared_inputs={"text": "Number"},+ )+ )+ assert fix is not None+ assert fix.fix_code == "sync-controller-inputs"+ assert fix.safety == FixSafety.SAFE+ assert fix.source == "main.mthds"+ assert len(fix.ops) == 1+ the_op = fix.ops[0]+ assert the_op.kind == FixOpKind.SET_KEY+ assert the_op.table_path == ["pipe", "make_summary", "inputs"]+ assert the_op.key == "text"+ assert the_op.value == "Text"++ def test_input_drift_diff_adds_updates_and_deletes(self) -> None:+ """The fix is a diff: set_key for added/changed variables, delete_key for extraneous ones."""+ fix = plan_fix_for_pipe_validation_error(+ _input_drift_error_data(+ expected_inputs={"text": "Text", "doc": "Doc"},+ declared_inputs={"text": "Number", "note": "Text"},+ )+ )+ assert fix is not None+ op_shapes = [(op.kind, op.key, op.value) for op in fix.ops]+ assert op_shapes == [+ (FixOpKind.SET_KEY, "text", "Text"),+ (FixOpKind.SET_KEY, "doc", "Doc"),+ (FixOpKind.DELETE_KEY, "note", None),+ ]+ assert all(op.table_path == ["pipe", "make_summary", "inputs"] for op in fix.ops)+ for var_name in ("text", "doc", "note"):+ assert var_name in fix.description++ def test_matching_declared_variable_gets_no_op(self) -> None:+ """A declared variable whose rendered ref already matches is left untouched."""+ fix = plan_fix_for_pipe_validation_error(+ _input_drift_error_data(+ error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ expected_inputs={"doc": "Text?", "note": "Text"},+ declared_inputs={"doc": "Text?"},+ )+ )+ assert fix is not None+ assert [(op.kind, op.key) for op in fix.ops] == [(FixOpKind.SET_KEY, "note")]++ def test_no_declared_inputs_ensures_table_then_sets_each_key(self) -> None:+ """The same ops create a missing table or preserve an explicitly empty block table."""+ fix = plan_fix_for_pipe_validation_error(+ _input_drift_error_data(+ expected_inputs={"text": "Text", "doc": "Doc?"},+ declared_inputs={},+ )+ )+ assert fix is not None+ assert [(op.kind, op.key, op.value) for op in fix.ops] == [+ (FixOpKind.ENSURE_TABLE, None, None),+ (FixOpKind.SET_KEY, "text", "Text"),+ (FixOpKind.SET_KEY, "doc", "Doc?"),+ ]+ assert all(op.table_path == ["pipe", "make_summary", "inputs"] for op in fix.ops)++ def test_equal_mappings_yield_none(self) -> None:+ """An empty diff (renderings already agree) must not produce a no-op fix."""+ fix = plan_fix_for_pipe_validation_error(+ _input_drift_error_data(+ error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH,+ expected_inputs={"text": "Text"},+ declared_inputs={"text": "Text"},+ )+ )+ assert fix is None++ def test_input_drift_without_expected_inputs_yields_none(self) -> None:+ """No enrichment (operator raise sites) → no fix."""+ fix = plan_fix_for_pipe_validation_error(_input_drift_error_data(expected_inputs=None, declared_inputs={"text": "Text"}))+ assert fix is None++ def test_input_drift_without_declared_inputs_yields_none(self) -> None:+ """Without the declared mapping the planner cannot diff → no fix."""+ fix = plan_fix_for_pipe_validation_error(_input_drift_error_data(expected_inputs={"text": "Text"}, declared_inputs=None))+ assert fix is None++ def test_input_drift_without_pipe_code_yields_none(self) -> None:+ """Without a pipe locator there is no TOML table to patch → no fix."""+ fix = plan_fix_for_pipe_validation_error(_input_drift_error_data(pipe_code=None, expected_inputs={"text": "Text"}, declared_inputs={}))+ assert fix is Nonediff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_render.py b/tests/unit/pipelex/pipeline/fixes/test_fix_render.pynew file mode 100644index 000000000..54cc508be--- /dev/null+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_render.py@@ -0,0 +1,164 @@+"""Unit tests for agent-facing fix result markdown."""++from typing import Any++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.pipeline.fixes.fix_loop import FixBundleResult+from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_still_invalid_markdown+from pipelex.suggested_fix import FixSafety, SuggestedFix+++class TestFixRender:+ def test_already_valid_result_mentions_no_applied_fixes(self) -> None:+ result: dict[str, Any] = {+ "success": True,+ "is_valid": True,+ "bundle_path": "/workspace/bundle.mthds",+ "iterations": 0,+ "fixes_applied": [],+ "files_written": [],+ "remaining_errors": [],+ }++ rendered = format_fix_markdown(result)++ assert rendered.startswith("# Bundle already valid")+ assert "- **Bundle:** `/workspace/bundle.mthds`" in rendered+ assert "- **Iterations:** 0" in rendered+ assert "## Applied Fixes" not in rendered++ def test_fixed_result_lists_applied_fixes_and_written_files(self) -> None:+ result: dict[str, Any] = {+ "success": True,+ "is_valid": True,+ "bundle_path": "/workspace/entry.mthds",+ "iterations": 1,+ "fixes_applied": [+ {+ "fix_code": "match-sequence-output",+ "description": "Set output of pipe 'list_ideas' to 'Idea[]'",+ "source": "/workspace/entry.mthds",+ "ops": [],+ }+ ],+ "files_written": ["/workspace/entry.mthds"],+ "remaining_errors": [],+ }++ rendered = format_fix_markdown(result)++ assert rendered.startswith("# Fix applied - bundle is valid")+ assert "`match-sequence-output` - Set output of pipe 'list_ideas' to 'Idea[]'" in rendered+ assert "## Files Written" in rendered+ assert "- `/workspace/entry.mthds`" in rendered++ def test_multi_file_fix_names_non_entry_source(self) -> None:+ result: dict[str, Any] = {+ "success": True,+ "is_valid": True,+ "bundle_path": "/workspace/entry.mthds",+ "iterations": 1,+ "fixes_applied": [+ {+ "fix_code": "strip-namespace",+ "description": "Strip the same-domain prefix from pipe 'pkg.hello'",+ "source": "/workspace/libs/sibling.mthds",+ "ops": [],+ }+ ],+ "files_written": ["/workspace/libs/sibling.mthds"],+ "remaining_errors": [],+ }++ rendered = format_fix_markdown(result)++ assert "`strip-namespace` - Strip the same-domain prefix from pipe 'pkg.hello' (`/workspace/libs/sibling.mthds`)" in rendered++ def test_non_runnable_result_lists_pending_signatures(self) -> None:+ result: dict[str, Any] = {+ "success": True,+ "is_valid": True,+ "is_runnable": False,+ "bundle_path": "/workspace/entry.mthds",+ "iterations": 0,+ "fixes_applied": [],+ "files_written": [],+ "remaining_errors": [],+ "pending_signatures": ["signature_demo.summarize_doc"],+ }++ rendered = format_fix_markdown(result)++ assert rendered.startswith("# Bundle valid but not runnable")+ assert "## Pending Signatures" in rendered+ assert "- `signature_demo.summarize_doc`" in rendered++ def test_still_invalid_renders_applied_fixes_bail_and_remaining_as_prose(self) -> None:+ """The still-invalid markdown names the partial progress, the bail reason, and the remaining+ errors as prose items (with their 💡 lines) — not a JSON dump.+ """+ result = FixBundleResult(+ is_valid=False,+ iterations=2,+ fixes_applied=[+ SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output of pipe 'a' to 'X[]'",+ safety=FixSafety.SAFE,+ source="/w/entry.mthds",+ ops=[],+ )+ ],+ files_written=["/w/entry.mthds"],+ remaining_errors=[+ ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="unresolved_concept",+ pipe_code="b",+ concept_code="Missing",+ message="Concept 'Missing' is not defined.",+ source="/w/entry.mthds",+ suggested_fix=SuggestedFix(+ fix_code="strip-namespace",+ description="Strip the same-domain prefix from pipe 'b'",+ safety=FixSafety.SAFE,+ ops=[],+ ),+ )+ ],+ bail_reason="Cross-file collision: two files declare pipe 'b'",+ )++ rendered = format_fix_still_invalid_markdown(result, bundle_path="/w/entry.mthds")++ assert rendered.startswith("# Fix incomplete - bundle still invalid")+ assert "## Applied Fixes" in rendered+ assert "- `match-sequence-output` - Set output of pipe 'a' to 'X[]'" in rendered+ assert "**Stopped:** Cross-file collision: two files declare pipe 'b'" in rendered+ # Remaining errors render as prose items, with the humanized title and the 💡 suggested-fix line.+ assert "1. **Unresolved Concept**" in rendered+ assert " - Concept: `Missing`" in rendered+ assert " - 💡 Suggested fix: Strip the same-domain prefix from pipe 'b'" in rendered+ # A remaining fixable item flips the tip toward "not applied", not "no safe fix".+ assert "still show a suggested fix that was not applied" in rendered++ def test_still_invalid_tip_says_manual_when_no_remaining_fix(self) -> None:+ """When no remaining error carries a suggested fix, the tip points at a manual edit."""+ result = FixBundleResult(+ is_valid=False,+ iterations=1,+ fixes_applied=[],+ files_written=[],+ remaining_errors=[+ ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="unresolved_concept",+ message="Concept 'Missing' is not defined.",+ )+ ],+ )++ rendered = format_fix_still_invalid_markdown(result, bundle_path="/w/entry.mthds")++ assert "have no deterministic safe fix" in rendered+ assert "## Applied Fixes" not in rendereddiff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.pyindex 2175b49bd..749a67b4f 100644--- a/tests/unit/pipelex/pipeline/test_validation_errors.py+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py@@ -17,6 +17,7 @@ from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidatfrom pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorTypefrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.validation_errors import build_validation_error_items+from pipelex.suggested_fix import FixOpKinddef _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:@@ -271,6 +272,132 @@ class TestBuildValidationErrorItems:assert problem_document["validation_errors"] == cli_dictsassert json.dumps(problem_document["validation_errors"], sort_keys=True) == json.dumps(cli_dicts, sort_keys=True)+ def test_enriched_pipe_validation_error_rides_a_suggested_fix(self) -> None:+ """An enriched output-mismatch error data yields an item carrying the planner's suggested_fix."""+ items = build_validation_error_items(+ blueprint_errors=[],+ factory_errors=[],+ pipe_validation_errors=[+ PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,+ domain_code="testapp",+ source="main.mthds",+ pipe_code="list_ideas",+ message="output mismatch",+ field_path="",+ expected_output_ref="Idea[]",+ ),+ ],+ )+ assert len(items) == 1+ suggested_fix = items[0].suggested_fix+ assert suggested_fix is not None+ assert suggested_fix.fix_code == "match-sequence-output"+ assert suggested_fix.ops[0].table_path == ["pipe", "list_ideas"]+ assert suggested_fix.ops[0].value == "Idea[]"++ def test_input_drift_error_rides_a_sync_controller_inputs_fix(self) -> None:+ """An enriched controller input-drift error data yields an item carrying the multi-op fix."""+ items = build_validation_error_items(+ blueprint_errors=[],+ factory_errors=[],+ pipe_validation_errors=[+ PipesAndConceptValidationErrorData(+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ domain_code="testapp",+ source="main.mthds",+ pipe_code="make_summary",+ message="input drift",+ field_path="",+ expected_inputs={"text": "Text"},+ declared_inputs={"text": "Number", "note": "Text"},+ ),+ ],+ )+ assert len(items) == 1+ suggested_fix = items[0].suggested_fix+ assert suggested_fix is not None+ assert suggested_fix.fix_code == "sync-controller-inputs"+ assert suggested_fix.source == "main.mthds"+ assert [(op.kind, op.key) for op in suggested_fix.ops] == [+ (FixOpKind.SET_KEY, "text"),+ (FixOpKind.DELETE_KEY, "note"),+ ]++ def test_blueprint_native_redeclaration_rides_a_strip_fix(self) -> None:+ """An enriched native-concept redeclaration blueprint error carries the strip fix through the builder.++ First blueprint-channel fix: the builder's blueprint loop now runs the planner too, and the+ fix carries a populated ``source`` (blueprint error data has one, unlike the pipe raise sites).+ """+ items = build_validation_error_items(+ blueprint_errors=[+ PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION,+ domain_code="nativefix",+ source="main.mthds",+ concept_code="Text",+ message="Cannot declare a concept named 'Text' because it is natively available in Pipelex.",+ ),+ ],+ factory_errors=[],+ pipe_validation_errors=[],+ )+ assert len(items) == 1+ suggested_fix = items[0].suggested_fix+ assert suggested_fix is not None+ assert suggested_fix.fix_code == "strip-native-concept-redecl"+ assert suggested_fix.source == "main.mthds"+ assert [(op.kind, op.table_path, op.key) for op in suggested_fix.ops] == [(FixOpKind.DELETE_KEY, ["concept"], "Text")]++ def test_blueprint_strip_namespace_rides_a_rename_fix(self) -> None:+ """An enriched same-domain dotted declaration carries a strip-namespace rename through the builder."""+ items = build_validation_error_items(+ blueprint_errors=[+ PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,+ domain_code="greetings",+ source="main.mthds",+ pipe_code="greetings.hello",+ stripped_pipe_code="hello",+ message="Pipe code 'greetings.hello' is not a valid pipe code. Must be in snake_case.",+ ),+ ],+ factory_errors=[],+ pipe_validation_errors=[],+ )+ assert len(items) == 1+ suggested_fix = items[0].suggested_fix+ assert suggested_fix is not None+ assert suggested_fix.fix_code == "strip-namespace"+ assert [(op.kind, op.table_path, op.key, op.new_key) for op in suggested_fix.ops] == [+ (FixOpKind.RENAME_TABLE_KEY, ["pipe"], "greetings.hello", "hello"),+ ]++ def test_non_fixable_blueprint_error_has_no_suggested_fix(self) -> None:+ """An un-enriched INVALID_PIPE_CODE_SYNTAX (no ``stripped_pipe_code``) keeps ``suggested_fix`` unset."""+ items = build_validation_error_items(+ blueprint_errors=[+ PipelexBundleBlueprintValidationErrorData(+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,+ domain_code="nativefix",+ source="main.mthds",+ message="Invalid pipe code syntax",+ ),+ ],+ factory_errors=[],+ pipe_validation_errors=[],+ )+ assert len(items) == 1+ assert items[0].suggested_fix is None++ def test_non_fixable_pipe_validation_error_has_no_suggested_fix(self) -> None:+ """A pipe-validation item with no enriched data keeps suggested_fix unset (wire unchanged)."""+ items = _build_items(_all_category_error())+ assert all(item.suggested_fix is None for item in items)+ for item in items:+ assert "suggested_fix" not in item.model_dump(mode="json", exclude_none=True)+def test_instantiation_errors_are_projected_as_pipe_validation(self) -> None:"""Pipe/concept *instantiation* errors reach the wire too (not silently dropped).diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.pyindex b89b6777c..acfe42f28 100644--- a/tests/unit/pipelex/pipeline/test_validation_render.py+++ b/tests/unit/pipelex/pipeline/test_validation_render.py@@ -2,9 +2,17 @@from __future__ import annotations+from pathlib import Pathfrom typing import Any-from pipelex.pipeline.validation_render import format_validate_markdown, render_invalid_validation_markdown+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.pipeline.validation_render import (+ build_fix_command,+ format_validate_markdown,+ format_validation_error_items_markdown,+ render_invalid_validation_markdown,+)+from pipelex.suggested_fix import FixSafety, SuggestedFixclass TestValidationRender:@@ -94,9 +102,11 @@ class TestValidationRender:assert "✅" not in markdownassert "⚠️" not in markdown- def test_renders_invalid_report_with_locators_and_dry_run_residual(self):- """The invalid-arm renderer surfaces the message, an error count, and each item's- category + message with its present locators; a dry_run residual (no locators) renders too.+ def test_renders_invalid_report_as_prose_with_fix_lines_and_dry_run_residual(self):+ """The invalid-arm renderer reconstructs the typed items from the report and delegates to+ the shared prose renderer: category-grouped headings, humanized titles, identity fields,+ the message, per-item `💡 Suggested fix` lines, and the plain dry_run residual — the same+ prose the agent CLI and human panel show (no more dict-based `## Errors (N)` list)."""report: dict[str, Any] = {"is_valid": False,@@ -104,12 +114,18 @@ class TestValidationRender:"validation_errors": [{"category": "pipe_validation",- "error_type": "PipeValidationError",+ "error_type": "inadequate_output_multiplicity","message": "Pipe references an unknown concept.","pipe_code": "summarize","concept_code": "Contractt","field_name": "output","source": "/fake/method.mthds",+ "suggested_fix": {+ "fix_code": "match-sequence-output",+ "description": "Set output of pipe 'summarize' to 'Contract'",+ "safety": "safe",+ "ops": [],+ },},{"category": "dry_run",@@ -122,11 +138,75 @@ class TestValidationRender:markdown = render_invalid_validation_markdown(report)assert markdown.startswith("# Validation failed")- assert "MTHDS validation found errors" in markdown- assert "## Errors (2)" in markdown- assert "1. **pipe_validation** — Pipe references an unknown concept." in markdown- assert " - pipe: `summarize`" in markdown- assert " - concept: `Contractt`" in markdown- assert " - source: `/fake/method.mthds`" in markdown- # The dry_run residual has no locators — it renders its category + message, no sub-bullets.- assert "2. **dry_run** — Dry run failed: boom." in markdown+ # Prose shape from the shared renderer: category heading + humanized title + identity fields.+ assert "## Pipe validation errors" in markdown+ assert "1. **Inadequate Output Multiplicity**" in markdown+ assert " - Pipe: `summarize`" in markdown+ assert " - Concept: `Contractt`" in markdown+ assert " - Field: `output`" in markdown+ assert " - Pipe references an unknown concept." in markdown+ assert " - 💡 Suggested fix: Set output of pipe 'summarize' to 'Contract'" in markdown+ assert " - Source: `/fake/method.mthds`" in markdown+ # The dry_run residual keeps its plain single-message rendering.+ assert "## Dry run error" in markdown+ assert "Dry run failed: boom." in markdown++ def test_format_validation_error_items_markdown_groups_categories_and_renders_fix_line(self):+ """The shared items renderer groups by category, humanizes the error_type title, renders+ the identity fields + message + `💡 Suggested fix` line, and keeps the dry_run residual plain.+ """+ items = [+ ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ error_type="inadequate_output_multiplicity",+ pipe_code="brainstorm",+ domain_code="story_studio",+ source="/w/bundle.mthds",+ message="the sequence 'brainstorm' declares its output as 'StoryIdea', but its last step yields 'StoryIdea[]'.",+ suggested_fix=SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step",+ safety=FixSafety.SAFE,+ ops=[],+ ),+ ),+ ValidationErrorItem(+ category=ValidationErrorCategory.DRY_RUN,+ error_type="DryRunError",+ message="Dry run failed: boom.",+ ),+ ]++ markdown = format_validation_error_items_markdown(items)++ # Category grouping (markdown headings), humanized title, identity fields, message, fix line.+ assert "## Pipe validation errors" in markdown+ assert "1. **Inadequate Output Multiplicity**" in markdown+ assert " - Pipe: `brainstorm`" in markdown+ assert " - Domain: `story_studio`" in markdown+ assert " - the sequence 'brainstorm' declares its output as 'StoryIdea'" in markdown+ assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown+ assert " - Source: `/w/bundle.mthds`" in markdown+ # No internal repr / Python-list-repr brackets leak (Phase 1 diseases stay cured downstream).+ assert "multiplicity=None" not in markdown+ # The dry_run residual keeps its plain single-message rendering (no numbering, no bullets).+ assert "## Dry run error" in markdown+ assert "Dry run failed: boom." in markdown++ def test_build_fix_command_echoes_library_dirs_and_signatures(self):+ """`build_fix_command` shell-joins the executable, path, each `-L` dir, and `--allow-signatures`."""+ command = build_fix_command(+ "pipelex-agent",+ bundle_path=Path("my bundle.mthds"),+ library_dirs=[Path("libs/a"), Path("libs/b")],+ allow_signatures=True,+ )++ # shlex.join quotes the space-bearing path so it stays one argument when pasted.+ assert command == "pipelex-agent fix bundle 'my bundle.mthds' -L libs/a -L libs/b --allow-signatures"++ def test_build_fix_command_minimal_has_no_flags(self):+ """With no library dirs and signatures disabled, only the bare `fix bundle <path>` is emitted."""+ command = build_fix_command("pipelex", bundle_path=Path("bundle.mthds"))++ assert command == "pipelex fix bundle bundle.mthds"diff --git a/tests/unit/pipelex/test_suggested_fix.py b/tests/unit/pipelex/test_suggested_fix.pynew file mode 100644index 000000000..e3878ca1c--- /dev/null+++ b/tests/unit/pipelex/test_suggested_fix.py@@ -0,0 +1,78 @@+"""Unit tests for the suggested-fix wire models (``pipelex/suggested_fix.py``).++``SuggestedFix`` rides ``ValidationErrorItem.suggested_fix`` — the additive, optional,+runtime-only wire field (D2). These tests pin the serialization round-trip and the+``exclude_none`` invariant: a non-fixable error item serializes byte-identically to+what it was before the field existed.+"""++import json++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.suggested_fix import FixOp, FixOpKind, FixSafety, SuggestedFix+++def _sample_fix() -> SuggestedFix:+ return SuggestedFix(+ fix_code="match-sequence-output",+ description="Set output to 'Idea[]' to match the last step",+ safety=FixSafety.SAFE,+ source="main.mthds",+ ops=[+ FixOp(+ kind=FixOpKind.SET_KEY,+ table_path=["pipe", "list_ideas"],+ key="output",+ value="Idea[]",+ ),+ ],+ )+++class TestSuggestedFixModels:+ def test_round_trip_preserves_all_fields(self) -> None:+ """A SuggestedFix survives a JSON dump/load round-trip unchanged."""+ fix = _sample_fix()+ reloaded = SuggestedFix.model_validate_json(fix.model_dump_json())+ assert reloaded == fix+ assert reloaded.ops[0].kind == FixOpKind.SET_KEY+ assert reloaded.ops[0].table_path == ["pipe", "list_ideas"]+ assert reloaded.ops[0].value == "Idea[]"+ assert reloaded.safety == FixSafety.SAFE++ def test_enum_fields_serialize_to_plain_strings(self) -> None:+ """StrEnum fields ride the wire as their plain string values."""+ dumped = _sample_fix().model_dump(mode="json")+ assert dumped["safety"] == "safe"+ assert dumped["ops"][0]["kind"] == "set_key"++ def test_validation_error_item_carries_suggested_fix(self) -> None:+ """ValidationErrorItem gains the optional suggested_fix field and dumps it when set."""+ item = ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ message="output mismatch",+ pipe_code="list_ideas",+ suggested_fix=_sample_fix(),+ )+ dumped = item.model_dump(mode="json", exclude_none=True)+ assert dumped["suggested_fix"]["fix_code"] == "match-sequence-output"+ assert dumped["suggested_fix"]["ops"][0]["key"] == "output"++ def test_non_fixable_item_stays_byte_identical(self) -> None:+ """An item without a fix serializes with NO suggested_fix key — byte-identical to today."""+ item = ValidationErrorItem(+ category=ValidationErrorCategory.PIPE_VALIDATION,+ message="output mismatch",+ pipe_code="list_ideas",+ )+ dumped = item.model_dump(mode="json", exclude_none=True)+ assert "suggested_fix" not in dumped+ assert json.dumps(dumped, sort_keys=True) == json.dumps(+ {"category": "pipe_validation", "message": "output mismatch", "pipe_code": "list_ideas"},+ sort_keys=True,+ )++ def test_unset_op_fields_drop_from_wire(self) -> None:+ """A set_key op's unused fields (new_key) drop out of the exclude_none projection."""+ dumped = _sample_fix().model_dump(mode="json", exclude_none=True)+ assert "new_key" not in dumped["ops"][0]diff --git a/uv.lock b/uv.lockindex 7530cf41a..7993a202e 100644--- a/uv.lock+++ b/uv.lock@@ -3263,6 +3263,7 @@ dependencies = [{ name = "opentelemetry-sdk" },{ name = "opentelemetry-semantic-conventions" },{ name = "pillow" },+ { name = "pipelex-tools-py" },{ name = "polyfactory" },{ name = "portkey-ai" },{ name = "posthog" },@@ -3415,6 +3416,7 @@ requires-dist = [{ name = "opentelemetry-semantic-conventions" },{ name = "pillow", specifier = ">=12.1.1" },{ name = "pipelex-tools", marker = "extra == 'dev'", specifier = ">=0.6.0" },+ { name = "pipelex-tools-py", specifier = "==0.1.1" },{ name = "polyfactory", specifier = ">=2.21.0" },{ name = "portkey-ai", specifier = ">=2.1.0" },{ name = "posthog", specifier = ">=6.7.0" },@@ -3469,6 +3471,21 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/87/97/bb4a9034781e7f189d903b8940de837c723201d1733a71bb7072d0bcf309/pipelex_tools-0.6.0-py3-none-win_amd64.whl", hash = "sha256:56424ede9de3268c816af937f3525bf0b4c4fce8612bf6907e21f4ce078c3ead", size = 5471901, upload-time = "2026-05-31T23:15:04.587Z" },]+[[package]]+name = "pipelex-tools-py"+version = "0.1.1"+source = { registry = "https://pypi.org/simple" }+sdist = { url = "https://files.pythonhosted.org/packages/1c/7a/475d5314cf2c8a402ff646ebf435ccc9d51b9d4e3c52eb063b37130e6ee5/pipelex_tools_py-0.1.1.tar.gz", hash = "sha256:ec1f5e30fe666417f210a5bb1013394cef8b0c246d070037d78cf8dfcd086603", size = 114697, upload-time = "2026-06-29T10:23:00.415Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/6b/51/701114de4b1744dbddf37ec172ab97649177d6c7c761d75689a4b1ea6788/pipelex_tools_py-0.1.1-cp38-abi3-macosx_10_12_x86_64.whl", hash = "sha256:69e930881da8787259cf3040eb33b669dfb4bd4ed13c8a68f082ee284f4fa3a7", size = 2490500, upload-time = "2026-06-29T10:22:48.96Z" },+ { url = "https://files.pythonhosted.org/packages/b0/4f/3f28ffe46d8a31760841f29a773519794b86c3e4a1d4eec70c9b74f97282/pipelex_tools_py-0.1.1-cp38-abi3-macosx_11_0_arm64.whl", hash = "sha256:fe07dbf840deace1fa8bebe8154fef0abb4284177aae89961437edf9bddf3257", size = 2388577, upload-time = "2026-06-29T10:22:50.771Z" },+ { url = "https://files.pythonhosted.org/packages/ea/79/6d235117695c803946ae0fdcb5ad9410c11ed70f7182bf7a01460bf4d410/pipelex_tools_py-0.1.1-cp38-abi3-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:29b818d6af5af6510bf25505acbe7d3cdca309f1443cd95299c61b0b7fd0e180", size = 2717460, upload-time = "2026-06-29T10:22:52.446Z" },+ { url = "https://files.pythonhosted.org/packages/43/aa/31f70c2ef5b7417d0b46c3b1079f797d3d42a2fc60ceaf176a8a9d52938f/pipelex_tools_py-0.1.1-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:902b69127df66a91f80d3b3158217ff29aa40c2ad86917b46de7e9640a6f81ab", size = 2505388, upload-time = "2026-06-29T10:22:53.902Z" },+ { url = "https://files.pythonhosted.org/packages/b9/4f/53f3e3e10391d3035bbc84966a80439277b04a9efc8cab09e890871a3cfe/pipelex_tools_py-0.1.1-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f89c17a9c58161ff0ff515bc7054bfc58710c9edec3d4dfc842d07966f239ba", size = 2629996, upload-time = "2026-06-29T10:22:55.713Z" },+ { url = "https://files.pythonhosted.org/packages/8d/72/4a68e0b3f3c758c0808a888db40299d46af1f79b23aa0c3fcc442f3a68de/pipelex_tools_py-0.1.1-cp38-abi3-win32.whl", hash = "sha256:b26e93fd975682b7dc15d0d300ddb540650cfdf9dff917a6e4880cc1283e83c8", size = 2396611, upload-time = "2026-06-29T10:22:57.173Z" },+ { url = "https://files.pythonhosted.org/packages/98/16/aa4ad4790c29d2f7d0a9160e3fe2faf1b8be12d9dde081f989654038fc63/pipelex_tools_py-0.1.1-cp38-abi3-win_amd64.whl", hash = "sha256:a925bdc2e0ee00dde3adc9fe360e227f2968376b2ed0bbe4e14bb82014d9ac7e", size = 2633419, upload-time = "2026-06-29T10:22:58.875Z" },+]+[[package]]name = "platformdirs"version = "4.9.6"diff --git a/wip/autofix/README.md b/wip/autofix/README.mdnew file mode 100644index 000000000..480c91cc6--- /dev/null+++ b/wip/autofix/README.md@@ -0,0 +1,18 @@+# Autofix track++Deterministic auto-fixing of `.mthds` validation errors — fixes attached to validation diagnostics, applied by a convergence loop.++| Doc | What it is | Status |+| --- | --- | --- |+| [master-plan.md](master-plan.md) | Executive step ladder: spike → wave 1 → protocol/API/MCP/editor waves | **CURRENT — steps 1–5 DONE (steps 3+4 merged as PR #1035; step 5 on `feature/Autofix-step5`, PR-ready); step 6 (release train) next** |+| [suggested-fixes-design.md](suggested-fixes-design.md) | The live design: architecture, fix rules, phases | **CURRENT — steps 1 + 2 DONE; per-checkpoint findings + the step-2 abstraction verdict recorded inside** |+| [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md) | Detailed design + working plan for step 5 (`pipelex fix bundle` + the `💡 Suggested fix:` line in `pipelex validate`) | **DONE — all phases incl. `--diff`; CHECKPOINT B cleared (5 bugs fixed, 5 deferred); PR-ready** |+| [validation-error-reporting-plan.md](validation-error-reporting-plan.md) | Follow-on quality track (dogfooded on `pipelex-demos/bad_bundles`): author-syntax messages at the raise sites, prose agent `validate`/`fix` surfaces, and one clean summary `message` on every surface | **DONE — all phases complete 2026-07-09; conformance corpus regen release-gated to step 6; archived from the worktree-root `TODOS.md`** |+| [step3-step4-hardened-loop-and-agent-apply.md](step3-step4-hardened-loop-and-agent-apply.md) | Detailed design + working plan for steps 3 (multi-file targeting) and 4 (`pipelex-agent fix bundle`) | **DONE — merged as PR #1035; review triage in [pr-1035-review-notes.md](pr-1035-review-notes.md)** |+| [pr-1035-review-notes.md](pr-1035-review-notes.md) | PR #1035 review triage — one real-but-inert finding deferred (intra-round cross-file collision) | **CURRENT** |+| `deferred-checkpoint-{0,a,a-prime,b,c,d,e}-review-items.md` | Real-but-deferred items from each checkpoint's code review (multi-file targeting, conformance fixture sync, upstream `pipelex-tools-py` follow-ups, rename convergence cap, the step-5 exit triage in `-e`, …) | **CURRENT** |+| [spike-reviewers-guide.md](spike-reviewers-guide.md) | Reviewer's guide for the step-1 spike PR (#1027) — the chain, invariants, test map | **DONE — Checkpoint 0 cleared 2026-07-07; archived from the worktree-root `TODOS.md`** |+| [step2-reviewers-guide.md](step2-reviewers-guide.md) | Reviewer's guide for the step-2 PR (#1031) — the chain, invariants, test map | **DONE — Checkpoint 1 cleared 2026-07-08; archived from the worktree-root `TODOS.md`** |+| [old-plan-to-auto-fix.md](old-plan-to-auto-fix.md) | The original `feature/Bundle-fixer` plan (standalone fix engine) | Superseded — kept as reference; its "Legacy reference" citations point at code that no longer exists |++The abandoned `feature/Bundle-fixer` branch still exists and holds harvestable domain logic (see the design doc's salvage section), but its architecture is not the one we're building.diff --git a/wip/autofix/deferred-checkpoint-0-review-items.md b/wip/autofix/deferred-checkpoint-0-review-items.mdnew file mode 100644index 000000000..03148d352--- /dev/null+++ b/wip/autofix/deferred-checkpoint-0-review-items.md@@ -0,0 +1,29 @@+# Deferred items from Checkpoint 0 code review++Items surfaced by the clean-context code review of the Phase 0 spike (and the PR bot round) that are real but deliberately NOT addressed in the spike, per the no-over-engineering rule. Each belongs to an already-planned later step.++## 0. `is_single_file` must derive from the RESOLVED library dirs (Phase 1, with multi-file targeting)++Cubic finding, arbitrated VALID-but-DEFER. `fix_bundle_file` gates source-less fixes on `library_dirs is None`, which is wrong in both directions: an explicit `library_dirs=[]` is a documented "no libraries" value (`resolve_library_dirs` docstring) that IS single-file yet gets fixes dropped (safe-only over-filtering — reduced capability, never a wrong patch); and `library_dirs=None` can fall through to hub defaults or `PIPELEXPATH` and load OTHER files while the gate still calls it single-file. The band-aid one-liner (`not library_dirs`) would fix only the harmless direction. The correct fix — compute the gate from the resolved `effective_dirs` (`resolve_library_dirs(library_dirs)`) — is entangled with real multi-file targeting (item 1 below) and lands with it in Phase 1. No production caller passes `[]` today.++## 1. Real multi-file fix targeting (Phase 1)++The spike's convergence loop refuses to apply source-less fixes when `library_dirs` is set (`_applicable_safe_fixes` in `pipelex/pipeline/fixes/fix_loop.py`) — a safe no-op, not a solution. The review found the underlying gap: `SuggestedFix.source` is populated from `PipeValidationError.file_path`, and **no raise site in the codebase ever sets `file_path`**, so the source-based file check is dead code today. The scoping guard prevents the corruption scenario (same `pipe_code` in two domains → fix patches the wrong file's table), but multi-file bundles get no fixes at all.++Phase 1 must thread the declaring file into the enriched errors — either set `file_path` at the raise sites (the pipe/library layer knows the source file) or carry a domain qualifier the loop can check against the target file's `domain` key. Until then, `fix` only fixes single-file bundles. This matches the master plan's "hardened loop (multi-file targeting)" Phase 1 item.++## 1b. `_fix_fingerprint` must include `new_key` when rename ops land (Phase 1)++gstack pre-landing review finding, deferred. The no-progress fingerprint in `fix_loop.py` hashes each op as `kind:path:key:value` and omits `new_key` — two `rename_table_key` ops differing only in `new_key` would collide and trigger a false no-progress bail. Zero impact today (no planner emits rename ops; the applier raises for them). Add `new_key` to the fingerprint in the same Phase 1 change that implements position-preserving rename.++## 1c. Ship-wave changelog must mention the additive wire field++Once released, `suggested_fix` surfaces in `/validate` API payloads (additive, `exclude_none`). The master-plan step 3 changelog entry should call out the new optional field so API consumers know about it.++## 2. Conformance fixture regeneration (cross-repo sync wave)++`conformance/validate-error-qa/generated/invalid_inadequate_output_multiplicity.json` pins the exact JSON body of an `INADEQUATE_OUTPUT_MULTIPLICITY` error from a live `pipelex-api`. Once this enrichment (`suggested_fix` on `ValidationErrorItem`, `expected_output_ref`) reaches the runner API via a pipelex release + pin bump, that fixture needs regeneration. Belongs to the already-tracked cross-repo schema-sync step (master plan) — nothing to do in this repo now.++## 3. Accepted as-is: unconditional `expected_output_ref` computation++`PipeSequence.validate_output_with_library` now computes `expected_output_ref` before the compatibility checks, so it also runs on the happy path. Reviewed and accepted: the cost is one string format + attribute reads on a validation (not execution) path, and computing it lazily would re-duplicate the code the change deduplicated. Not deferred work — recorded so a later reviewer knows it was a deliberate call.diff --git a/wip/autofix/deferred-checkpoint-a-prime-review-items.md b/wip/autofix/deferred-checkpoint-a-prime-review-items.mdnew file mode 100644index 000000000..b3dd8013f--- /dev/null+++ b/wip/autofix/deferred-checkpoint-a-prime-review-items.md@@ -0,0 +1,21 @@+# Deferred follow-ups from Checkpoint A′ (format_mthds backend)++Two forward-looking items surfaced during Phase A′ and its review, both concerning **`pipelex-tools-py`** — which is ours (`vscode-pipelex/crates/pipelex-py`), so both are upstream-fixable. Neither blocks Phase A′; recorded here to revisit at the noted trigger.++## 1. Simplify the `Diagnostic` import workaround once the fixed `pipelex-tools-py` ships++Louis is fixing the stub/runtime drift in the package.++**What we hit:** `pipelex_tools`' PEP 561 stub declares `Diagnostic` / `Range` / `FormatResult` / `LintResult` in `__all__`, but those TypedDicts are type-only — not runtime exports of the compiled module. So `from pipelex_tools import Diagnostic` type-checks (pyright/mypy read the stub) yet raises `ImportError` at runtime.++**Current workaround** (`pipelex/pipeline/fixes/applier.py`): import only the real callable `format_mthds` at module top, and pull `Diagnostic` in under a `TYPE_CHECKING` guard with a quoted annotation on `_render_syntax_diagnostic(diagnostic: "Diagnostic")`.++**Follow-up (gated on the fix shipping + our pin bump):** once `pipelex-tools-py` exports the TypedDicts at runtime (or is otherwise fixed so the advertised import works), delete the `TYPE_CHECKING` block and the quoted annotation, and import `Diagnostic` at the top beside `format_mthds`. Bump the `pipelex-tools-py` pin in `pyproject.toml` to the fixed version in the same change. Purely a cleanup — no behavior change.++## 2. Explore an upstream rename / canonical-ordering primitive for Phase C (`strip-namespace`)++**Do not dig into this now** — it's a note for when Phase C is actually attempted (Phase C is a gated stretch; dropping it is a valid outcome).++**Context:** Phase C's `strip-namespace` fix needs a **position-preserving rename** of a `[pipe.<domain>.<code>]` table key. The known trap (from the old `feature/Bundle-fixer` branch) is that a tomlkit `del` + re-add sends the renamed pipe to the bottom of `[pipe]`. Phase A′ does **not** rescue this: `format_mthds` reflows spacing and alignment but does **not reorder** tables or keys, so a reordered pipe stays reordered after the format pass.++**Possible upstream angle:** since `pipelex-tools-py` is ours, `format_mthds` (or a sibling function) could expose either a position-preserving table-key **rename primitive** or a **canonical table-ordering** option. Either would let Phase C sidestep the fiddly tomlkit rename mechanics that currently gate the whole rule. Weigh this against just solving it in tomlkit when Phase C's go/no-go spike (TODOS.md C.1) runs.diff --git a/wip/autofix/deferred-checkpoint-a-review-items.md b/wip/autofix/deferred-checkpoint-a-review-items.mdnew file mode 100644index 000000000..6f52c7642--- /dev/null+++ b/wip/autofix/deferred-checkpoint-a-review-items.md@@ -0,0 +1,32 @@+# Deferred / reviewed items from Checkpoint A code review++Clean-context multi-angle review of the `sync-controller-inputs` diff (`git diff <phase-base>..HEAD`). The confirmed correctness defects were fixed in the same checkpoint (see below); the items here are the design-tradeoff and forward-looking findings that are real but deliberately NOT acted on now, per the no-over-engineering rule.++## Fixed in this checkpoint (not deferred — recorded for completeness)++- **Inline-table canonicalizer crashed on non-bare keys and nested values.** The old `_canonical_inline_table` assembled TOML text with raw `f"{key} = {value}"`, assuming every key is a bare unquoted key and every value a scalar. A supported dotted input key (`"cv.name"`, allowed by `validate_input_name` and used in real fixtures) raised `KeyAlreadyPresent`; a nested inline-table value (a pipe authored as a single-line inline table, patched by `match-sequence-output`) raised `UnexpectedCharError`. Fixed by letting tomlkit itself render keys/values (native `inline_table()` assignment quotes non-bare keys, nests, and preserves each value's own string style) and splicing only the outer brace padding. Pinned by `test_dotted_input_key_survives_format` and `test_set_output_on_whole_pipe_inline_table_survives_format` (renamed in Phase A′, when the hand-rolled canonicalizer was replaced by the `format_mthds` pass — the crash modes now can't occur because the real parser handles valid TOML).+- **`declared_inputs` was missing from `PipeValidationError.desc()`** while `expected_inputs` was shown — the field was added as the diff counterpart, so the asymmetry hid the "before" side in logged errors. Added the symmetric line.++## 1. Keep the exhaustive `match self` classifier idiom (reviewed, not a defer)++Several angles flagged that `is_controller_input_drift` and `is_inadequate_output` each hand-enumerate the whole `PipeValidationErrorType` set, so a new member must be classified in every `is_*` property. This is the sanctioned house style (`.claude/rules/python-standards.md`: no `case _:`, so pyright's exhaustiveness check *forces* a decision on every new member) — a `{error_type: fix_code}` mapping would trade that compile-time guarantee for silence. Keeping the idiom is the correct call, not a deferral. Revisit the ergonomics only if wave-2 rules push the classifier count high enough that the per-member edit cost outweighs the guard — a real refactor with its own design, not a spike edit.++## 2. Trivia-preservation is solved twice (DISSOLVED by Phase A′)++~~`applier._canonicalize_mutated_inline_table` transplants four trivia fields; `tools/misc/toml_sync.set_nested_value` swaps the whole trivia object.~~ **Moot as of Phase A′:** `_canonicalize_mutated_inline_table` is deleted — the applier no longer preserves inline-table trivia at all, because it no longer re-emits inline tables. `format_mthds` owns canonical spacing, and block-table comments survive by tomlkit's in-place mutation. The only remaining trivia handling is `toml_sync`'s, outside the fix pipeline. Nothing to consolidate.++## 3. Per-`table_path` batch canonicalization (DISSOLVED by Phase A′)++~~`_canonicalize_mutated_inline_table` runs after every `SET_KEY`/`DELETE_KEY`, re-canonicalizing the whole table per op.~~ **Moot as of Phase A′:** there is no per-op canonicalization left in the applier — `apply_fix_ops` is pure DOM mutation, and canonical formatting happens exactly once per file write (`serialize_and_format` → one `format_mthds` pass). The `O(N·K)` concern is gone.++## 4. Micro-duplication in the `_*_for_fix` helpers (accept)++`_expected_inputs_for_fix` and `_declared_inputs_for_fix` repeat the `if not self.is_controller: return None` guard and the one-line `to_bundle_representation(relative_to_domain=self.domain_code)` render. A shared `_render_input_ref` / caller-side guard would save two lines across two tightly-related methods. Small enough to leave; reconsider if a third `_*_for_fix` helper appears.++## 5. Two op-shapes in `_plan_sync_controller_inputs` (early-warning, watch)++The rule emits either one whole-table `SET_KEY` (no `inputs` declared yet) or N per-key `SET_KEY`/`DELETE_KEY` ops (diff an existing table) — the reason `TomlValue` was widened to `TomlScalar | dict[str, TomlScalar]`. Fine for one rule. If a second table-create-vs-patch rule lands (e.g. sync operator config, sync structure fields), factor the create-vs-diff decision into a shared planner helper rather than widening `TomlValue` further per rule. Flagged so wave-2 doesn't accrete op-shapes silently.++## 6. `FixOp.value` wire-schema forward note (cross-repo, defer)++No `pipelex/` consumer serializes `SuggestedFix` to wire format yet, so the `TomlValue` widening (dict-valued ops) is inert here. When a CLI/API surface (mthds/protocol, sibling repo) starts rendering `SuggestedFix`, it must type the value slot as `TomlValue`, not `TomlScalar`, or it will reject the dict-valued `sync-controller-inputs` fix. Extends checkpoint-0 item 1c (additive-field changelog) with the container-value nuance; belongs to the cross-repo schema-sync wave.diff --git a/wip/autofix/deferred-checkpoint-b-review-items.md b/wip/autofix/deferred-checkpoint-b-review-items.mdnew file mode 100644index 000000000..752215da9--- /dev/null+++ b/wip/autofix/deferred-checkpoint-b-review-items.md@@ -0,0 +1,23 @@+# Deferred follow-ups from Checkpoint B (`strip-native-concept-redecl`)++The Phase B review fan-out (Sonnet-5 `/code-review` on the Phase B diff, no inherited context) surfaced two items. Neither is a defect; both are recorded here and closed for Phase B.++## 1. Comment reflow when deleting a `[concept.X]` table with a leading comment++**What it is.** `DELETE_KEY` on `["concept"]` removes the redeclared concept via tomlkit's `del`. When a *standalone comment line* sits directly above the deleted `[concept.X]` table, tomlkit reattaches that comment as leading trivia of the **next** surviving element (the successor table). `format_mthds` reflows spacing but does not reposition comments, so the comment ends up annotating unrelated content — a stale, potentially misleading comment describing removed illegal content now appears above legitimate content.++**Why it's not fixed.**++- The guarantee we make is that comments on *untouched* content survive; a comment sitting **on the deleted concept** is the only thing that can dangle.+- Repositioning/removing a deleted node's leading trivia is fiddly tomlkit container-body work, disproportionate to a purely cosmetic artifact.+- The autofix output is whole-file canonical MTHDS that the author reviews (and CI reformats). A leftover comment is visible in that review, not silently shipped.++**What we did instead.** Pinned the behavior with a characterization test (`test_leading_comment_on_deleted_table_reflows_onto_successor` in `tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py`) so it is explicit and regression-caught rather than an undocumented surprise, and kept the golden fixtures clean (comments placed on surviving content, which is what the fix guarantees to preserve).++**If revisited.** A general "strip a deleted node's leading standalone comment(s)" pass in the applier would remove the artifact for every delete-shaped fix (this rule and any future one). Weigh it when a delete-shaped fix first ships to a human-facing surface (master-plan step 5), not before.++## 2. `_extract_wrapped_native_concept_redeclaration_error` shares the shape of `extract_wrapped_pipe_validation_error`++Both do the same three steps (check `error["type"] == "value_error"`, pull `ctx["error"]`, `isinstance`-narrow). The reviewer flagged a possible generic `TypeVar`-based unwrap helper serving both, then judged it "not a real problem — a small, readable, well-documented function."++**Decision: no action.** Two readable call sites do not justify a generic helper; the same "keep the house style, don't over-abstract the enum-match/unwrap duplication" call was made at Checkpoint A. Revisit only if a third structural-unwrap site appears.diff --git a/wip/autofix/deferred-checkpoint-c-review-items.md b/wip/autofix/deferred-checkpoint-c-review-items.mdnew file mode 100644index 000000000..8c2d8d100--- /dev/null+++ b/wip/autofix/deferred-checkpoint-c-review-items.md@@ -0,0 +1,35 @@+# Deferred follow-ups from Checkpoint C (`strip-namespace`)++The Phase C review fan-out (multi-agent `/code-review` on the staged strip-namespace diff) surfaced eight findings. Three were fixed immediately (applier crash on `OutOfOrderTableProxy`/`InlineTable`, the `main_pipe` retarget collision gate in the categorizer, the cross-file rename collision guard in the fix loop). The two below are confirmed limitations deliberately deferred for later review; the cleanup notes at the end are recorded for completeness.++## 1. `main_pipe` strip can rewrite to a pipe that does not exist++**What it is.** The `main_pipe` strip enrichment never verifies that the bare target pipe exists — the `main_pipe` field validator runs before `pipe` validates, and the categorizer gate we added only suppresses the *retarget* case (both dotted and bare declarations present). With `domain = "greetings"`, `main_pipe = "greetings.helo"` (typo'd tail, no `[pipe.helo]` anywhere), the tail is valid snake_case so the enrichment fires, the SAFE fix rewrites the file to `main_pipe = "helo"`, and re-validation fails with the model validator's "Main pipe 'helo' could not be found" — an unfixable error. The user's file was mutated by a fix advertised as SAFE, the bundle stays invalid with a *different* error, and the author's original over-qualified spelling (which pointed at what they meant) is gone from the file.++**Why it's deferred, not fixed.**++- The natural home for an existence check is the categorizer's document-level gate (it holds the raw bundle dict, same as the retarget gate). But "exists" is subtler than it looks: the raw `pipe` dict at that point may itself contain dotted keys that a *sibling* strip-namespace fix will rename in a later iteration — `main_pipe = "d.hello"` with only `[pipe."d.hello"]` declared is exactly the convergent happy path (both strip to `hello` across iterations), and a naive "bare target must already exist" check would kill it.+- The correct predicate is roughly "the bare tail exists as a key OR the dotted code itself exists as a key (its rename will materialize the bare target)". That needs deciding together with finding #5's one-error-per-pass behavior, since convergence order is what makes the second disjunct sound.+- The failure mode leaves a *loud* residual error naming the missing pipe, not silent wrong execution — bad UX, not a correctness trap like the retarget case was.++**If revisited.** Extend `_main_pipe_strip_would_retarget` in `validation_error_categorizer.py` into a broader `_main_pipe_strip_is_safe` gate implementing the two-disjunct predicate above, and pin the typo'd-tail scenario (enrichment suppressed, file untouched) plus the dotted-declaration happy path (still converges) in `test_strip_namespace_enrichment.py`.++**Related (PR #1031, cubic P2 — same defect, second site).** A second review flagged that the `main_pipe` strip `SET_KEY` is not filtered by the fix loop's cross-file sibling-collision gate (`_is_cross_file_colliding_rename` / `_split_cross_file_rename_collisions`, `fix_loop.py:112-141`), which only recognizes `RENAME_TABLE_KEY` ops. The *stated* impact — silently retargeting `main_pipe` to a sibling file's pipe — is a **false positive**: `validate_main_pipe` is bundle-local and runs per-file before any library merge, so a stripped `main_pipe` can never resolve to a sibling's pipe; it always fails loudly with "could not be found". But the underlying gap is real and benign: in a two-file same-domain library (file A `[pipe."d.hello"]` + `main_pipe = "d.hello"`, sibling B `[pipe.hello]`), iteration 1 drops the paired declaration rename (cross-file collision) yet keeps and applies the `main_pipe` `SET_KEY`, writing an orphaned `main_pipe = "hello"` to file A before iteration 2 bails loudly on the still-present dotted declaration. Same benign family as this item (pointless file mutation, loud residual — not silent corruption). **Key coupling for the fix:** the categorizer-only gate proposed above does **not** cover this case — its second disjunct ("the dotted code exists as a key, so its rename materializes the target") is satisfied here, but the categorizer can't see that the rename will be blocked cross-file. So the suppression must **also** live in the fix loop's `_split_cross_file_rename_collisions` (`fix_loop.py:120`), where `sibling_pipe_codes` is known — e.g. also drop a root `main_pipe` `SET_KEY` whose value is in `sibling_pipe_codes` (or whose paired declaration rename was just dropped as colliding). The clean fix therefore spans **both** the categorizer and the fix loop.++## 2. One declaration rename per iteration caps convergence at `max_iterations` dotted keys++**What it is.** `validate_pipe_keys` (a `mode="before"` field validator) raises on the *first* invalid pipe key, so each validation pass surfaces at most one strip-namespace declaration rename. A bundle with more over-qualified `[pipe."domain.xxx"]` keys than `max_iterations` (default 5) exhausts the loop and returns `is_valid=False` with bail_reason "max_iterations reached without convergence" and a partially-rewritten file — even though every remaining error was mechanically fixable by the same rule.++**Why it's deferred, not fixed.**++- It is a completeness limitation, not a misfix: every rename applied is individually correct, and the bail is loud and explains itself.+- The same one-error-per-pass shape is already an accepted convergence pattern in this codebase (`strip-native-concept-redecl` converges error-by-error the same way; pinned by `test_native_redeclarations_converge_error_by_error`).+- The clean fix is to collect *all* invalid pipe keys in one pass and raise an aggregate (or plan one fix with multiple rename ops, the way `sync-controller-inputs` repairs all input drift at once). That changes the raise-site contract (`InvalidPipeCodeSyntaxError` carries one offending code) and the categorizer/planner discrimination protocol with it — a coherent follow-up chunk, not a patch to sneak in during review triage.++**If revisited.** Either (a) make `validate_pipe_keys` accumulate offending keys and raise a multi-code error the planner turns into one multi-op fix, or (b) simply raise `max_iterations` for the declaration-rename rule. (a) is the solid fix; (b) is a stopgap that just moves the cliff.++## Cleanup notes recorded, no action taken++- The declaration-vs-`main_pipe` raise site is inferred implicitly twice (pydantic `loc[0]` in the categorizer, `pipe_code` None-ness in the planner) instead of riding the typed exception explicitly. An explicit marker on `InvalidPipeCodeSyntaxError` would remove both inference points.+- `_strippable_same_domain_pipe_code` re-implements dotted-ref parsing that `QualifiedRef.parse()` provides; two parsers for one grammar can drift.+- `existing_pipe_codes` in `validate_pipe_keys` is built eagerly on every bundle validation even when all keys are valid; a lazy build would keep the happy path allocation-free.diff --git a/wip/autofix/deferred-checkpoint-d-review-items.md b/wip/autofix/deferred-checkpoint-d-review-items.mdnew file mode 100644index 000000000..04f1e2d82--- /dev/null+++ b/wip/autofix/deferred-checkpoint-d-review-items.md@@ -0,0 +1,35 @@+# Deferred follow-ups from Checkpoint D (Phase D step exit — PR #1031)++The PR #1031 review surfaced one unresolved thread (codex, P2). It is a **confirmed** but **low-severity, fail-safe** edge-case bug whose proper fix requires a design decision, so it is deferred here with the thread left open rather than patched during triage. (The earlier "PR #1031, cubic P2" cross-reference in `deferred-checkpoint-c-review-items.md` is a *different* finding — the `main_pipe` `SET_KEY` cross-file gap — not this one.)++## 1. Dotted-key controller inputs misfire `sync-controller-inputs`++**Reporter.** codex (P2), on `pipelex/pipeline/fixes/planner.py:94-98` (`_plan_sync_controller_inputs`).++**What it is.** When a controller input is authored with a **quoted dotted key** — e.g. `inputs = { "cv.name" = "Text" }` on a `PipeSequence` — the input-sync fix targets the wrong TOML key and either skips or duplicates.++**Mechanism (all cited).**++- `InputStuffSpecs.validate_concept_codes` collapses the authored key `cv.name` → root `cv` via `get_root_from_dotted_path` (`pipelex/core/pipes/inputs/input_stuff_specs.py:55`), so `self.inputs.root` is keyed by root names only.+- `_declared_inputs_for_fix` / `_expected_inputs_for_fix` read those already-normalized root keys (`pipelex/core/pipes/pipe_abstract.py:301-304`, `279-291`). The authored dotted key is gone before the pure planner runs.+- The planner emits ops keyed on `cv` (`planner.py:94` SET, `planner.py:98` DELETE). The applier matches the **literal** TOML key (`applier.py:198` for SET, `207-208` for DELETE). Because `cv` ≠ `"cv.name"`, the op misses.++**The authoring form is supported, not a mistake.** `is_valid_input_name` explicitly permits dotted (sub-attribute) input names, and `test_fix_applier_inputs_sync.py:94` (`test_dotted_input_key_survives_format`) authors exactly `inputs = { "cv.name" = "Text", cv = "Curriculum", note = "Text" }` on a `PipeSequence`, calling `"cv.name"` "a supported sub-attribute name." That test only covers deleting an *unrelated* sibling key, so this drift scenario is real and untested. (Note: only the **quoted** form is reachable — an unquoted `cv.name = "Text"` nests to `{cv: {name: ...}}`, whose dict value fails `PipeBlueprint.inputs: dict[str, str]` at blueprint parse. codex scoped the claim correctly.)++**Why it fails safe (this is the reason it is low-severity, not a correctness trap).**++- **Case A — extraneous dotted input.** `DELETE_KEY cv` finds no `cv` key (only `"cv.name"`) → **skipped** (`applier.py:207-208`) → `any_op_applied=False`, no file write → the same fix fingerprint is re-proposed next iteration → the loop bails **loudly** with `is_valid=False`, bail_reason "no progress" (`fix_loop.py:191-203`). The file is untouched and the error is correctly reported unfixed.+- **Case B — drifting dotted input (concept/multiplicity mismatch).** `SET_KEY cv=<new>` **appends** `cv` beside the existing `"cv.name"` (`applier.py:198`). On re-validation `InputStuffSpecs` re-collapses both to root `cv`; iteration order makes the later (`cv=<new>`, correct) value win, so validation **passes** — but a stale/shadowed `"cv.name"` line is left in the file. It is valid TOML and invisible to the `EXTRANEOUS_INPUT_VARIABLE` check (which iterates `self.inputs.variables`, i.e. root keys — `pipe_abstract.py:385`), so it never re-errors.+- **No path** reports an invalid bundle as valid, crashes, or corrupts the file. Even a hypothetical key-order flip in Case B would just fail validation and re-hit the same no-progress bail. Worst observed outcome: a loud "couldn't fix" (Case A) or a cosmetic stale line in an otherwise-correct, valid file (Case B).++**Why deferred, not fixed now.** The planner is **structurally blind** to the dotted case — normalization to `cv` is lossy and irreversible before the planner ever sees the data, and `declared_inputs={"cv": ...}` is indistinguishable from a genuine bare `cv` declaration. So the planner cannot detect or guard it without disabling *all* controller-input fixes. That leaves three real options, and choosing among them is a design decision:++1. **Applier-side root-aware resolution (recommended).** In `_apply_one_op` (`applier.py:191-210`), when `table_path` ends in `inputs`, resolve any existing literal key whose `get_root_from_dotted_path(key) == fix_op.key` before acting: DELETE removes that dotted key; SET replaces/renames it in place instead of appending a sibling. Bounded and local, but it special-cases an intentionally **path-generic** applier (see its module docstring) — so it needs a conscious "yes, `inputs` tables get special treatment" call.+2. **Carry the authored key through.** Preserve the un-normalized requirement expression from `InputStuffSpecs` into the error data so the planner can target the literal key. This ripples widely — everything downstream relies on `self.inputs.root` being root-keyed — and touches the error model plus all three raise sites (`pipe_abstract.py:339-340`, `380-381`, `394-395`). Heaviest option.+3. **Accept the edge case.** Given it already fails safe, document it and move on.++Recommendation: option 1 if we decide dotted controller inputs are worth first-class fix support; otherwise option 3. Option 2 is out of proportion to the payoff.++**If revisited.** Implement option 1 in `applier.py`, and pin both cases in `test_fix_applier_inputs_sync.py`: Case A (extraneous dotted key actually removed, loop converges instead of bailing) and Case B (drifting dotted key replaced **in place**, no duplicate `cv` line left behind). `test_dotted_input_key_survives_format` is the existing sibling test to sit next to.++**Thread:** https://github.com/Pipelex/pipelex/pull/1031 — codex comment on `pipelex/pipeline/fixes/planner.py:94-98` (left open).diff --git a/wip/autofix/deferred-checkpoint-e-review-items.md b/wip/autofix/deferred-checkpoint-e-review-items.mdnew file mode 100644index 000000000..14332a3d0--- /dev/null+++ b/wip/autofix/deferred-checkpoint-e-review-items.md@@ -0,0 +1,39 @@+# Checkpoint B (step 5 exit) — code-review triage++Exit review for step 5 (`pipelex fix bundle` + the `💡 Suggested fix:` line in `pipelex validate`), branch `feature/Autofix-step5`, diff `git diff 611644e82..HEAD`.++## How this review actually ran++The workflow-backed `/code-review` (high effort) fanned out four finders that pooled **19 candidate findings**, then tried to spawn one verifier per distinct `(file, line)`. **Every verifier agent (13/13) died on an Anthropic session limit** before adjudicating anything — the workflow's headline "No findings survived verification" reflects `verified: 0, refuted: 0`, i.e. the verify stage collapsed, **not** a clean bill of health. So the 19 candidates were triaged by hand against the code (the journal is at `subagents/workflows/wf_48d1dfe9-5f4/journal.jsonl`). The 19 dedupe to 11 distinct issues below.++## Fixed in this branch (confirmed bugs)++These were verified reachable against the code and fixed at checkpoint exit.++1. **mkdocs nav orphan** — `mkdocs.yml`. `docs/tools/cli/fix.md` was added only to the llmstxt plugin's page-title map (the `Reference:` block ~line 269), not to the site `nav:` `CLI Reference` block (~line 489). The page was unreachable from site navigation and `mkdocs build --strict` would flag it. Fix: added `- Fix: tools/cli/fix.md` after `Validate` in the real `nav:`.++2. **`validate` footer not shell-safe** — `error_handlers.py` ~line 367. The actionable `pipelex fix bundle <path> -L <dir>` footer was built by bare f-string interpolation of `bundle_path` and each `-L` dir. A path containing a space rendered a command that splits when copy-pasted (the one-click remediation the feature exists for). Fix: `shlex.quote` each interpolated path.++3. **`fix` still-invalid tip contradicts its own suggested-fix lines** — `_fix_core.py` ~line 120. The still-invalid arm always printed "…they have no deterministic safe fix, so they need a manual edit", but `remaining_errors` routinely carries items **that do** have a `💡 Suggested fix:` line — errors skipped by `--select`/`--ignore`, dropped for being out of write scope, or left by a `max_iterations`/no-progress/collision bail. The shipped integration test `test_select_filter_is_honored_end_to_end` produces exactly this contradiction. Fix: make the tip conditional — when any remaining error still carries a suggested fix, point at the filters / `-L` / bail reason instead of claiming a manual edit is the only option.++4. **`--diff` PipeSignature wording asserts the file is valid** — `_fix_core.py` ~line 94. Under `--diff`, a run that converges to valid-with-pending-signatures printed "Bundle is valid but NOT yet runnable …" in the same non-conditional phrasing as a real write, even though nothing was written and the on-disk bundle is still invalid. Fix: make the pending-signature messaging preview-aware ("would be valid but would still not be runnable").++5. **`--diff` crashes and mislabels on a missing `-L` dir; diverges from the real run** — `_diff_sandbox.py` + `_fix_core.py`. A non-existent `-L` dir makes `shutil.copytree` in `mirror_bundle_for_preview` raise `FileNotFoundError`, which `execute_fix`'s blanket `except FileNotFoundError` mislabels as `"bundle file not found: '<bundle_path>'"` (the bundle exists — the `-L` dir is what's missing) and exits 2. The **real** (non-`--diff`) run tolerates a missing dir (`library_utils.get_pipelex_mthds_files_from_dirs` skips it; `resolve_library_dirs` keeps it in `effective_dirs` so multi-file semantics are unchanged) and still produces a 0/1 verdict. Fix: `mirror_bundle_for_preview` creates an **empty** copy dir for a missing `-L` dir instead of copying it — no crash, the dir contributes no files (matching the real loader), and the 1:1 dir count preserves `is_single_file`, so the preview verdict tracks the real run.++## Deferred (real, but design tradeoffs or niche — not snap-fixed at checkpoint exit)++Per the house pattern (`feedback_defer_design_tradeoff_findings`): findings that are genuine but are design tradeoffs, currently-unreachable latent gaps, or DRY refactors whose correct fix touches a layering boundary — captured here rather than patched reflexively at exit.++- **A. `validate` footer over-counts fixable errors** — `error_handlers.py` ~line 365. `fixable_count` counts every `ValidationErrorItem` carrying a `suggested_fix`, but `pipelex fix`'s loop then drops fixes that are UNSAFE, source-less under multi-file validation (`_safe_fixes`), or target files outside the per-call write scope (`_partition_by_write_scope`). So in ambient/multi-file edge cases (a fixable error whose fix is sourced at a hub-default / `PIPELEXPATH` file, validated with no `-L`) the footer promises "N can be fixed" and the suggested command then bails "outside write scope", applying nothing. **Not reachable in the common single-file, all-safe-rules path** (all shipped rules are SAFE; sources are backfilled). A faithful count would have the renderer re-derive `resolve_library_dirs` + `_safe_fixes` + write-scope — coupling the validate presentation layer to fix-loop internals. **Recommendation:** either (a) soften the footer from a promise to a hint ("may be auto-fixable — try:") — cheap but slightly dilutes the good common-case UX, or (b) factor a shared `count_applicable_fixes(items, *, library_dirs)` helper in the fixes package that both the loop and the footer call, so the promise is exact. Prefer (b) when an UNSAFE rule or heavier multi-file usage ships; until then the over-promise is confined to niche ambient setups.++- **B. `--diff` sandbox copies each `-L` dir separately — no resolved-path dedup** — `_diff_sandbox.py` ~line 71. Each explicit `-L` dir is mirrored into its own `lib_<i>`, so overlapping/duplicate/nested `-L` values (`-L a -L a`, or directory mode `dir/` combined with `-L $PWD/dir`) become physically distinct files that defeat the real loader's resolved-path dedup (`library_manager` collapses them). The preview then reports duplicate pipe/concept declarations and "would still be invalid" (exit 1) while the real run dedupes and converges (exit 0). **Niche** (requires the user to pass overlapping `-L` dirs). Correct fix: dedupe `-L` dirs by resolved path before mirroring and let `to_original` map multiple original roots onto the single copy (the mapping currently assumes one original per copy). Deferred because the multi-origin `to_original` change deserves its own tests, and the trigger is unusual. Note the adjacent question of whether `resolve_bundle_target`'s directory auto-injection should itself dedupe against an explicit `-L` (it string-compares the injected relative dir against an absolute `-L`).++- **C. `resolve_bundle_target` duplicated across the human and agent CLIs** — `pipelex/cli/commands/bundle_path_resolver.py` re-implements `pipelex/cli/agent_cli/commands/bundle_path_resolver.py` near-verbatim (same `expanduser`, `DEFAULT_BUNDLE_FILE_NAME` precedence, single-`*.mthds` glob fallback, library-dir injection), differing only in error presentation (typer red-err vs the agent's structured error). ~60 lines now live twice; a future change to the resolution rules applied to one twin silently diverges the surfaces, breaking the "fix patches exactly the file validate judged" invariant. **Recommendation:** extract a shared core that resolves and raises a typed `BundleTargetResolutionError`, each CLI rendering it in its own presentation. Deferred as a DRY refactor, not a live bug (behavior is currently identical). This is the same shape as the step-3/4 shared-resolver work; fold it into the next surfacing wave rather than a checkpoint-exit patch.++- **D. `_reject_invalid_rule_filters` duplicated across the human and agent CLIs** — `pipelex/cli/commands/fix/bundle_cmd.py` duplicates the identically-named check in `pipelex/cli/agent_cli/commands/fix/bundle_cmd.py` (same `--select`/`--ignore` mutual-exclusion rule and `KNOWN_FIX_CODES` set-math), differing only in presentation. Same risk and remedy as C: extract the set-math into a shared helper returning the violation, each CLI presenting it. Deferred with C.++- **E. Dry-run diagnostic can be dropped in `fix`'s still-invalid arm** — `_fix_core.py` still-invalid rendering. `validate`'s human handler re-prints `exc.dry_run_error_message` alongside categorized errors (the shared items builder projects the dry-run channel only when it is the sole failure channel). `fix`'s still-invalid arm renders only `remaining_errors` (same builder output) and has no equivalent guard, and `FixBundleResult` does not carry `dry_run_error_message` separately. **Currently unreachable:** `validate_bundle`'s raise arms never produce categorized errors and a dry-run message together (the finder acknowledged this). Latent only. Fixing it means adding a `dry_run_error_message` field to `FixBundleResult` and threading it — more than a rendering tweak, for a case the code can't currently hit. Deferred as a latent-consistency item; revisit if `validate_bundle` ever raises the mixed shape.++## Considered and rejected (not a defect)++- **`ValidationErrorCategory.is_dry_run` property is "speculative API for one call site"** — `base_exceptions.py`. A finder argued the 4-arm exhaustive-match property should be an inline `item.category == ValidationErrorCategory.DRY_RUN`. **Rejected:** this contradicts the repo's Python standard (`.claude/rules/python-standards.md` → "Never test equality to an enum value: use match/case … add `@property` methods to the enum class such as `is_foobar()`"). The property is the house-preferred form precisely so that adding a `ValidationErrorCategory` member makes the linter flag every site that must handle it. Keeping it.diff --git a/wip/autofix/master-plan.md b/wip/autofix/master-plan.mdnew file mode 100644index 000000000..8739f3ffb--- /dev/null+++ b/wip/autofix/master-plan.md@@ -0,0 +1,94 @@+# Autofix — executive master plan++Deterministic auto-fixing of `.mthds` validation errors. Full rationale and architecture: [suggested-fixes-design.md](suggested-fixes-design.md). Approved decisions: fixes attach to validation diagnostics (D1), runtime-only wire first (D2), wave 1 targets agent CLI + skills (D3), pruning cut from wave 1 (D4).++**Guiding principle:** one validation engine feeds every surface. Validators state what they expected; a planner turns that into structured `suggested_fix` payloads on the report; appliers and commands are thin. Fix ops are contract, rendered diffs are presentation.++## Where we are++**Step 1 (spike) is DONE** — PR #1027 vs dev, merge-ready. The full chain is proven on one rule (`match-sequence-output`): enriched typed error → planner → tomlkit applier → convergence loop, all TDD, golden format-preservation tests pinning tomlkit's in-place style preservation. The `suggested_fix` payload already rides `pipelex-agent validate bundle --format json` and the `/validate` API 422 body, because the planner hooks into the one shared `build_validation_error_items` builder. Checkpoint findings are recorded in the design doc; deliberate deferrals in [deferred-checkpoint-0-review-items.md](deferred-checkpoint-0-review-items.md).++**Step 2 (wave-1 rule breadth) is DONE** — on the stacked branch `feature/Autofix-step2` (PR #1031). All three wave-1 rules landed, each a deliberately different fix *shape*: `sync-controller-inputs` (multi-op in-place table sync, Phase A), `strip-native-concept-redecl` (delete-shaped, first blueprint channel, Phase B), and the stretch `strip-namespace` (position-preserving rename, Phase C — **GO, shipped**). Mid-step, Phase A′ swapped the applier's hand-rolled canonicalization for the in-process `pipelex_tools.format_mthds` backend (core runtime dep). **Abstraction verdict (CHECKPOINT 1): `SuggestedFix`/`FixOp` survived all four shapes with no structural change** — the only wire-level edit was widening `TomlValue` (the type of `FixOp.value`) to admit a flat scalar dict; the feared array-of-tables `table_path` extension was never needed. Full verdict + carried-forward warts in the design doc's "Step-2 exit — abstraction verdict" section; per-checkpoint deferrals in `deferred-checkpoint-{a,a-prime,b,c,d}-review-items.md`. Reviewer's guide: [step2-reviewers-guide.md](step2-reviewers-guide.md) (archived from the worktree-root `TODOS.md`).++**Steps 3 (hardened loop) and 4 (agent apply surface) are DONE** — merged together as PR #1035 (`feature/Autofix-step4-Agnt-Apply`). Step 3 replaced the spike's drop-everything scoping guard with real multi-file targeting (source backfill at the translate funnel, resolved-dirs single-file gate, write-scope policy, per-file apply with `files_written`); step 4 shipped `pipelex-agent fix bundle` with the CLI-free markdown renderer and full test coverage. The PR review triage fixed two confirmed bugs and deferred one inert finding to [pr-1035-review-notes.md](pr-1035-review-notes.md).++**Step 5 (human CLI surfacing) is DONE** — `pipelex fix bundle` (including the `--diff` preview), the `💡 Suggested fix:` lines + actionable footer in `pipelex validate`, docs, and changelog all landed on branch `feature/Autofix-step5`; detailed plan + decisions: [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md). The CHECKPOINT B exit review fixed five confirmed bugs on the branch and deferred five tradeoffs — triage in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md). The branch is PR-ready; **step 6 (release train) is next**, and its CHANGELOG must still name the additive `suggested_fix` wire field in `/validate` payloads (deferred item 1c) plus regenerate the conformance fixture (deferred item 2).++## Sequencing doctrine (decided 2026-07-07)++- **The agent surface is the proving ground.** Agent JSON output and tests are where the `SuggestedFix`/`FixOp` shape gets iterated freely — machine consumers we control, no format freeze. This is D3 operationalized.+- **The human CLI comes last in wave 1, gated on two testable bars** — not on a "complete fixer" (completeness is a moving target and invites big-bang scope):+ 1. The abstraction has been stress-tested by rules of *different shapes* — not just another `set_key`, but in-place table sync and delete ops — so the wire shape and the `description` wording are known-stable before humans see them.+ 2. The apply command exists, so a human-facing hint has an action behind it (`pipelex fix`), not a "go hand-edit this" teaser.+ Rationale: a `💡 Suggested fix` line that appears for exactly one error class reads worse than no hints at all, and anything shown to humans becomes user-facing output we can no longer reshape freely.+- **Known plumbing fact for the human step:** the human renderer (`_display_validation_error_details` in `pipelex/cli/error_handlers.py`) does NOT flow through `build_validation_error_items` — it iterates raw `PipesAndConceptValidationErrorData` and prints fields by hand. Surfacing fixes there is a deliberate addition (call the planner from the renderer, or route it through the shared items), not free-riding on existing wiring.++## Steps++### 1. Spike — prove the chain end-to-end — **DONE (PR #1027)**++One rule through all layers, no CLI command, driven by tests. Exit criteria met: chain proven, format preservation demonstrated by golden tests, design doc updated with findings. Reviewer's guide: [spike-reviewers-guide.md](spike-reviewers-guide.md).++### 2. Wave-1 rule breadth — stress the abstraction — **DONE (PR #1031)**++Detailed implementation plan with progress checkboxes: was `TODOS.md` at the worktree root, now archived as [step2-reviewers-guide.md](step2-reviewers-guide.md).++Add the remaining wave-1 rules, in this order (each is a different fix *shape*, which is the point):++- **`sync-controller-inputs`** — `MISSING_INPUT_VARIABLE` / `EXTRANEOUS_INPUT_VARIABLE` / `INPUT_STUFF_SPEC_MISMATCH` on a controller pipe → in-place sync of the `inputs` table with `needed_inputs()`. First non-`set_key` shape: multiple ops per fix, add/update/delete inside an existing table without rebuilding it (the old branch's rebuild destroyed comments/style). Carries the two rule guards from the design doc: **optionals markers** (preserve the author's `?`/`!` when concept+multiplicity already match; derive markers only for added inputs) and **prerequisite-clean** (suppress the fix when co-errors like `UNRESOLVED_PIPE_DEPENDENCY`/`UNRESOLVED_CONCEPT` on the same pipe make `needed_inputs()` untrustworthy — the loop picks it up next round).+- **`strip-native-concept-redecl`** — blueprint-level error for a redeclared native concept → `delete_table` / `delete_key` for `[concept.X]` or inline `concept.X = "..."`. First *blueprint-channel* fix (the spike only enriched the pipe-validation channel) and first delete-shaped fix in production.+- **`strip-namespace` (stretch)** — same-domain dotted pipe codes → position-preserving rename + rewrite of internal refs (`steps`, `branches`, `branch_pipe_code`, `outcomes`, `default_outcome`, `main_pipe`). Gated on **position-preserving rename mechanics** in tomlkit (the old branch's `del`+re-add reordering bug is the thing to avoid); if rename doesn't land clean, this rule stays out of wave 1. When rename lands, also add `new_key` to the loop fingerprint (deferred item 1b).++Exit (**CHECKPOINT 1**) — **met:** all wave-1 rules green with planner suppression tests + golden format-preservation tests; the explicit **abstraction verdict** is recorded in the design doc ("Step-2 exit — abstraction verdict") — `SuggestedFix`/`FixOp` survived multi-op, delete, blueprint-channel, **and** rename fixes with no structural change (only an additive `TomlValue` widening). **strip-namespace decision: GO — shipped** (position-preserving rename via tomlkit's `Container._replace`; `RENAME_TABLE_KEY` proven end-to-end; the array-of-tables `table_path` extension it was gated on turned out never to be needed).++### 3. Hardened loop — real multi-file targeting++Detailed design + working plan (shared with step 4): [step3-step4-hardened-loop-and-agent-apply.md](step3-step4-hardened-loop-and-agent-apply.md), on the stacked branch `feature/Autofix-step4-Agnt-Apply`.++Replaces the spike's conservative scoping guard (source-less fixes are simply dropped under `library_dirs`). Deferred items 0 and 1 from checkpoint 0:++- Thread the declaring file into enriched errors — set `file_path` or better yet `source` at the raise sites, so `SuggestedFix.source` is actually populated and the loop's file check stops being dead code.+- Derive `is_single_file` from the **resolved** effective dirs (`resolve_library_dirs`), fixing both wrong directions of the current raw-arg check (`[]` is documented single-file but treated as multi; `None` can fall through to hub defaults/`PIPELEXPATH` and load other files while being treated as single).++Ships behind CHECKPOINT 1. Exit: fixes apply correctly across multi-file bundles, targeting the declaring file only; the drop-everything guard is gone.++### 4. Agent apply surface — `pipelex-agent fix bundle`++Detailed design + working plan (shared with step 3): [step3-step4-hardened-loop-and-agent-apply.md](step3-step4-hardened-loop-and-agent-apply.md).++Thin command over `fix_bundle_file`: two-stream output per the workspace output conventions (`--format`/`--error-format`, JSON contract carrying `FixBundleResult` — is_valid, iterations, fixes_applied, remaining_errors, bail_reason; markdown rendering for the agent as presentation). e2e CLI snapshot tests. This is the milestone where an agent can run validate → fix → re-validate entirely from the CLI. Exit: command shipped on the agent CLI, snapshots green.++### 5. Human CLI surfacing — gated on steps 2 + 4 — **DONE (branch `feature/Autofix-step5`, PR-ready)**++Detailed implementation plan with progress checkboxes: [step5-human-cli-surfacing.md](step5-human-cli-surfacing.md). Checkpoint B triage: [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md).++Both gates from the sequencing doctrine are now met. Two pieces, landed together for symmetry:++- `pipelex fix` (human command) wrapping the same loop with human-rendered output.+- `💡 Suggested fix:` line per fixable error in `pipelex validate`'s error rendering (via the planner from the human renderer path — see plumbing fact above), showing `SuggestedFix.description` only (ops stay machine-facing).++Exit: a human can see the suggestion in `validate` and apply it with `fix`, with output that names every change made.++### 6. Ship wave 1++Release train: CHANGELOG entry (must mention the **additive `suggested_fix` wire field** now surfacing in `/validate` API payloads — deferred item 1c — plus the new commands), docs page in `docs/`, cut the pipelex release. Post-release follow-through: regenerate the conformance fixture that pins the `/validate` error body (deferred item 2, sibling `conformance/` repo) and bump the pipelex-api pin when the runner picks the version up. Exit (**CHECKPOINT 2**): released; hand-off list for wave 2 recorded.++### 7. Skills uptake++Update the `mthds-fix` skill (and the pipelex-plugins equivalent) to run deterministic `fix` before manual LLM editing. Cross-repo, cheap, gated on step 6's release.++### 8–10. Wave 2 (each gets its own plan when it starts)++- **Protocol promotion**: `suggested_fix` becomes a formal MTHDS protocol surface — spec sections in `docs/specs/`, conformance arm, schema sync to downstream copies (mthds, mthds-js, mthds-python).+- **Remote surfaces**: API `POST /fix` on pipelex-api, MCP `mthds_fix` tool — thin wrappers over the same engine/report; the markdown renderer already lives CLI-free for this reason.+- **Editor**: VS Code `CodeActionProvider` (first code action in the extension), quick fixes keyed on `diag.code = error_type` with fix payloads riding the existing validation backends.++These are independent of each other once wave 1 has shipped and can be re-prioritized freely.++### Later++Pruning rules (`prune-unreachable`, `prune-unused-concepts`) resurrected as opt-in lint warnings with attached fixes (D4 — they're cleanups, not fixes); further rules as validator enrichment makes them deterministic.++## Sequencing summary++Step 2 → 3 → 4 are the wave-1 engine-and-agent track and land in that order (3 may overlap 2). Step 5 is deliberately gated on 2 + 4, never earlier. Step 6 ships the lot; 7 follows the release. Each step gets its own detailed TODOS-style plan when it starts — this document stays the map.diff --git a/wip/autofix/old-plan-to-auto-fix.md b/wip/autofix/old-plan-to-auto-fix.mdnew file mode 100644index 000000000..1d702a09a--- /dev/null+++ b/wip/autofix/old-plan-to-auto-fix.md@@ -0,0 +1,384 @@+# Strategy: `pipelex fix` / `pipelex-agent fix` command++## Goal++A new standalone CLI command that auto-fixes deterministic issues in `.mthds` bundles, similar to `ruff check --fix`. Operates on bundle files only, accepts a list of paths.++Tier 1 only: all fixes are deterministic, no LLM involved, no iteration loop.++## CLI surface++### `pipelex-agent fix`++```+pipelex-agent fix my_method.mthds # apply default fixes, show diff on stderr, write file+pipelex-agent fix my_method.mthds other.mthds # fix multiple bundles+pipelex-agent fix my_method.mthds --stdout # output fixed file to stdout (for agents)+pipelex-agent fix my_method.mthds --select strip-namespace,sync-controller-inputs+pipelex-agent fix my_method.mthds --ignore match-sequence-output+pipelex-agent fix my_method.mthds --prune # opt-in: also run prune-unreachable + prune-unused-concepts+```++### `pipelex fix`++```+pipelex fix my_method.mthds # fix single bundle, show diff, write file+pipelex fix *.mthds # fix all bundles via shell glob+pipelex fix my_method.mthds --stdout # fixed file to stdout+pipelex fix my_method.mthds --prune # opt-in pruning+```++### Rule categories++Rules are split into two groups with different defaults:++| Group | Rules | Default |+|-------|-------|---------|+| **Correction rules** | `strip-namespace`, `strip-native-concept-redecl`, `sync-controller-inputs`, `match-sequence-output`, `fix-list-notation` | ON — always applied unless `--ignore`'d |+| **Pruning rules** | `prune-unreachable`, `prune-unused-concepts` | OFF — require `--prune` or explicit `--select` |++`--prune` is a shorthand for `--select prune-unreachable,prune-unused-concepts` on top of the default correction rules. It can combine with `--ignore` to still exclude specific correction rules.++`--select` and `--ignore` are mutually exclusive.++### Output behavior++| Mode | stdout | stderr | File |+|------|--------|--------|------|+| Default | JSON result with `fixes_applied` array | unified diff of changes | written in-place |+| `--stdout` | fixed `.mthds` content | unified diff + JSON diagnostics | untouched |++When multiple bundles are passed, `--stdout` is an error (ambiguous output). Each bundle is fixed independently; the JSON result contains a per-bundle summary.++The diff is always shown on stderr when fixes are applied. Suppress with `--quiet`.++### JSON output (agent CLI)++Single bundle:++```json+{+ "success": true,+ "bundle_path": "/path/to/bundle.mthds",+ "fixed": true,+ "fixes_applied": [+ {+ "fix_code": "strip-namespace",+ "pipe_code": "my_domain.generate_report",+ "message": "Stripped same-domain prefix 'my_domain.' from pipe code",+ "line": 12+ },+ {+ "fix_code": "sync-controller-inputs",+ "pipe_code": "run_pipeline",+ "message": "Synced inputs with needed_inputs(): added 'topic', removed 'unused_var'"+ }+ ],+ "remaining_errors": [...],+ "validated_pipes": [...]+}+```++Multiple bundles:++```json+{+ "success": true,+ "bundles": [+ {+ "bundle_path": "/path/to/a.mthds",+ "fixed": true,+ "fixes_applied": [...],+ "remaining_errors": []+ },+ {+ "bundle_path": "/path/to/b.mthds",+ "fixed": false,+ "fixes_applied": [],+ "remaining_errors": [...]+ }+ ]+}+```++When no fixes are needed and validation passes, `fixed: false` with empty arrays.++### Fixability annotations on `validate` errors++Independently of the `fix` command, the existing `pipelex-agent validate` output gains `fixable`/`fix_code` annotations per validation error, so agents know which errors are auto-fixable:++```json+{+ "validation_errors": [+ {+ "category": "pipe_validation",+ "error_type": "MISSING_INPUT_VARIABLE",+ "pipe_code": "my_pipe",+ "fixable": true,+ "fix_code": "sync-controller-inputs"+ }+ ]+}+```++## Fix rules (Tier 1)++### Correction rules (default ON)++#### `strip-namespace` — Remove same-domain pipe code prefixes++**Triggers on:** Pipe codes containing `.` where the prefix matches the bundle's own domain.++**What it does:** `my_domain.generate_report` -> `generate_report` when the bundle's `domain = "my_domain"`. Applies to:+- Pipe definition keys (`[pipe.my_domain.foo]` -> `[pipe.foo]`)+- `main_pipe` value+- Internal references: `steps`, `branches`, `branch_pipe_code`, `outcomes` values, `default_outcome`++Does NOT strip cross-domain references (different domain prefix) — those are legitimate qualified refs.++**Error types that trigger it:** `INVALID_PIPE_CODE_SYNTAX` (when caused by dotted codes)++**Legacy reference:** `builder_loop.py:590-701` (`_strip_namespace_from_pipe_codes`), specifically the `_should_strip_ref()` helper at lines 648-657 which checks whether the bare code exists in the bundle or the dotted prefix matches the bundle's domain.++#### `strip-native-concept-redecl` — Remove redeclared native concepts++**Triggers on:** Concept definitions whose key matches a built-in native concept (Text, Image, Document, etc.).++**What it does:** Removes the entire `[concept.Text]` section (or inline `concept.Text = "..."`) since native concepts must not be redeclared.++**Error types that trigger it:** Concept factory errors when a declared concept shadows a native one.++**Legacy reference:** `builder_loop.py:556-570` (`_strip_native_concept_declarations`). Uses `NativeConceptCode.values_list()` to identify builtins.++**Current codebase reference:** `pipelex/core/concepts/native/concept_native.py` for `NativeConceptCode`.++#### `sync-controller-inputs` — Align controller pipe inputs with their requirements++**Triggers on:** `MISSING_INPUT_VARIABLE` or `EXTRANEOUS_INPUT_VARIABLE` errors on controller pipes (PipeSequence, PipeParallel, PipeBatch, PipeCondition).++**What it does:** Replaces the `inputs` table of the controller pipe with the exact set from its `needed_inputs()`. This works because controller inputs are fully derivable from the child pipes they orchestrate.++**Legacy reference:** `builder_loop.py:784-811` (`_fix_bundle_validation_error`, MISSING/EXTRANEOUS handler). Calls `pipe.needed_inputs()` and rebuilds the input dict.++**Current codebase reference:**+- `pipelex/core/pipes/exceptions.py:103-104` for `PipeValidationErrorType.MISSING_INPUT_VARIABLE` / `EXTRANEOUS_INPUT_VARIABLE`+- Each controller pipe class exposes `needed_inputs()` which returns the correct input set++#### `match-sequence-output` — Fix sequence output to match last step++**Triggers on:** `INADEQUATE_OUTPUT_CONCEPT` or `INADEQUATE_OUTPUT_MULTIPLICITY` errors on PipeSequence pipes.++**What it does:** Sets the sequence's `output` to the output concept (with multiplicity) of its last step. A sequence's output is always its last step's output — this is a structural invariant.++**Legacy reference:** `builder_loop.py:813-835`. Gets the last step's pipe, reads its output concept and multiplicity, updates the sequence's output.++#### `fix-list-notation` — Add `[]` for multiplicity mismatches++**Triggers on:** Dry-run errors where a PipeCompose field receives `ListContent` but expects a scalar type.++**What it does:** Adds `[]` to the input concept reference. E.g., `inputs = { items = "MyItem" }` -> `inputs = { items = "MyItem[]" }`.++**Legacy reference:** `builder_loop.py:909-966` (`_fix_dry_run_compose_multiplicity_mismatch`) and `builder_loop.py:968-1027` (`_fix_single_multiplicity_mismatch`). Parses the dry-run error message regex to identify the pipe, field, and expected type.++### Pruning rules (default OFF, opt-in via `--prune`)++#### `prune-unreachable` — Remove pipes not reachable from main_pipe++**Triggers on:** Bundle contains pipe definitions that are never referenced from `main_pipe` (directly or transitively).++**What it does:** Walks the call graph starting from `main_pipe`, collecting all reachable pipe codes via:+- PipeSequence -> `steps[*].pipe_code`+- PipeParallel -> `branches[*].pipe_code`+- PipeBatch -> `branch_pipe_code`+- PipeCondition -> `outcomes` values + `default_outcome` (excluding special outcomes)++Removes all pipe definitions not in the reachable set.++**Legacy reference:** `builder_loop.py:340-394` (steps A-B of `_prune_unreachable_specs`). The graph walk is at lines 358-388.++#### `prune-unused-concepts` — Remove concepts not referenced by any pipe++**Triggers on:** Bundle contains concept definitions not referenced by any reachable pipe or by any other used concept (transitively).++**What it does:**+1. Collect concept refs from all reachable pipes (output, inputs, combined_output)+2. Transitively walk concept definitions: if concept A refines concept B or has a structure field referencing concept C, then B and C are also used+3. Remove concept definitions not in the transitive closure++**Legacy reference:** `builder_loop.py:396-424` (steps C-E of `_prune_unreachable_specs`). Helper methods: `_collect_concept_refs_from_pipe_spec` (lines 452-488), `_collect_concept_refs_from_concept_spec` (lines 491-523), `_extract_local_bare_code` (lines 428-450).++## Architecture++### Processing pipeline++```+read .mthds file (raw text)+ |+ v+parse to PipelexBundleBlueprint (existing interpreter)+ |+ v+run validation (existing validate_bundle), catch errors+ |+ v+match errors to fix rules+ |+ v+apply fixes to TOML document (tomlkit, preserves formatting)+ |+ v+re-validate to confirm fixes worked+ |+ v+output: diff + fixed content + JSON report+```++### TOML-level rewriting++The key challenge: fixes must operate on the TOML source (to preserve comments, ordering, formatting) rather than on Python objects.++We use **tomlkit** (already a dependency, used throughout the codebase) which provides a DOM-like TOML representation that preserves comments, whitespace, and inline table style.++### Code layout++```+pipelex/pipeline/+ validate_bundle.py # existing validation logic (unchanged)+ fix_bundle.py # NEW: orchestrator (fix_bundle, fix_bundles)+ fix_rules/ # NEW: one module per fix rule+ __init__.py # registry: ALL_RULES, DEFAULT_RULES, PRUNING_RULES+ base.py # FixRule ABC, FixResult model, FixRuleCategory enum+ strip_namespace.py+ strip_native_concept_redecl.py+ sync_controller_inputs.py+ match_sequence_output.py+ fix_list_notation.py+ prune_unreachable.py+ prune_unused_concepts.py++pipelex/cli/+ agent_cli/commands/+ fix_cmd.py # NEW: pipelex-agent fix+ commands/+ fix_cmd.py # NEW: pipelex fix+```++### Fix rule interface++```python+class FixRuleCategory(StrEnum):+ CORRECTION = "correction" # default ON+ PRUNING = "pruning" # default OFF, opt-in via --prune+++class FixResult(BaseModel):+ fix_code: str+ pipe_code: str | None = None+ concept_code: str | None = None+ message: str+ line: int | None = None+++class FixRule(ABC):+ code: str # e.g. "strip-namespace"+ category: FixRuleCategory+ description: str++ @abstractmethod+ def apply(+ self,+ toml_doc: TOMLDocument,+ blueprint: PipelexBundleBlueprint,+ validation_error: ValidateBundleError | None,+ ) -> list[FixResult]:+ """Mutate toml_doc in place. Return list of fixes applied."""+```++Each rule receives:+- The **tomlkit document** (mutable, preserves formatting) for making changes+- The **parsed blueprint** (read-only) for understanding the bundle structure+- The **validation error** (if any) for matching specific error types++### Execution order++Rules execute in a defined order (not arbitrary) because some fixes enable others:++1. `strip-namespace` — must run first, unlocks correct pipe code resolution for all subsequent rules+2. `strip-native-concept-redecl` — removes invalid concepts before input/output analysis+3. `sync-controller-inputs` — needs correct pipe codes and concepts+4. `match-sequence-output` — needs correct pipe codes+5. `fix-list-notation` — needs dry-run results, runs after structural fixes+6. `prune-unreachable` — cleanup pass, runs after all pipe fixes (opt-in)+7. `prune-unused-concepts` — cleanup pass, runs last, depends on prune-unreachable (opt-in)++### Orchestrator++```python+# In fix_bundle.py+async def fix_bundle(+ mthds_file_path: Path,+ selected_rules: list[str] | None = None,+ ignored_rules: list[str] | None = None,+ prune: bool = False,+ library_dirs: Sequence[Path] | None = None,+) -> FixBundleResult:+ raw_text = mthds_file_path.read_text()+ toml_doc = tomlkit.parse(raw_text)++ # Phase 1: validate to get errors+ blueprint, validation_error = _validate_and_catch(mthds_file_path, library_dirs)++ # Phase 2: resolve which rules to run+ rules = _resolve_rules(selected_rules, ignored_rules, prune)++ # Phase 3: apply fix rules in order+ all_fixes: list[FixResult] = []+ for rule in rules:+ fixes = rule.apply(toml_doc, blueprint, validation_error)+ all_fixes.extend(fixes)++ if not all_fixes:+ return FixBundleResult(fixed=False, fixes=[], original=raw_text, result=raw_text)++ fixed_text = tomlkit.dumps(toml_doc)++ # Phase 4: re-validate to confirm+ remaining_error = _validate_text_and_catch(fixed_text, library_dirs)++ return FixBundleResult(+ fixed=True,+ fixes=all_fixes,+ original=raw_text,+ result=fixed_text,+ remaining_errors=remaining_error,+ )+++def _resolve_rules(+ selected: list[str] | None,+ ignored: list[str] | None,+ prune: bool,+) -> list[FixRule]:+ if selected and ignored:+ msg = "--select and --ignore are mutually exclusive"+ raise ValueError(msg)+ if selected:+ return [rule for rule in ALL_RULES if rule.code in selected]+ active = list(DEFAULT_RULES)+ if prune:+ active.extend(PRUNING_RULES)+ if ignored:+ active = [rule for rule in active if rule.code not in ignored]+ return active+```++## What is NOT in scope (Tier 1)++- No LLM-based fixes (generating missing concepts, inferring outputs for conditions)+- No `fix-input-stuff-mismatch` (requires understanding concept compatibility — judgment call)+- No `fix-compose-structure` (updating concept structure fields for list types — too close to authoring)+- No `fix-condition-output` (choosing output for PipeCondition with mixed branch outputs — ambiguous)+- No iteration loop (fixes are convergent in a single pass)+- No `plxt fmt` integration (can be run separately by the caller)++These are candidates for a future Tier 2 (`--fix --unsafe`).diff --git a/wip/autofix/pr-1035-review-notes.md b/wip/autofix/pr-1035-review-notes.mdnew file mode 100644index 000000000..c64f0d3fd--- /dev/null+++ b/wip/autofix/pr-1035-review-notes.md@@ -0,0 +1,30 @@+# PR #1035 — deferred review note++Triage of the SWE-agent review comments on PR #1035 (`feature/Autofix-step4-Agnt-Apply`) fixed two confirmed bugs (logical-source mangling in `validate_bundle`; missing `~` expansion in the shared bundle-path resolver) and dismissed three false positives. One finding is real-but-inert and is captured here rather than fixed, per the "defer design-tradeoff findings" convention.++## Intra-round cross-file collision in `fix_loop._split_cross_file_collisions`++**Reporter:** cubic-dev-ai (P2, confidence 7) — thread on `pipelex/pipeline/fixes/fix_loop.py`.++**The observation (correct):** `_split_cross_file_collisions` decides whether a queued fix would collide with a bare pipe code by comparing only against the *already-loaded* `codes_by_file`. It does not account for bare codes that *other queued fixes in the same round* are about to write. So, read in isolation, two fixes that rename a pipe in two different files to the same new bare code in the same iteration would both be kept — writing a duplicate bare code across files.++**Why it is inert today:** the scenario cannot currently arise.++- The only fix rule that writes a bare pipe code is `strip-namespace` (`pipelex/pipeline/fixes/planner.py`), which fires on `INVALID_PIPE_CODE_SYNTAX`.+- `INVALID_PIPE_CODE_SYNTAX` is a per-file blueprint-parse error. `_load_mthds_files_into_library` (`pipelex/libraries/library_manager.py:777`) raises on the **first** file that fails to parse, and the entry file is parsed only after libraries load cleanly. So a single `validate_bundle` pass surfaces `strip-namespace` fixes for **exactly one file**.+- The cross-*iteration* case (file X stripped to `process` in round 1, entry file's `beta.process` surfacing in round 2) is already caught: `codes_by_file` is rebuilt fresh every iteration, so X's now-bare `process` is visible and the entry fix is dropped — the loop bails with the "cross-file collision" reason.++The safety is real but **emergent and non-local**: it depends on the per-file short-circuit in blueprint loading, which is not documented at the collision gate.++**When it becomes a live bug:**++1. `_load_mthds_files_into_library` is changed to **accumulate** blueprint-parse errors across all files (a plausible "show me all my errors at once" UX improvement) — two files' `strip-namespace` fixes could then co-occur in one pass; or+2. a **new** fix rule is added that writes a bare pipe code from a **merge-stage** error (merge processes all blueprints together), rather than from a per-file parse error.++**Remediation options (pick when/if the above changes land):**++- *Low-churn, do-now-if-desired:* add an invariant comment at `_split_cross_file_collisions` noting it is safe against intra-round duplicates only because bare-code-writing fixes come from per-file parse errors that short-circuit (one file per pass), and that a change to that short-circuit must revisit this gate.+- *Full fix (~10 lines):* thread a running `claimed_this_round: set[str]` through `_split_cross_file_collisions`. Check each fix against `other_codes ∪ claimed_this_round`; after keeping a fix, add its written bare codes (rename `new_key`s / `main_pipe` values, excluding the same target) to `claimed_this_round`. Order-independent, closes the window regardless of how many files surface per pass.+- *Test (pure function):* feed two fixes targeting different paths, both with a `RENAME_TABLE_KEY` `new_key="process"`, and a `codes_by_file` where neither path yet declares `process`. Current code keeps both; the hardened version keeps the first and drops the second.++**Status:** deferred, thread left open on the PR for follow-up.diff --git a/wip/autofix/spike-reviewers-guide.md b/wip/autofix/spike-reviewers-guide.mdnew file mode 100644index 000000000..9d8bdbfce--- /dev/null+++ b/wip/autofix/spike-reviewers-guide.md@@ -0,0 +1,37 @@+# Autofix — suggested fixes for `.mthds` validation errors (reviewer's guide)++This branch delivers **step 1 of the autofix master plan**: the whole suggested-fixes chain proven end-to-end on ONE fix rule — `match-sequence-output` (a `PipeSequence`'s declared `output` must equal its last step's effective output). There is deliberately no CLI command yet; everything is driven by tests. Design docs: `wip/autofix/master-plan.md` (the step ladder), `wip/autofix/suggested-fixes-design.md` (architecture, approved decisions D1–D4, checkpoint findings).++## The chain, in one pass++1. **Enriched typed error.** `PipeSequence.validate_output_with_library` (`pipelex/pipe_controllers/sequence/pipe_sequence.py`) computes `expected_output_ref` — the ref an author would write: bare concept code when same-domain or native, qualified `domain.Code` otherwise, with multiplicity (honoring the sub-pipe `output_multiplicity` override) and optionality marker rendered by `format_concept_with_multiplicity`. It rides `PipeValidationError` (`pipelex/core/pipes/exceptions.py`) and is threaded through `categorize_pipe_validation_with_libraries_error` (`pipelex/core/pipes/handle_pipe_errors.py`) into `PipesAndConceptValidationErrorData` (`pipelex/core/exceptions.py`). The validator states the semantic fact at detection time, so the planner cannot drift from the validator.+2. **Wire models.** `pipelex/suggested_fix.py` — a low-level module (stdlib + pydantic only) so `base_exceptions.py` imports it cycle-free: `FixOpKind` (`set_key`/`delete_key`/`delete_table`/`rename_table_key`), `FixOp`, `FixSafety` (`safe`/`unsafe`), `SuggestedFix`. `ValidationErrorItem` (`pipelex/base_exceptions.py`) gains `suggested_fix: SuggestedFix | None` — serialized `exclude_none`, so non-fixable error payloads are byte-identical to before (pinned by test).+3. **Planner.** `pipelex/pipeline/fixes/planner.py` — a pure function over error-data, keyed on `error_type.is_inadequate_output` (exhaustive-match property on the enum) + presence of `expected_output_ref` + `pipe_code`, never on message strings. Emits one SAFE `set_key ["pipe", <code>] output = <expected>` op. Hooked into `build_validation_error_items` (`pipelex/pipeline/validation_errors.py`) — the ONE shared builder every consumer (CLI/API/MCP) flows through.+4. **Applier.** `pipelex/pipeline/fixes/applier.py` — mutates a tomlkit DOM **in place, never rebuilds containers**, so comments, ordering, and table style of untouched content survive by construction (golden byte-compare tests pin it). An op whose target path is absent is skipped-and-reported, not raised (synthetic pipes have no TOML to patch); a malformed op raises `PipelexUnexpectedError` (planner bug). `rename_table_key` exists on the wire enum but the applier raises for it — position-preserving rename is Phase 1, nothing emits it yet.+5. **Convergence loop.** `pipelex/pipeline/fixes/fix_loop.py` — async `fix_bundle_file`: validate (reusing `validate_bundle` wholesale — NO parallel validation pipeline) → collect applicable SAFE fixes → apply → re-validate, to a fixed point bounded by `max_iterations`. Cascades are expected (validation aborts at the first `PipeValidationError`, so nested mismatches converge error-by-error). Non-convergence bails loudly via fix fingerprints (`fix_code|source|per-op` identity): a fingerprint proposed twice ends the loop with `bail_reason` instead of spinning.++## Invariants a reviewer should check++- **Structural suppression, not type-sniffing.** `INADEQUATE_OUTPUT_CONCEPT`/`_MULTIPLICITY` are also raised by PipeParallel, PipeCondition, and operator sites — their output choice is ambiguous, so they must get NO fix. Only the two `PipeSequence` raise sites set `expected_output_ref`; the planner's field-presence requirement suppresses everything else. Tests pin the missing-field → `None` behavior.+- **Multi-file scoping guard.** No raise site sets `PipeValidationError.file_path` today, so `SuggestedFix.source` is always `None`. A source-less fix is only provably targeted at the file being fixed under single-file validation — with `library_dirs`, a same-named pipe from another domain could resolve to this file's table (pipe codes are only unique per domain). `_applicable_safe_fixes` therefore drops source-less fixes when `library_dirs` is set: multi-file bundles get no fixes rather than a wrong patch. Real multi-file targeting is Phase 1 (`wip/autofix/deferred-checkpoint-0-review-items.md`).+- **Presentation stays out of the contract.** The fix ops are the contract; no rendered diffs, exit codes, or prose verdicts leak into the wire models.+- **No behavior change for non-fixable errors.** `suggested_fix` is additive and `exclude_none`; existing consumers see identical payloads.++## Test map++- `tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py` — enrichment: wrong concept, multiplicity, `nb_output` override, optionality marker.+- `tests/unit/pipelex/test_suggested_fix.py` — wire round-trip, plain-string enum serialization, byte-identity for non-fixable items.+- `tests/unit/pipelex/pipeline/fixes/test_fix_planner.py` — planning + suppression cases.+- `tests/unit/pipelex/pipeline/fixes/test_fix_applier.py` — golden byte-compare (`tests/data/fixes/*.mthds` + `.golden.mthds`), idempotence, guarded skip, delete semantics.+- `tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py` — no-progress fingerprint bail (stubbed validator).+- `tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py` — source-less fixes dropped under `library_dirs`, still applied single-file.+- `tests/integration/pipelex/pipeline/test_fix_convergence_loop.py` — single-pass fix, two-iteration cascade (nested sequences), already-valid no-op.+- `tests/unit/pipelex/pipeline/test_validation_errors.py` — fixes ride the wire items through the shared builder.++## Known deferrals (deliberate, not gaps)++See `wip/autofix/deferred-checkpoint-0-review-items.md`: real multi-file fix targeting (thread `file_path` from raise sites — Phase 1); conformance fixture regeneration in the sibling `conformance/` repo (cross-repo sync wave, after a release reaches `pipelex-api`); `expected_output_ref` computed on the happy validation path too (accepted: trivial cost, laziness would duplicate code). One deleted surface: the empty, unreferenced `PipelexBundleBlueprintFixableErrorType` stub enum. Changelog entry is deferred to master-plan step 3 (ship wave) — the spike introduces no user-facing surface.++## Next steps (not in this PR)++Master-plan step 2 (wave-1 engine): remaining safe rules (`sync-controller-inputs`, `strip-native-concept-redecl`, `strip-namespace` if position-preserving rename lands clean), hardened loop with multi-file targeting, then the agent-CLI surface (wave 1, D3).diff --git a/wip/autofix/step2-reviewers-guide.md b/wip/autofix/step2-reviewers-guide.mdnew file mode 100644index 000000000..0ad727ac3--- /dev/null+++ b/wip/autofix/step2-reviewers-guide.md@@ -0,0 +1,39 @@+# Autofix — wave-1 rule breadth (step 2 reviewer's guide)++This branch delivers **step 2 of the autofix master plan**: three more fix rules, each a deliberately different fix *shape*, landed on the stacked branch `feature/Autofix-step2` (PR #1031, base `feature/Autofix` — stacks on the step-1 spike, PR #1027). Design docs: `wip/autofix/master-plan.md` (the step ladder), `wip/autofix/suggested-fixes-design.md` (architecture, per-checkpoint findings, the step-2 abstraction verdict). Reviewer's guide for step 1: `wip/autofix/spike-reviewers-guide.md`.++## The chain, in one pass++1. **`sync-controller-inputs`** (Phase A) — first multi-op fix. `PipeAbstract.generic_validate_inputs_with_library` (`pipelex/core/pipes/pipe_abstract.py`) is enriched with `expected_inputs`/`declared_inputs` (both rendered via `StuffSpec.to_bundle_representation`), gated on `self.is_controller` so operator raise sites stay unfixable. The planner (`planner.py`) diffs the two mappings into `set_key`/`delete_key` ops on the `inputs` table — one fix repairs all input drift for a pipe even though validation aborts at the first error. The applier mutates the inline/block table in place.+2. **Canonical-output swap** (Phase A′, mid-step) — the applier's hand-rolled inline-table canonicalization (crash-prone on nested/dotted keys) was replaced by a single `pipelex_tools.format_mthds` pass (`applier.serialize_and_format`), now a **core runtime dep** (`pipelex-tools-py`). Output philosophy shifted from "surgical byte-preservation" to "canonical whole-file MTHDS" — a no-op on already-formatted files. `apply_fix_ops` stays pure DOM mutation; `serialize_and_format` owns rendering and raises `PipelexUnexpectedError` on any `kind="syntax"` diagnostic (never silently writes).+3. **`strip-native-concept-redecl`** (Phase B) — first blueprint-channel fix and first delete-shaped fix in production. `validate_concept_keys` now raises a typed `NativeConceptRedeclarationError` carrying `concept_code`; a new blueprint-channel planner path (`plan_fix_for_blueprint_validation_error`) emits `delete_key` on `["concept"]`, which covers every authoring form (table, inline, dotted) because tomlkit represents them all as one `concept` table. First fix with a populated `SuggestedFix.source`, exercising the loop's source/`library_dirs` guard live.+4. **`strip-namespace`** (Phase C, stretch — **GO, shipped**) — the last unexercised op kind, `RENAME_TABLE_KEY`, proven end-to-end via tomlkit's private, position-preserving `Container._replace`. A typed `InvalidPipeCodeSyntaxError` carries `offending_code`/`stripped_code`, gated by `_strippable_same_domain_pipe_code` (same-domain prefix, valid bare tail, no collision). The feared array-of-tables `table_path` widening **never materialized**: same-domain qualified `steps[]/branches[]` references already resolve to the bare code, and only declaration keys + `main_pipe` enforce snake_case — so the fix touches only those two sites.++## Invariants a reviewer should check++- **Structural suppression throughout, never message-sniffing.** Each new fix keys off a field set only at the raise site that knows the correct value (`expected_inputs`, `concept_code`, `stripped_pipe_code`); the planner never re-derives or matches on error text.+- **`format_mthds` guarantee.** Every applier write goes through one canonical-format pass; a syntax diagnostic aborts loudly rather than writing malformed TOML. All new fixtures are `format_mthds`-idempotent.+- **Collision and ordering safety in the rename path.** `_rename_key_in_place` handles all three tomlkit container shapes (plain `Table`, `OutOfOrderTableProxy` with the pipe's fields split across interleaved chunks, inline `AbstractTable`) and renames the key in **every** chunk — the checkpoint-D fix for a pipe whose header and block `.inputs` straddle an intervening `[concept]` section (previously orphaned the block under a phantom key while reporting APPLIED). `main_pipe` retarget is collision-gated at the categorizer (`_main_pipe_strip_would_retarget`), and the fix loop pre-scans sibling bundles flat across **all** domains (`_sibling_pipe_codes`) before allowing a rename, bailing loudly rather than writing a colliding rename.+- **No abstraction drift.** `SuggestedFix`/`FixOp` absorbed multi-op, delete-shaped, blueprint-channel, and rename fixes with no structural change — the only wire edit was widening `TomlValue` to admit a flat scalar dict (Phase A.2). See the design doc's "Step-2 exit — abstraction verdict" section.+- **No behavior change for non-fixable errors.** All new fields are additive on already-`exclude_none` models.++## Test map++- `tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py` — Phase A enrichment (missing/extraneous/mismatch, cross-domain refs, optionals-marker preservation, PipeCondition suppression).+- `tests/unit/pipelex/pipeline/fixes/test_fix_planner.py` — `sync-controller-inputs` planning + suppression.+- `tests/unit/pipelex/pipeline/fixes/test_fix_applier_inputs_sync.py` + `tests/data/fixes/controller_inputs_*.mthds` — golden byte-compare (inline/block/missing-table forms).+- `tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py` — Phase B typed-error enrichment across authoring forms.+- `tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py` — blueprint-channel planning for both B and C.+- `tests/unit/pipelex/pipeline/fixes/test_fix_applier_native_concept.py` + `native_redecl_*.mthds` — Phase B golden fixtures, idempotence, guarded skip.+- `tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py` — Phase C typed-error enrichment (rename + `main_pipe`, collision/cross-package suppression).+- `tests/unit/pipelex/pipeline/fixes/test_fix_applier_strip_namespace.py` + `strip_namespace_rename.mthds`/`.golden.mthds` — position/comment preservation, collision-skip, key-absent-skip.+- `tests/unit/pipelex/pipeline/fixes/test_fix_convergence_loop.py` — cross-rule cascades (inputs mask outputs; two redeclarations converge one per iteration; rename + `main_pipe` in one pass) and the checkpoint-D interleaved-chunk regression.+- `tests/unit/pipelex/pipeline/test_validation_errors.py` — all three fixes ride `ValidationErrorItem` through the shared builder.++## Known deferrals++Per-checkpoint deferred items (design tradeoffs, not defects) live in `wip/autofix/deferred-checkpoint-{a,a-prime,b,c,d}-review-items.md` — notably: `main_pipe`-to-nonexistent-pipe strip, the one-rename-per-iteration convergence cap, comment reflow on a deleted `[concept.X]` table, an upstream `pipelex_tools` stub/runtime-export mismatch. Real multi-file targeting and the `pipelex-agent fix bundle` command are out of scope for step 2 (master-plan steps 3–4).++## Next steps (not in this PR)++Master-plan step 3: hardened loop with real multi-file targeting (thread `file_path` from raise sites, fix `is_single_file` derivation) — may reuse Phase B's `SuggestedFix.source` threading. Then step 4 (`pipelex-agent fix bundle`), gated human CLI surfacing (step 5), and the ship wave (step 6).diff --git a/wip/autofix/step3-step4-hardened-loop-and-agent-apply.md b/wip/autofix/step3-step4-hardened-loop-and-agent-apply.mdnew file mode 100644index 000000000..28f7b0a6c--- /dev/null+++ b/wip/autofix/step3-step4-hardened-loop-and-agent-apply.md@@ -0,0 +1,163 @@+# Autofix — steps 3 + 4 design: hardened loop + agent apply surface++Detailed design and working plan for master-plan steps 3 (hardened loop — real multi-file targeting) and 4 (agent apply surface — `pipelex-agent fix bundle`), landing together on the stacked branch `feature/Autofix-step4-Agnt-Apply` (base: `feature/Autofix-step2`, PR #1031). Map: [master-plan.md](master-plan.md). Architecture and per-checkpoint findings: [suggested-fixes-design.md](suggested-fixes-design.md).++**Status: STEP 4 CODE COMPLETE (2026-07-08) — `make agent-check` + touched tests green, CHECKPOINT 2 review NOT yet run.** CHECKPOINT 1 review on the step-3 diff is complete; confirmed bugs were fixed in this pass (signature-only sibling headers no longer block valid concrete renames, input-drift source threading is pinned, collision-map rebuilds are pinned, and `files_written` order/dedupe is pinned). Step 4 now ships `pipelex-agent fix bundle`, the CLI-free fix renderer, command/unit/integration/e2e coverage, agent CLI docs, and a CHANGELOG entry. The current step-4/checkpoint-review changes are **uncommitted** on `feature/Autofix-step4-Agnt-Apply` (base commit `a6ffae486`).++**NEXT ACTION (cold start): run CHECKPOINT 2** — fresh-context `/code-review` fan-out on the step-4 diff (from `a6ffae486` to the current working tree), plus the checkpoint-1 review fixes listed above. Fix confirmed bugs, defer tradeoffs to a new `deferred-checkpoint-e-review-items.md` only if real tradeoffs remain, then update this doc, the master plan, and the README before landing.++### Implementation record (what a cold session needs to know beyond the design)++- **D3.1** — `_backfill_pipe_error_source` in `pipelex/pipeline/validate_bundle.py`, called first thing in the `except PipeValidationError` arm of `_translate_to_validate_bundle_error`. Full-pipe_ref lookup only; miss leaves `file_path=None`. Pins: 3 new pipe-channel tests in `test_validate_bundle_source_threading.py`.+- **D3.2–D3.5** — `fix_loop.py` was substantially rewritten. Helper names: `_safe_fixes` (SAFE + single-file gate + select/ignore filters), `_partition_by_write_scope`, `_pipe_codes_by_file` (per-file map over entry + resolved dirs, rebuilt per iteration), `_colliding_op_name` + `_split_cross_file_collisions` (per-target), `_fix_target_path` (source → resolved Path, else entry). `FixBundleResult.files_written: list[str]` = **resolved** paths, first-write order, deduped. Out-of-scope bail wording: `fixes target files outside write scope: <paths> — pass their directory with -L/--library-dir to allow writing`. Cross-file bail wording changed to `…would write a pipe code (…) already declared in a sibling bundle` (covers renames AND main_pipe set_keys). Mixed scope proceeds with in-scope fixes (no all-or-nothing).+- **D3.6 categorizer half** — `_main_pipe_strip_would_retarget` → `_main_pipe_strip_is_safe` (XOR predicate: safe iff exactly one of dotted/bare exists as a `[pipe]` key) in `validation_error_categorizer.py`; call site inverted (`not _main_pipe_strip_is_safe`). Cross-ref comment in `pipelex_bundle_blueprint.py` updated.+- **D3.6 loop half** — the `main_pipe` `SET_KEY` drop needs only ONE condition (`value in other-file pipe codes`): "paired rename was dropped as colliding" is subsumed, since a rename is dropped iff its `new_key` is declared elsewhere, and that `new_key` equals the `main_pipe` value.+- **Step-4 early items already DONE**: `fix_bundle_file(..., select_codes=None, ignore_codes=None)` filtering inside `_safe_fixes` + `KNOWN_FIX_CODES` frozenset in `planner.py` (pins: `tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py`); shared `pipelex/cli/agent_cli/commands/bundle_path_resolver.py` (`resolve_bundle_target(path, *, library_dir) -> tuple[str, list[str] | None]`) adopted by `validate bundle` verbatim-behavior (its now-stale `# type: ignore[arg-type]` comments removed; validate tests green).+- **CHECKPOINT 1 review fixes DONE**: `_pipe_codes_by_file` now excludes typeless signature-only sections from hard collision checks, because same-batch crate merge permits a concrete pipe to replace a matching `PipeSignature`; new pins cover sibling signature headers, input-drift `source` on entry and sibling files, per-iteration collision-map rebuilds, and first-write-order `files_written`.+- **Step 4 implementation DONE**: new `fix` agent CLI group registered after `validate`; `fix bundle` uses shared bundle-path resolution, validates mutually-exclusive/unknown rule filters, initializes Pipelex with the validate profile, runs `fix_bundle_file`, emits success via `format_fix_markdown`, and emits still-invalid verdicts as `FixBundleError` with the full `FixBundleResult` payload. Tests added: renderer unit tests, patched command-format unit tests, real-loop command integration tests, and subprocess e2e tests.+- **Corruption-regression fixture gotcha**: a dotted `main_pipe = "domain.pipe"` is itself invalid (strip-namespace fires) — multi-file fixtures must use the bare form (`main_pipe` resolution is bundle-local, so bare codes duplicated across domains in sibling files are fine).+- Unit tests drive the loop with `mocker.patch("pipelex.pipeline.fixes.fix_loop.validate_bundle", side_effect=[...])` and, for ambient-dir cases, patch `...fix_loop.resolve_library_dirs`; pass `max_iterations` explicitly (or patch `...fix_loop.get_config`) to avoid needing a booted config.++## Scope++- **Step 3** replaces the spike's conservative scoping guard with real multi-file targeting: pipe-channel errors get a populated `source`, the single-file gate derives from *resolved* library dirs, fixes apply to the file that declares the offending item, and only user-passed files are ever written. Closes deferred items 0 and 1 ([deferred-checkpoint-0-review-items.md](deferred-checkpoint-0-review-items.md)) and the two halves of checkpoint-C item 1 ([deferred-checkpoint-c-review-items.md](deferred-checkpoint-c-review-items.md)). Also wires the orphaned `fix_loop_max_attempts` config.+- **Step 4** ships `pipelex-agent fix bundle`: a thin command over `fix_bundle_file` following the agent CLI's two-stream output conventions, plus `--select`/`--ignore` rule filtering in the loop, a CLI-free markdown renderer, and e2e CLI tests. This is the milestone where an agent runs validate → fix → re-validate entirely from the CLI.++**Out of scope** (unchanged deferrals): the human CLI (`pipelex fix` + the `💡 Suggested fix` line — step 5, gated on this branch), `--diff` preview (step 5, see D4.2), checkpoint-C item 2 (one-rename-per-iteration convergence cap — mitigated here by the config default, the aggregate-raise refactor is its own chunk), checkpoint-D item 1 (dotted-key controller inputs — accepted fail-safe), wave-2 surfaces (API `POST /fix`, MCP, editor).++## Where the code stands (step-2 exit)++- **The guard to replace.** `_applicable_safe_fixes` (`pipelex/pipeline/fixes/fix_loop.py:64-83`) keeps a source-less fix only when `is_single_file`, and a sourced fix only when `Path(source) == mthds_file_path`. The call site computes `is_single_file=library_dirs is None` (`fix_loop.py:172`) — wrong in both directions: explicit `[]` (documented "no libraries") is treated as multi-file (fixes over-dropped), and `None` can fall through to hub defaults / `PIPELEXPATH` and load other files while being treated as single-file.+- **Pipe-channel `source` is dead code.** `categorize_pipe_validation_with_libraries_error` reads `pipe_error.file_path` (`pipelex/core/pipes/handle_pipe_errors.py:199`), but no raise site ever sets it — so `match-sequence-output` and `sync-controller-inputs` fixes are source-less and get dropped whenever library dirs are in play. The blueprint channel (`strip-native-concept-redecl`, `strip-namespace`) is already populated from `blueprint_dict["source"]`.+- **Provenance already exists — no new bookkeeping needed.** `LibraryManager._pipe_source_map: dict[str, Path]` (pipe_ref → declaring `.mthds` file, `pipelex/libraries/library_manager.py:101`) is populated during load (`library_manager.py:505-507`, fed by `LibraryCrate.source_map`, which tracks the winning declaration across duplicates) and exposed via `get_pipe_source()` (`library_manager.py:235`). Population happens in the same loop that builds pipes, *before* `library.validate_library()` runs — so the map is live when any pipe-validation error propagates.+- **Pipes deliberately do not carry their source.** `_make_pipe_data_for_registry` (`pipelex/core/pipes/pipe_abstract.py:160-167`) grafts `source` from the crate map at serialization time precisely because `PipeAbstract` has no such field. Step 3 must respect that design.+- **The loop is single-file and nothing calls it.** One DOM load / one write per iteration (`fix_loop.py:205-215`); the applier (`apply_fix_ops` / `serialize_and_format`) is already per-DOM and needs no change. `fix_bundle_file` has no production caller — the fingerprint already includes `source`, so cross-file no-progress detection works unchanged. The config `fix_loop_max_attempts = 10` (`pipelex/pipelex.toml:53`, `BuilderConfig` in `pipelex/system/configuration/configs.py`) is defined but unwired; the code hardcodes `max_iterations: int = 5`.++## Step 3 — hardened loop++### D3.1 — Thread `source` at the catch boundary, not the raise sites++Backfill `pipe_error.file_path` in the shared translate funnel in `pipelex/pipeline/validate_bundle.py` (the `except PipeValidationError` arm, ~line 135), immediately before `categorize_pipe_validation_with_libraries_error` runs: when `file_path` is `None` and both `domain_code` and `pipe_code` are present, look up `get_library_manager().get_pipe_source(f"{domain_code}.{pipe_code}")` and set it. Use the full pipe_ref only — never the bare-code suffix fallback (bare codes are ambiguous across domains; that ambiguity is exactly what checkpoint C's cross-file guard defends against).++Why here and not the alternatives from deferred item 1:++- **Not a `source` field on `PipeAbstract`.** The codebase deliberately keeps provenance out of the runtime pipe model and looks it up from the crate when needed (see `_make_pipe_data_for_registry`); adding the field would change the pipe serialization surface for one consumer's benefit.+- **Not per-raise-site threading.** The raise sites (`pipe_abstract.py` input checks, `pipe_sequence.py` output checks) don't know the file, and every future enriched raise site would have to remember the same plumbing. One interception point covers them all, including the un-enriched raise sites (their errors gain a `source` locator for free — better error reports even without a fix).+- **Not a domain-qualifier check in the loop.** Domains legitimately span files, so a domain match cannot prove which file declares the pipe.++Lookup misses (either code absent, or the ref not in the map) leave `file_path` as `None` — the fix stays source-less and falls under the conservative single-file rule, which is the safe direction. The wrapped blueprint-stage `PipeValidationError` path in the categorizer already prefers `wrapped_pipe_error.file_path or source` and needs no change.++### D3.2 — Derive the single-file gate from resolved dirs++At loop start, resolve once: `effective_dirs, _ = resolve_library_dirs(library_dirs)` (`pipelex/hub.py:699` — per-call → hub instance default → `PIPELEXPATH` → none), and set `is_single_file = not effective_dirs`. This fixes both directions of deferred item 0: `[]` is now genuinely single-file (source-less fixes apply), and a `None` that fell through to ambient dirs is now multi-file (source-less fixes conservatively dropped). `validate_bundle` resolves through the same function internally, so the gate matches what validation actually loaded. The sibling pre-scan gate (`fix_loop.py:162`, currently `library_dirs is not None`) switches to `effective_dirs` too.++### D3.3 — Write-scope policy: only user-passed files are written++Per the rule guard already decided in the design doc ("only files the user passed to the command get written"):++- **Writable:** the entry `mthds_file_path`, plus any `.mthds` file under the *per-call* `library_dirs` argument when one was explicitly provided.+- **Read-only:** files loaded via ambient resolution (hub defaults, `PIPELEXPATH`) — the user did not pass those to *this* command. Fixes sourced there are excluded from the applicable set.+- Path comparisons normalize both sides with `.resolve()` (the current guard compares raw paths).++When applicable fixes exist but every one of them targets a read-only file, the loop returns `is_valid=False` with a bail reason naming the out-of-scope files ("fixes target files outside write scope: … — pass their directory with -L to allow writing"), so the outcome is loud and actionable rather than a silent no-op. The remaining errors still carry their `suggested_fix` (with `source`), so a consumer can see exactly what would have been done and where.++### D3.4 — Per-file apply, `files_written`, per-target collision scan++The apply phase groups the iteration's new fixes by target file (`Path(fix.source).resolve()`, defaulting to the entry file for source-less fixes), loads one tomlkit DOM per distinct target, applies that group's ops, and writes each changed file through `serialize_and_format` — the same load/apply/write shape as today, per file. `FixBundleResult` gains `files_written: list[str]` (ordered, deduped across iterations; additive field on a runtime-only model).++The cross-file rename-collision machinery becomes per-target: the sibling scan builds a per-file pipe-code map over *all* loaded files (still flat across domains — the checkpoint-C ambiguity rule stands), rebuilt each iteration now that multiple files can mutate, and a `RENAME_TABLE_KEY` targeting file F collides iff the bare `new_key` exists as a pipe key in any loaded file other than F.++### D3.5 — Wire `fix_loop_max_attempts`++`fix_bundle_file`'s signature becomes `max_iterations: int | None = None`; `None` resolves to `get_config().pipelex.builder_config.fix_loop_max_attempts` (config default 10). The hardcoded 5 is deleted — per the config rules, the default lives in `pipelex/pipelex.toml` only. This also softens (without fixing) checkpoint-C item 2's convergence cliff.++### D3.6 — Checkpoint-C item 1 lands here (both halves)++Step 3 rewrites exactly the code sites this deferral names, and multi-file writes make both failure modes more reachable, so the pair is in scope:++- **Categorizer half:** extend `_main_pipe_strip_would_retarget` (`pipelex/core/interpreter/validation_error_categorizer.py`) into a `_main_pipe_strip_is_safe` gate with the two-disjunct predicate from the deferral doc — the strip is enriched only when the bare tail already exists as a pipe key OR the dotted code itself exists as a key (its paired rename will materialize the target). Kills the "typo'd tail → SAFE fix rewrites `main_pipe` to a nonexistent pipe" mutation while keeping the convergent dotted-declaration happy path.+- **Fix-loop half (the PR #1031 cubic P2 gap):** in the cross-file collision split (`fix_loop.py:112-141` today), also drop a root `main_pipe` `SET_KEY` whose paired declaration rename was dropped as cross-file colliding, or whose value collides with a sibling file's pipe code — the categorizer cannot see cross-file state, so this suppression must live in the loop.++### Step-3 tasks (TDD — red tests first per layer)++- [x] Integration: `test_validate_bundle_source_threading.py` grows pipe-channel assertions — `INADEQUATE_OUTPUT_*` and input-drift errors carry `source` for entry-file and sibling-file pipes; lookup-miss leaves `source` absent.+- [x] `validate_bundle.py` funnel backfill (D3.1).+- [x] Unit: `is_single_file` derivation cases (`[]` single, `None`+hub-default multi, explicit dirs multi) in `test_fix_loop_multi_file_scoping.py`; loop switch to `resolve_library_dirs` (D3.2).+- [x] Unit: write-scope policy — sourced fix under `-L` applies to the declaring sibling; ambient-dir fix excluded with the out-of-scope bail reason (D3.3).+- [x] Loop rework: per-file grouping + `files_written` + per-target collision scan rebuilt per iteration (D3.4), with unit pins for grouping and collision.+- [x] Integration: `test_fix_convergence_loop.py` multi-file cascade — an error declared in a sibling file is fixed *in the sibling*; both files written and reported; **regression pin for the original corruption scenario** (same pipe code in two domains across two files → the fix patches the declaring file, never the entry file's same-named table).+- [x] Config wiring (D3.5) + `make tb` boot check.+- [x] Checkpoint-C item 1 pins per the deferral doc's "if revisited" notes: typo'd-tail strip suppressed (file untouched), dotted-declaration path still converges, two-file `main_pipe` `SET_KEY` dropped alongside its blocked rename (D3.6).+- [x] `make agent-check` + `make agent-test` green (full suite, 2026-07-08).++### Exit — CHECKPOINT 1 (step-3 exit)++Fixes apply correctly across multi-file bundles, targeting the declaring file only; the drop-everything guard is gone; the corruption-scenario regression test is green. House pattern: fresh-context `/code-review` fan-out on the step-3 diff; confirmed bugs fixed, tradeoffs deferred to a `deferred-checkpoint-e-review-items.md`. Update this doc's status block and the master plan, then hand off to step 4 (natural session boundary — step 4 opens the CLI surface, a different area).++## Step 4 — `pipelex-agent fix bundle`++### D4.1 — Command layout: mirror the `validate` group exactly++New group `fix` beside `validate`/`run`/`inputs`: `pipelex/cli/agent_cli/commands/fix/app.py` (`fix_app = typer.Typer(add_completion=False, no_args_is_help=True)`, one `bundle` subcommand, no group callback — options live on the subcommand, house style) and `commands/fix/bundle_cmd.py`. Register with `app.add_typer(fix_app, name="fix", ...)` in `_agent_cli.py` and add `"fix"` to `PipelexAgentCLI.list_commands()` right after `validate`. Init via `make_pipelex_for_agent_cli(library_dirs=..., needs_inference=False, needs_model_specs=True)` (same profile as validate — the loop's re-validation dry-runs, no live inference), `asyncio.run(fix_bundle_file(...))`, teardown in `finally`, `except typer.Exit: raise` before the catch-all — the full validate handler cascade.++### D4.2 — Options++| Option | Semantics |+| --- | --- |+| `path` (arg) | `.mthds` file or directory — same resolution as `validate bundle` (auto-detect the default bundle file name or a single `*.mthds`; ambiguous → exit 2; a directory injects itself into the library dirs, and being user-passed it is **writable** under D3.3). |+| `-L/--library-dir` | Repeatable, as in validate. Per D3.3 these dirs are the write scope beyond the entry file. |+| `--max-iterations` | `int | None`, min 1; `None` → the `fix_loop_max_attempts` config default. |+| `--select` / `--ignore` | Repeatable fix-rule codes; mutually exclusive (both → exit 2). Unknown code → exit 2 listing the known codes (exported as a frozenset beside the planner's fix-code constants). Implemented in the loop as keyword-only `select_codes`/`ignore_codes` filtering inside `_applicable_safe_fixes`, so step 5's human command inherits it for free. Failing fast on a typo beats lenient-ignore here: the flag selects *behavior* (what gets written), not presentation. |+| `--format` / `--error-format` | The two-stream convention: markdown default on stdout; `--error-format` inherits `--format` when omitted; first body line is `set_agent_cli_error_format(error_format or output_format)`. |++Deliberately absent: `--diff` (preview belongs to the human command, step 5 — agents run in repos and inspect diffs themselves, the loop has no no-write mode yet, and the result payload already names every op applied); `--pipe` (fix is whole-bundle by design); `--allow-signatures` (signatures are never errors and the fixer never touches them — runnability is validate's concern, and an agent chains fix → validate anyway); `--unsafe` (no UNSAFE rule exists in wave 1; the SAFE-only filter stays hardwired until the first UNSAFE rule arrives with its flag).++### D4.3 — Verdict, streams, exit codes++Mirrors `validate bundle`'s precedent (negative verdict → error stream):++- **Valid after the loop** (including already-valid, `iterations=0`): success payload on stdout via `agent_success_formatted(result, markdown_renderer=format_fix_markdown, output_format=...)`, exit 0.+- **Still invalid**: `agent_error(...)` on stderr with `error_type="FixBundleError"`, exit 1, message summarizing the outcome (iterations run, fixes applied, errors remaining, bail reason), and the full structured payload as envelope extras. Partial progress is normal here — the payload, not the exit code, tells the agent what advanced.+- **No verdict** (bad path, ambiguous bundle, init failure, unexpected exception): exit 2, same handlers as validate.++Contract vs presentation, per the workspace conventions: machine consumers branch on `is_valid` / `fixes_applied` / `remaining_errors`, never on the exit code.++### D4.4 — JSON contract++Both arms carry the same structured core — `FixBundleResult` dumped `mode="json", exclude_none=True` plus the envelope keys: `is_valid`, `bundle_path`, `iterations`, `fixes_applied[]` (full `SuggestedFix` dumps: `fix_code`, `description`, `safety`, `source`, `ops[]`), `files_written[]` (step 3), `remaining_errors[]`, `bail_reason` (omitted when absent). `remaining_errors[]` items are the same `ValidationErrorItem` shape as `validate`'s `validation_errors[]` (same builder), so an agent parses one error schema across both commands. Success arm adds `success: true`; error arm rides the standard `agent_error` envelope (`error_type`, `message`, extras).++### D4.5 — Markdown renderer (CLI-free)++`format_fix_markdown(result: dict[str, Any]) -> str` in a new `pipelex/pipeline/fixes/fix_render.py` — beside the engine, importable without Typer so the wave-2 API can reuse it (the design doc's stated placement intent). Success-arm rendering: `# Fix applied — bundle is valid` (or `# Bundle already valid` when nothing was applied), one bullet per applied fix (`fix_code` — description, naming the file when it isn't the entry bundle), a `Files written` list, and the iteration count. The still-invalid arm goes through the generic `agent_error` markdown envelope with the summary message; if agents turn out to need richer failure markdown, that refinement lands with step 5's human renderer, which will want the same thing.++### D4.6 — Shared bundle-path resolution helper++Factor `validate_bundle_cmd`'s path→bundle resolution (`commands/validate/bundle_cmd.py:94-131` — directory auto-detect, ambiguity errors, library-dir injection) into a shared helper module under `commands/`, adopted by both `validate bundle` and `fix bundle` in this change (no behavior change for validate; identical resolution is a correctness requirement — fix must patch exactly the file validate judged). Adoption by `run bundle` / `inputs bundle` is a follow-up, not scoped here.++### Step-4 tasks (TDD)++- [x] Loop: keyword-only `select_codes`/`ignore_codes` on `fix_bundle_file` + known-codes frozenset beside the planner constants, with unit pins (filtering, unknown code raises at the CLI layer only). (Landed early, with step 3.)+- [x] Shared path-resolution helper factored out + adopted by validate (D4.6), validate's existing tests staying green. (Landed early: `commands/bundle_path_resolver.py`.)+- [x] Renderer: `fix_render.py` + unit tests (fixed / already-valid / multi-file arms).+- [x] Command: `fix/app.py` + `fix/bundle_cmd.py` + registration (D4.1-D4.3), with `tests/unit/pipelex/cli/agent_cli/test_fix_format.py` mirroring `test_validate_format.py` (patched core; both format arms; exit 0/1; `--select`/`--ignore` mutual exclusion and unknown-code rejection).+- [x] Integration: `tests/integration/pipelex/cli/test_agent_fix_bundle.py` — the command function against the real loop on `tmp_path` *copies* of fixtures (the command mutates files): fixable bundle → exit 0 + file actually fixed on disk; unfixable → structured error payload; `--select` honored end-to-end.+- [x] E2E: `tests/e2e/agent_cli/test_fix_bundle.py` — subprocess `pipelex-agent fix bundle` in the hermetic/offline harness (`tests/e2e/agent_cli/conftest.py` pattern), asserting the JSON contract, stdout-cleanliness, and exit codes. (The master plan says "snapshot tests"; the repo has no snapshot framework — subprocess + JSON/string assertions is the house e2e pattern, and that's what ships.)+- [x] Docs plumbing: update `pipelex/cli/agent_cli/CLAUDE.md` (output-format section gains the fix command); CHANGELOG `[Unreleased]` entry for the new command. The user-facing docs page stays in step 6 per the master plan; the `mthds-agent` output-audit update is a cross-repo step-7 hand-off note.+- [x] `make agent-check` green; touched test slice green (`55 passed`: renderer/command/select-ignore/unit scoping/integration/e2e/checkpoint pins). Full `make agent-test` was not run in this pass.++### Exit — CHECKPOINT 2 (step-4 exit)++The command is shipped on the agent CLI and an agent can run validate → fix → re-validate entirely from the CLI; e2e tests green. House-pattern review fan-out on the step-4 diff. Update this doc, the master plan (steps 3 + 4 → DONE), and the wip README; record the step-5 hand-off list (what step 5 reuses: the loop's select/ignore params, `fix_render.py`, the shared path helper; candidate refinement: richer still-invalid markdown).++## Test map (new / extended)++- `tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py` — pipe-channel `source` backfill (D3.1).+- `tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py` — resolved-dirs gate, write scope, out-of-scope bail (D3.2, D3.3).+- `tests/integration/pipelex/pipeline/test_fix_convergence_loop.py` — multi-file cascades, corruption-scenario regression, `files_written` (D3.4).+- `tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py` + `tests/unit/pipelex/pipeline/fixes/test_fix_convergence_loop.py` pins for checkpoint-C item 1 (D3.6).+- `tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py` — loop `select_codes`/`ignore_codes` pins (step 4, DONE).+- `tests/unit/pipelex/pipeline/fixes/test_fix_render.py`, `tests/unit/pipelex/cli/agent_cli/test_fix_format.py`, `tests/integration/pipelex/cli/test_agent_fix_bundle.py`, `tests/e2e/agent_cli/test_fix_bundle.py` — step 4 (TODO).++## Sequencing++Step 3 lands first and clears CHECKPOINT 1 before step 4 starts: the CLI's contract tests pin `FixBundleResult` (including `files_written` and the write-scope bail reasons), so the loop semantics must be frozen first. Both steps ship on this branch; step 5 (human CLI) remains gated on this branch's exit per the master plan's sequencing doctrine.diff --git a/wip/autofix/step5-human-cli-surfacing.md b/wip/autofix/step5-human-cli-surfacing.mdnew file mode 100644index 000000000..025964e2b--- /dev/null+++ b/wip/autofix/step5-human-cli-surfacing.md@@ -0,0 +1,171 @@+# Autofix — step 5 design: human CLI surfacing++Detailed design and working plan for master-plan step 5 (human CLI surfacing: `pipelex fix bundle` + the `💡 Suggested fix:` line in `pipelex validate`), on branch `feature/Autofix-step5` (base: the PR #1035 squash `611644e82`, which landed steps 3 + 4). Map: [master-plan.md](master-plan.md). Architecture and per-checkpoint findings: [suggested-fixes-design.md](suggested-fixes-design.md). Steps 3 + 4 record: [step3-step4-hardened-loop-and-agent-apply.md](step3-step4-hardened-loop-and-agent-apply.md).++**Status: STEP 5 COMPLETE — all phases (A–D) done, `--diff` shipped (GO), CHECKPOINT B exit review cleared.**++**NEXT ACTION (cold start): step 6 (release train)** — see the [master plan](master-plan.md). This branch is ready to open as a PR. Step-6 hand-off notes are at the bottom of this doc ("Step-6 hand-off").++**CHECKPOINT B outcome:** the workflow-backed `/code-review` (high effort) ran, but its verify stage collapsed — all 13 verifier agents died on an Anthropic session limit, so the 19 finder candidates were never adjudicated by the workflow. They were triaged by hand against the code instead. Full triage is in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md). Five confirmed bugs were fixed on this branch (mkdocs nav orphan; validate footer not shell-safe; `fix`'s still-invalid tip contradicting its own suggested-fix lines; `--diff` PipeSignature wording asserting the file is valid; `--diff` crash + mislabel + real-run divergence on a missing `-L` dir). Five items were deferred (validate footer over-count; `--diff` `-L` dedup; two cross-CLI duplications; a currently-unreachable dry-run drop) and one was rejected (the `is_dry_run` property is house-preferred over inline enum equality). Gates green (`make agent-check` 0 errors) and the targeted CLI suites + e2e pass after the fixes.++Phases A + B landed exactly per the design below; decisions taken and deltas from plan:++- **Shared human resolver** (`pipelex/cli/commands/bundle_path_resolver.py`): parameterized by `command` name + a per-command `not_a_bundle_hint` (validate's wording preserved verbatim); the `~`-expansion gap the agent side had fixed in PR #1035 triage **did** exist on the human side and is fixed in the helper (pinned by tests).+- **Flag-and-fix, telemetry**: `execute_validate` double-suffixed its `CLI_COMMAND` tag ("validate bundle bundle") — it now tags `telemetry_command_label` verbatim.+- **Flag-and-fix, rendering (beyond the planned factory-error change)**: routing the human renderer through the shared items means (a) a message-only `ValidateBundleError` (e.g. TOML parse failure) now renders the fallback residual item — previously the human saw NO detail at all; (b) pipe-validation errors now show `└─ Source:` when the item carries it. Both pinned by tests.+- **Dry-run channel kept lossless**: the wire builder suppresses the dry-run residual when categorized errors exist; `handle_validate_bundle_error` still prints `exc.dry_run_error_message` in that case (pinned).+- **E2E**: human subprocess E2E reuses the agent hermetic-HOME harness via a `tests/e2e/pipelex/cli/conftest.py` fixture re-export.+- **GO on `--diff`**: mechanics look tractable; key subtlety recorded — when the entry file lies under an explicit `-L` dir (directory mode), the sandbox entry path must be the file *inside* the mirrored dir copy, not a separate copy, or the loop would load duplicate pipes.++## Both gates are met (sequencing doctrine)++The master plan gates step 5 on two bars, both cleared:++1. **Abstraction stress-tested by rules of different shapes** — the step-2 exit verdict in the design doc ("Step-2 exit — abstraction verdict"): `SuggestedFix`/`FixOp` survived multi-op, delete, blueprint-channel, and rename fixes with no structural change; `description` is a stable one-line human string across all four rules.+2. **The apply command exists** — `pipelex-agent fix bundle` shipped in step 4 (PR #1035), so the human hint has an action behind it.++## Scope++Two pieces, landed together for symmetry (per the master plan):++- **`pipelex fix bundle`** — human command wrapping the same `fix_bundle_file` loop, with Rich-rendered output that names every change made.+- **`💡 Suggested fix:` line** — per fixable error in `pipelex validate`'s error rendering, showing `SuggestedFix.description` only (ops stay machine-facing), plus an actionable footer naming the `pipelex fix` command.+- **`--diff` preview** (show, don't write) — listed in the design doc's wave-1 CLI surface and explicitly deferred from step 4 to here ("preview belongs to the human command"). Scoped as the last phase and **cuttable**: the step-5 exit criteria don't require it, so if it fights back it becomes a deferred item rather than blocking the step.++**Out of scope:** the step-6 release train (user-facing docs page, conformance fixture regen, release cut); wave-2 surfaces (API `POST /fix`, MCP, editor); `--unsafe` (no UNSAFE rule exists in wave 1); richer still-invalid *markdown* for the agent command (only if Phase B's item renderer makes it free — see D5.5).++## What step 5 builds on (verified inventory)++- **The loop** — `fix_bundle_file(mthds_file_path, *, library_dirs, allow_signatures, max_iterations, select_codes, ignore_codes) -> FixBundleResult` (`pipelex/pipeline/fixes/fix_loop.py:292`). `FixBundleResult` (frozen, `fix_loop.py:47`): `is_valid`, `iterations`, `fixes_applied: list[SuggestedFix]`, `files_written: list[str]` (resolved paths, first-write order), `remaining_errors: list[ValidationErrorItem]`, `pending_signatures`, `is_runnable`, `bail_reason`. `max_iterations=None` resolves to `builder_config.fix_loop_max_attempts` (default 10). `select_codes`/`ignore_codes` filtering lives inside the loop, so the human command inherits it for free (that was step 4's stated intent).+- **The planner** — `plan_fix_for_pipe_validation_error` / `plan_fix_for_blueprint_validation_error` (`pipelex/pipeline/fixes/planner.py:30` / `:132`): pure functions, one raw error-data item → `SuggestedFix | None`. `KNOWN_FIX_CODES` frozenset at `planner.py:20`. `SuggestedFix` (`pipelex/suggested_fix.py:65`): `fix_code`, `description`, `safety`, `source`, `ops`.+- **The items builder** — `build_validation_error_items` (`pipelex/pipeline/validation_errors.py:24`) is the single source of truth attaching `suggested_fix` to items; called by the agent CLI, the API 422 (`ValidateBundleError.to_error_report`, `pipelex/pipeline/exceptions.py:154`), and the fix loop. `ValidationErrorItem` (`pipelex/base_exceptions.py:269`) carries the **union** of every field the human renderer prints (`error_type`, `pipe_code`, `concept_code`, `domain_code`, `source`, `field_path`, `field_name`, `variable_names`, `message`, `category`) plus `suggested_fix` — this is what makes D5.5's item-routing viable.+- **The agent command to mirror** — `pipelex/cli/agent_cli/commands/fix/bundle_cmd.py` (options, rule-filter validation `_reject_invalid_rule_filters` at `:26`, runnability gate) and the CLI-free markdown renderer `format_fix_markdown` (`pipelex/pipeline/fixes/fix_render.py:16`). The markdown renderer is **not** reused for humans (headings/backticks are agent presentation); its *structure* — title by verdict, per-fix `fix_code` + description + source-when-not-entry, files written — is the template.+- **The human validate command to mirror** — group registration in `pipelex/cli/commands/validate/app.py`; path resolution inline in `pipelex/cli/commands/validate/bundle_cmd.py:50-99` (directory auto-detect of `DEFAULT_BUNDLE_FILE_NAME`, single-`*.mthds` fallback, ambiguous → exit 2, directory injects itself into library dirs); setup/run/teardown wrapper `execute_validate` in `commands/validate/_validate_core.py:208`.+- **The human renderer to change** — `_display_validation_error_details(console, *, exc)` (`pipelex/cli/error_handlers.py:251`) iterates the **raw** `exc.pipelex_bundle_blueprint_validation_errors` / `exc.pipe_validation_errors` lists by hand — which do not carry `suggested_fix`. Its wrapper `handle_validate_bundle_error` (`error_handlers.py:323`) already computes `report = exc.to_error_report()` (items included) at `:330` and already uses the emoji conventions (`❌`, `💡 Tip:`).+- **Human CLI registration** — root Typer app in `pipelex/cli/_cli.py`: `_CORE_COMMAND_ORDER` (`:27-39`) + `app.add_typer(...)` calls (~`:222-234`).++## Design decisions++### D5.1 — Command layout: `pipelex fix bundle`, mirroring the validate group++New group `fix` beside `validate`/`run`: `pipelex/cli/commands/fix/app.py` (one `bundle` subcommand, no group callback — house style) + `commands/fix/bundle_cmd.py` + `commands/fix/_fix_core.py` (the setup/run/teardown wrapper, modeled on `_validate_core.execute_validate`: Pipelex boot with the same profile validate uses, `asyncio.run(fix_bundle_file(...))`, teardown in `finally`, `except typer.Exit: raise` before the catch-all, telemetry label `fix bundle`). Register in `_cli.py`: add `"fix"` to `_CORE_COMMAND_ORDER` right after `"validate"` and `app.add_typer(fix_app, name="fix", ...)`.++Why a group with one subcommand rather than a bare `pipelex fix <path>`: symmetry with both the human `validate` group and the agent `fix` group — every bundle-shaped surface reads `<cli> <verb> bundle <path>`, and wave 2 may grow `fix pipe`/`fix method` the way validate did.++### D5.2 — Shared human bundle-path resolution (fix must patch exactly what validate judged)++Step 4's D4.6 established the principle on the agent side (shared `agent_cli/commands/bundle_path_resolver.py`); the human side still has the resolution inlined in `validate/bundle_cmd.py:50-99`. Factor it into `pipelex/cli/commands/bundle_path_resolver.py` (human-side helper, `typer.secho` + exit-2 presentation preserved verbatim) and adopt it in **both** `validate bundle` and `fix bundle` in this change — identical resolution is a correctness requirement, not a nicety, because a directory argument defines the write scope (D3.3: the injected dir is user-passed, hence writable).++Not unified with the agent resolver in this step: the two differ exactly in error presentation (human text stream vs agent error envelope), and parameterizing that is more machinery than duplicating ~40 lines of resolution whose *semantics* are pinned by tests on both sides. Candidate follow-up if a third consumer appears. **Flag-and-fix while in there:** the PR #1035 triage fixed a missing `~` expansion in the agent resolver — check whether the human validate path has the same gap and fix it in the new helper if so.++### D5.3 — Options++| Option | Semantics |+| --- | --- |+| `path` (arg) | `.mthds` file or directory — same resolution as human `validate bundle` via the D5.2 helper. |+| `-L/--library-dir` | Repeatable, as in validate. Per D3.3 these dirs are the write scope beyond the entry file. |+| `--max-iterations` | `int \| None`, min 1; `None` → the `fix_loop_max_attempts` config default. |+| `--select` / `--ignore` | Repeatable fix-rule codes; mutually exclusive (both → exit 2); unknown code → exit 2 listing `KNOWN_FIX_CODES`. Same *behavior* as the agent command; the validation check is tiny — reuse `_reject_invalid_rule_filters` if its error presentation is plain enough for the human stream, else duplicate the two checks with `typer.secho` wording. |+| `--allow-signatures` | Mirrors the agent fix gate: without it, a valid-but-not-runnable result (pending signatures) exits 1 with the signatures listed; with it, exit 0. |+| `--diff` | Show, don't write (Phase C — see D5.6). |++Deliberately absent: `--format`/`--error-format` (human command — Rich console only; the two-stream convention is the agent CLI's); `--orchestrator` (validate-specific boot-verification flag; the fix loop re-validates in-process by design); `--pipe` (fix is whole-bundle); `--unsafe` (no UNSAFE rule in wave 1).++### D5.4 — Human rendering of `FixBundleResult`++Rendered via `get_console()` Rich markup matching `error_handlers.py` conventions (`escape()` on all interpolated strings, `❌`/`💡`/`✅` emoji register). Rendering lives in the fix command layer (`_fix_core.py` or a small sibling `_render.py`), **not** in `fix_render.py` — that module stays the CLI-free agent/API markdown renderer.++- **Valid after the loop** (fixes applied): `✅ Bundle fixed — valid`, the bundle path, then a numbered list naming every change (the step-5 exit bar): `SuggestedFix.description`, with the `fix_code` dim and the source file named when it isn't the entry bundle; then `Files written:` (each resolved path) and the iteration count. Exit 0.+- **Already valid** (`iterations == 0`, nothing applied): `✅ Bundle already valid`, exit 0.+- **Valid but not runnable** without `--allow-signatures`: pending signatures listed, `💡 Tip:` explaining `--allow-signatures` vs providing implementations, exit 1 (mirrors the agent gate).+- **Still invalid**: what *was* applied (same named-change list — partial progress is normal), the `bail_reason` when present (the loop's bail wordings are already human-actionable, e.g. the out-of-scope one names the `-L` remedy), then the remaining errors rendered through the **same item renderer as validate** (D5.5) so the two commands can't drift, then the standard tip/links block. Exit 1.+- **No verdict** (bad path, ambiguous bundle, init failure, unexpected exception): exit 2, same handler cascade as human validate.++Exit codes are presentation; the human-facing "contract" is the rendered text. Ops are never rendered — `description` only, per the master plan.++### D5.5 — The `💡 Suggested fix:` line: route the human renderer through the shared items++Rewrite `_display_validation_error_details` to consume `ValidationErrorItem`s instead of the raw exception lists — `handle_validate_bundle_error` already computes `exc.to_error_report()` at `error_handlers.py:330`, so the items (with `suggested_fix` attached by the one shared builder) are already in hand; the renderer signature changes to take the report's items (or the exception grows nothing). Group items by `category` to keep the current section headers (`Blueprint Validation Errors:` / `Pipe Validation Errors:` / dry-run), keep the per-error field lines as today (every printed field exists on the item), and append per item, when `suggested_fix` is present:++```+ [green]💡 Suggested fix:[/green] {escape(item.suggested_fix.description)}+```++After the error sections, when at least one item is fixable, one actionable footer (this is the doctrine's "a hint needs an action behind it"): `💡 {n} of these errors can be fixed automatically — run: pipelex fix bundle {bundle_path}` (append the `-L` dirs when the invocation had them — thread `library_dirs` into `handle_validate_bundle_error` alongside the existing `bundle_path` param). The existing generic `💡 Tip:` line stays but yields to the footer when fixes exist (two stacked 💡 tips is noise — prefer the actionable one).++Why item-routing over calling the planner inline per raw error (the master plan names both): one engine feeding every surface is the track's guiding principle; the planner then runs in exactly one place (`build_validation_error_items`); and the item renderer is exactly what D5.4's still-invalid arm needs for `remaining_errors` (which are already items) — inline planner calls would leave the human path as the one surface with private wiring, which is the disease this track exists to cure. Fallback if item-routing churns the human output in ways review rejects: the planner functions are pure and take one raw error-data item, so the inline form stays a cheap plan B.++**Deliberate behavior change to pin:** the raw-list renderer silently skips `factory_errors`; the items include them (`PIPE_FACTORY` category). Routing through items makes factory errors visible in human validate output for the first time — that's a fix, not a regression (flag-and-fix rule); pin it with a test and note it in the CHANGELOG.++### D5.6 — `--diff` preview via a temp-copy sandbox (Phase C, cuttable)++The loop has no no-write mode, and re-validation loads from disk — so an honest preview runs the real loop against copies: mirror the entry file and each **explicit** `-L` dir into a scratch dir (preserving relative layout), remap `library_dirs` to the copies, run `fix_bundle_file` there, then render a unified diff (original vs copy) for each `files_written`, via Rich syntax highlighting. Originals untouched (pinned by test); exit codes keep the same verdict semantics (0 valid-after / 1 still-invalid) so `--diff` answers "would it converge?". Ambient-resolved dirs are not copied — they're read-only under D3.3 in the real run too, so behavior matches. Entry-only invocations (no `-L`) copy just the entry file and pass `library_dirs` through unchanged (`None` stays `None`: ambient dirs load identically from the copy's run since they're absolute).++If the temp-copy mechanics surface real complications (path remapping in rendered output, ambient-dir edge cases), cut the flag to a deferred item at the mid-step checkpoint — the exit criteria don't need it.++## Phases (TDD — red tests first per layer)++### Phase A — `pipelex fix bundle` — DONE++- [x] Factor the human bundle-path resolution helper (`commands/bundle_path_resolver.py`) out of `validate/bundle_cmd.py`; validate's existing tests stay green; check/fix the `~`-expansion gap (D5.2); unit tests for the helper.+- [x] `commands/fix/` package: `app.py`, `bundle_cmd.py`, `_fix_core.py`; registration in `_cli.py` (`_CORE_COMMAND_ORDER` + `add_typer`) (D5.1).+- [x] Options + validation: `--select`/`--ignore` mutual exclusion and unknown-code rejection (exit 2), `--max-iterations` min 1, `--allow-signatures` gate (D5.3).+- [x] Human rendering of all five verdict arms (D5.4), with unit tests asserting rendered output per arm (patched `fix_bundle_file`) at `tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py`.+- [x] Integration: `tests/integration/pipelex/cli/test_fix_bundle_human.py` against the real loop on `tmp_path` bundles: fixable → exit 0 + file fixed on disk; unfixable → rendered failure + exit 1; `--select` honored; directory mode.+- [x] E2E: subprocess `pipelex fix bundle` at `tests/e2e/pipelex/cli/test_fix_bundle_cmd.py`, reusing the agent hermetic-HOME harness via a local conftest re-export.++### Phase B — `💡 Suggested fix:` in validate rendering — DONE++- [x] Tests: `tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py` (💡 line, footer with `-L` echo, footer-replaces-tip, factory-error section, dry-run kept lossless) + integration pin `tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py`.+- [x] Rewrote `_display_validation_error_details` into the item-driven `display_validation_error_items` (D5.5); threaded `library_dirs` into `handle_validate_bundle_error` for the footer; section headers and per-field lines kept byte-comparable wherever the item carries the same data.+- [x] Wired D5.4's still-invalid arm to the same item renderer (remaining_errors) — one renderer, two commands.++### CHECKPOINT A (mid-step) — CLEARED++The step-5 exit criteria are functionally met: a human sees the suggestion in `validate` and applies it with `fix`, with output naming every change. Committed; status block updated. **GO on `--diff`** (see status block for the recorded sandbox-layout subtlety).++### Phase C — `--diff` preview — DONE (GO)++- [x] Temp-copy sandbox (`commands/fix/_diff_sandbox.py`: `mirror_bundle_for_preview` + `PreviewSandbox.to_original`) + diff rendering (`_print_preview_diffs`, would-be labels via `preview=True` in the result renderer, copy→original path remap for display); unit tests for the copy/remap helper (`test_diff_sandbox.py`) incl. the entry-inside-`-L`-dir layout subtlety; integration pins: `--diff` on a fixable bundle prints the diff with ORIGINAL paths, originals byte-identical, exit codes match the write-mode verdicts (0 would-converge / 1 would-still-be-invalid).++### Phase D — docs, changelog, gates — DONE++- [x] CHANGELOG `[Unreleased]`: `pipelex fix bundle` (+`--diff`), `💡 Suggested fix:` lines + actionable footer, item-routed human rendering changes (factory errors, parse-level message, pipe-error source), `~`-expansion fix, telemetry-label fix.+- [x] Repo docs sweep: new `docs/tools/cli/fix.md` reference page (+ mkdocs nav); fix rows/links added to `docs/tools/cli/index.md`, `docs/tools/cli/validate.md` ("Suggested Fixes" section), `docs/features/cli.md` (human + agent tables — the agent `fix` row was missing since step 4).+- [x] `make agent-check` green; full `make agent-test` green.++### Exit — CHECKPOINT B (step-5 exit) — DONE++House pattern followed: `/code-review` fan-out on the step-5 diff (workflow-backed, high effort). Its verify stage collapsed on a session limit (13/13 verifiers errored), so the 19 finder candidates were triaged by hand against the code — full record in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md).++- **Fixed on this branch (confirmed bugs):** mkdocs nav orphan (`fix.md` was in the llmstxt page-map, not the site `nav:`); the validate footer built its `pipelex fix bundle` command without shell quoting (breaks on paths with spaces → `shlex.join`); `fix`'s still-invalid tip claimed "no deterministic safe fix" even when remaining errors still carried a 💡 suggested-fix line (`--select`/`--ignore`/out-of-scope/bail) → tip now conditional; `--diff` printed "Bundle is valid but NOT yet runnable" non-conditionally though nothing was written → preview-aware wording; `--diff` crashed + mislabeled + diverged from the real run on a missing `-L` dir → the sandbox now mirrors a missing dir as an empty copy (matching the loader's skip).+- **Deferred (real, but tradeoffs / niche / DRY):** validate footer over-counts fixable errors vs the loop's applicability gates; `--diff` `-L` dirs aren't deduped by resolved path; `resolve_bundle_target` and `_reject_invalid_rule_filters` are duplicated across the human and agent CLIs; a currently-unreachable dry-run-message drop in `fix`'s still-invalid arm. See the deferred doc for the recommendations.+- **Rejected:** the finder's suggestion to inline `item.category == DRY_RUN` instead of the `is_dry_run` property — the property is the house-preferred form (exhaustive-match on the enum).++Gates: `make agent-check` 0 errors; targeted CLI unit + integration suites and the fix-bundle e2e pass after the fixes.++## Test map (new / extended)++- `tests/unit/pipelex/cli/` — human fix command format tests (patched loop; all verdict arms; option validation), bundle-path-resolver helper tests, validate-rendering 💡 tests (Phase B pins).+- `tests/integration/pipelex/cli/` — `test_fix_bundle_human.py` mirroring `test_agent_fix_bundle.py`; validate-output integration pin for the 💡 line on a real fixable fixture.+- `tests/e2e/` — subprocess `pipelex fix bundle` (harness per Phase A's finding).+- Phase C adds copy-sandbox unit tests + the originals-untouched integration pin.++## Cold-start pointers++- Fixtures: `tests/data/fixes/` holds `<name>.mthds` + `<name>.golden.mthds` pairs per rule — reuse them (always on `tmp_path` copies; the command mutates files).+- Unit tests drive the loop with `mocker.patch("pipelex.pipeline.fixes.fix_loop.validate_bundle", side_effect=[...])` and patch `...fix_loop.resolve_library_dirs` for ambient-dir cases; pass `max_iterations` explicitly to avoid needing a booted config (step-3/4 doc, implementation record).+- Golden `.mthds` fixtures are processed by `plxt format` during `make agent-check` — write, format, then derive goldens; fresh worktrees need `pipelex-dev generate-mthds-schema` before `plxt lint`.+- A dotted `main_pipe = "domain.pipe"` is itself invalid (strip-namespace fires) — multi-file fixtures must use the bare form.+- Known-inert collision gap in `_split_cross_file_collisions` (intra-round duplicate bare codes): documented in [pr-1035-review-notes.md](pr-1035-review-notes.md) — don't re-report it; revisit only if blueprint-parse error accumulation changes.++## Step-6 hand-off++Step 6 is the release train (see [master-plan.md](master-plan.md) step 6). Two things this step deliberately did **not** absorb — they belong to the release cut, not to step 5:++- **The release CHANGELOG entry must name the additive `suggested_fix` wire field** now surfacing in `/validate` API payloads (deferred item 1c in the design doc). Step 5's `[Unreleased]` entries cover the human/agent CLI surfaces; the API wire-field mention is a release-train line.+- **Regenerate the conformance fixture** that pins the `/validate` error body (deferred item 2, sibling `conformance/` repo), then bump the pipelex-api pin when the runner picks up the version.++Carry-in from Checkpoint B (in [deferred-checkpoint-e-review-items.md](deferred-checkpoint-e-review-items.md)) — not release blockers, fold into wave 2 unless they surface sooner: the validate footer over-count (item A) and the `--diff` `-L` dedup (item B) are the two with user-visible edge cases; the cross-CLI resolver/filter duplications (items C, D) are the natural next shared-abstraction refactor.++The branch is otherwise PR-ready: `feature/Autofix-step5` off `611644e82`, gates green.diff --git a/wip/autofix/suggested-fixes-design.md b/wip/autofix/suggested-fixes-design.mdnew file mode 100644index 000000000..a854e3579--- /dev/null+++ b/wip/autofix/suggested-fixes-design.md@@ -0,0 +1,216 @@+# Suggested fixes on validation diagnostics++Design for deterministic auto-fixing of `.mthds` bundles. Supersedes [old-plan-to-auto-fix.md](old-plan-to-auto-fix.md) (the `feature/Bundle-fixer` approach).++## Decisions taken (2026-07-07, with Louis)++- **D1 — Fixes attach to diagnostics.** Each fixable `ValidationErrorItem` carries a structured `suggested_fix`. The `fix` command is just "apply what validate found", in a loop. No standalone fix engine that re-derives problems.+- **D2 — Runtime-only wire first.** `suggested_fix` is an additive, optional, pipelex-owned field. Formal promotion into the MTHDS protocol (spec + conformance + downstream schema copies in mthds / mthds-js / mthds-python) is a later wave, once the shape is proven.+- **D3 — Wave 1 consumer = agent CLI + skills.** `pipelex-agent fix` with the convergence loop, consumed by the `mthds-fix` skill and hooks. API `POST /fix`, MCP `mthds_fix` tool, and VS Code quick fixes are later waves.+- **D4 — Pruning rules cut from wave 1.** `prune-unreachable` / `prune-unused-concepts` are cleanups, not fixes — nothing is broken when they'd fire. Salvage the graph-walk logic later as opt-in lint warnings with attached fixes. Wave 1 is purely "make invalid bundles valid".++## Why this shape (and why not the old branch's)++The old branch built a separate fix engine that re-implemented the validation pipeline (`_load_blueprint_and_pipes` hand-copied `validate_bundle`'s phases) and re-derived the correct values on its own. Two engines computing the same truths is a drift machine, and a fix computed inside a command is invisible to every other consumer (API, MCP, VS Code, skills).++The decisive observation: **the validator already knows the correct value at detection time.** `PipeSequence.validate_output_with_library` (`pipelex/pipe_controllers/sequence/pipe_sequence.py:63-115`) compares the declared output against the last step's output and already ships the correct concept in the error (`provided_concept_code`). `generic_validate_inputs_with_library` (`pipelex/core/pipes/pipe_abstract.py:264`) compares declared inputs against `needed_inputs()`. So fixability comes from **richer typed errors**, not from a smarter fixer: enrich the error to carry the expected value, and fix construction becomes a mechanical translation that cannot drift from the validator.++This also matches the workspace's presentation-vs-contract principle (`docs/specs/pipelex-mthds-protocol.md`): the fix ops are contract data on the structured report; any rendered diff is presentation. One validation engine keeps feeding every surface.++## Architecture++Three layers, all in `pipelex/`:++1. **Enriched typed errors** (validator sites). Where a validator computes the expected value, it puts that value on the typed error as structured fields (e.g. the expected output ref including multiplicity, the full needed-inputs mapping). Validators gain no TOML knowledge — they state semantic facts. This is valuable even without autofix: it makes error messages and agent-facing explanations better.+2. **Fix planner** (one module, e.g. `pipelex/pipeline/fixes/`). Translates enriched typed errors into `SuggestedFix` payloads: semantic patch ops addressed by TOML path. Keyed strictly off `error_type` + structured fields — never message strings. The planner runs inside report assembly (`build_validation_error_items` / `build_validation_report`), so every consumer of the report sees fixes with zero extra plumbing.+3. **Applier + loop** (tomlkit-based). Applies ops to the raw file's tomlkit DOM (style-preserving), per file. The `fix` command loops: validate → collect safe fixes → apply → re-validate, until fixed-point.++### Wire model (wave 1, runtime-only per D2)++```python+class FixOpKind(StrEnum):+ SET_KEY = "set_key" # set (or create) a key's value at a table path+ DELETE_KEY = "delete_key"+ DELETE_TABLE = "delete_table"+ RENAME_TABLE_KEY = "rename_table_key" # position-preserving; needed for strip-namespace (stretch)++class FixOp(BaseModel):+ kind: FixOpKind+ table_path: list[str] # e.g. ["pipe", "my_seq"] — aligned with field_path conventions+ key: str | None+ value: TomlValue | None # TOML-representable+ new_key: str | None # rename only++class SuggestedFix(BaseModel):+ fix_code: str # kebab-case rule id, e.g. "match-sequence-output"+ description: str # human/agent-readable, e.g. "Set output to 'Report[]' to match last step"+ safety: FixSafety # SAFE (auto-appliable) | UNSAFE (opt-in)+ source: str | None # file the ops target (multi-file libraries)+ ops: list[FixOp]+```++`ValidationErrorItem` gains `suggested_fix: SuggestedFix | None = None`. Serialization stays `exclude_none`, so nothing changes for non-fixable errors. Naming is brand-neutral (language-level concept — no `pipelex_` prefixes in field names).++Note `ValidationErrorItem` flows through the hosted API's `InvalidReport` too, so the field will *appear* on the API wire as soon as it exists — that's fine and additive; what D2 defers is the formal contract work (spec sections, conformance tests, downstream schema mirrors), not hiding the field.++### The applier++- tomlkit DOM per file (`load_toml_with_tomlkit` / `save_toml_to_path` in `pipelex/tools/misc/toml_utils.py` already exist). Comments, ordering, and table style of untouched content survive by construction.+- **In-place mutation, never rebuild.** For `sync-controller-inputs`, update/delete/add keys inside the existing `inputs` table rather than replacing it with a fresh inline table (the old branch's rebuild discarded comments and forced inline style).+- **Position-preserving rename** for `RENAME_TABLE_KEY` (the old branch's `del` + re-add sent renamed pipes to the bottom of `[pipe]`). If tomlkit makes this too fiddly, `strip-namespace` stays out of wave 1 rather than shipping the reordering bug.+- **Guarded application**: an op only applies if its target path exists in the DOM. This protects against errors raised on elaborated/synthetic constructs (`BundleElaborator` synthesizes sequences from `structuring_method = "preliminary_text"` — those pipes have no TOML to patch) and against ops targeting a different file than the one being patched.+- **Idempotent**: applying the same fix twice is a no-op.++### The convergence loop (`fix` command)++```+loop (max_iterations, default 5):+ report = validate_bundle(...) # THE validator — no parallel pipeline+ fixes = [e.suggested_fix for e in errors if fix is SAFE and selected]+ if no fixes: break+ if fingerprint(fixes) seen before: break # no-progress bail, report loudly+ apply fixes per file; write+final: re-validate, report is_valid + fixes_applied + remaining errors+```++Cascades are expected (fixing a sequence's output can surface a downstream input mismatch) — the loop is the design, not a fallback. The old branch's "fixes are convergent in a single pass" was asserted, never proven; here non-convergence is a first-class, loudly-reported outcome, and the loop-with-fingerprint makes it impossible to spin.++## Wave 1 fix rules++| fix_code | Trigger (typed) | Fix | Safety |+| --- | --- | --- | --- |+| `match-sequence-output` | `INADEQUATE_OUTPUT_CONCEPT` / `INADEQUATE_OUTPUT_MULTIPLICITY` on a **PipeSequence** | `set_key` the sequence's `output` to the last step's effective output (concept + multiplicity, honoring the sub-pipe multiplicity override) | SAFE |+| `sync-controller-inputs` | `MISSING_INPUT_VARIABLE` / `EXTRANEOUS_INPUT_VARIABLE` / `INPUT_STUFF_SPEC_MISMATCH` on a **controller** pipe | In-place sync of the `inputs` table with `needed_inputs()` | SAFE |+| `strip-native-concept-redecl` | Blueprint validation error for redeclared native concept | `delete_table` / `delete_key` for `[concept.X]` or inline `concept.X = "..."` | SAFE |+| `strip-namespace` (stretch) | `INVALID_PIPE_CODE_SYNTAX` from same-domain dotted pipe codes | Position-preserving rename + rewrite of internal refs (`steps`, `branches`, `branch_pipe_code`, `outcomes`, `default_outcome`, `main_pipe`) | SAFE, but gated on rename mechanics |++Explicitly **not** fixable (ambiguous, requires judgment): PipeParallel/PipeCondition output choice, `INPUT_STUFF_SPEC_MISMATCH` on operator pipes, generating missing concepts, anything on signature pipes (signatures are `pending_signatures`, never errors — the fixer must never touch them). The old branch's `fix-list-notation` is dropped: it fired unconditionally rather than off errors, only ever added `[]`, and predates the optionals grammar; if the underlying case matters it should resurface as a properly error-driven rule.++### Rule-level guards (lessons from the drift analysis)++- **Optionals markers `?` / `!`**: any rewrite of an input/output ref must preserve the author's presence markers. The validator deliberately does not compare presence markers in `INPUT_STUFF_SPEC_MISMATCH` — so `sync-controller-inputs` keeps the user's marker whenever concept + multiplicity already match, and only derives markers for inputs it adds.+- **Prerequisite-clean rule**: a fix is only emitted when its inputs are trustworthy. If a pipe also has `UNRESOLVED_PIPE_DEPENDENCY` / `UNRESOLVED_CONCEPT` errors, `needed_inputs()` is incomplete — the planner must not emit `sync-controller-inputs` for it. Generally: co-errors on the same pipe that undermine the derivation suppress the fix for that iteration (the loop picks it up next round once the prerequisite is fixed).+- **Multi-file libraries**: fixes target the file that *declares* the item (`ValidationErrorItem.source`), and only files the user passed to the command get written. Cross-package qualified refs are never rewritten.++## CLI surface (wave 1)++- `pipelex-agent fix bundle <files...>` (and the `pipelex fix` mirror), symmetric with `validate`. Flags: `-L/--library-dir`, `--diff` (show, don't write), `--select`/`--ignore` (mutually exclusive, rule codes), `--max-iterations`, `--format`/`--error-format` per the two-stream convention (markdown default on the agent CLI).+- `pipelex-agent validate` output gains the `suggested_fix` annotations automatically (same report) — agents benefit even without running `fix`.+- Contract vs presentation: the machine verdict is the structured body (`is_valid` after fixing, `fixes_applied[]`, remaining `validation_errors[]`). Exit codes are presentation: 0 = valid after fixes (or already valid), 1 = still invalid, 2 = no verdict (infra/args).+- The markdown renderer for fix results lives beside `validation_render.py` (CLI-free module) so the API can reuse it in wave 2.++## Testing (TDD)++- **Planner unit tests**: enriched typed error → expected `SuggestedFix` ops, per rule, including suppression cases (prerequisite co-errors, synthetic pipes, signature pipes, cross-package refs).+- **Applier golden tests**: fixture `.mthds` files with comments, mixed inline/block styles, deliberate ordering → apply ops → byte-compare against golden output. This is the regression net for format preservation, the thing the old branch never proved. Include idempotence (apply twice = same bytes).+- **Convergence tests**: a fixture needing multiple iterations (cascade); a deliberately non-convergent fixture that must bail cleanly with the no-progress report.+- **e2e CLI tests**: `fix bundle` JSON and markdown snapshots; `validate` output showing `suggested_fix` annotations.++## Phases++### Phase 0 — Spike: prove the chain end-to-end++One rule (`match-sequence-output`) through all three layers: enrich the `INADEQUATE_OUTPUT_*` errors with the expected output ref (concept + multiplicity — `provided_concept_code` exists but multiplicity needs adding), planner translation, tomlkit applier with the guarded/idempotent semantics, minimal loop, red-green tests at each layer. No CLI command yet — driven by tests.++**CHECKPOINT 0**: chain proven or design revised. Update this doc with findings (especially: does tomlkit in-place mutation preserve style as expected; what the enriched-error shape settled to).++**CHECKPOINT 0 findings (2026-07-07 — chain proven, design holds):**++- **tomlkit in-place mutation preserves style as promised.** Assigning `table["output"] = value` keeps the trailing comment *on the patched line itself*, plus all comments, key alignment, ordering, and inline/block table styles of untouched content. Golden byte-comparison tests pin it (`tests/data/fixes/`), including idempotence.+- **Enriched-error shape settled**: `expected_output_ref: str | None` on `PipeValidationError`, threaded to `PipesAndConceptValidationErrorData` by `categorize_pipe_validation_with_libraries_error`. Only the two `PipeSequence` raise sites set it — which is also the suppression mechanism: the planner requires the field, so PipeParallel / PipeCondition / operator `INADEQUATE_OUTPUT_*` errors are structurally unfixable, no pipe-type sniffing needed. Rendering: bare concept code when same-domain or native, qualified `domain.Code` otherwise; effective multiplicity honors the sub-pipe override; presence marker rides via `format_concept_with_multiplicity`. Kept internal (error-data only) — the wire gets only `suggested_fix` (D-R3).+- **Wire models** live in the new low-level `pipelex/suggested_fix.py` (stdlib + pydantic only) so `base_exceptions.py` imports it cycle-free. `ValidationErrorItem.suggested_fix` is additive; non-fixable items serialize byte-identically (pinned).+- **Loop mechanics verdict: works as designed.** `fix_bundle_file` reuses `validate_bundle` wholesale; fingerprint = `fix_code|source|per-op(kind:path:key:value)` string; bail fires when an iteration proposes only already-seen fingerprints (pinned via a synthetic-pipe skip that would otherwise spin); `iterations` counts apply rounds; one final validate decides the verdict after `max_iterations`. Cascade fixture (nested sequences) converged in 2 rounds — note validation aborts at the *first* `PipeValidationError`, so multi-error bundles converge error-by-error across iterations rather than batch-applying; fine for correctness, worth remembering for loop-count expectations in Phase 1.+- **One deviation**: `RENAME_TABLE_KEY` exists on the wire enum (per the sketch) but the applier raises `PipelexUnexpectedError` for it — position-preserving rename is Phase 1 work gated on the strip-namespace mechanics; no spike planner emits it.+- **Tooling gotchas for Phase 1**: golden `.mthds` fixtures are processed by `plxt format` during `make agent-check`, so fixtures must be format-stable (write them, run the formatter, then derive the golden); `plxt lint` needs `derived/mthds_schema.json` regenerated (`pipelex-dev generate-mthds-schema`) in fresh clones/worktrees.++### Phase 1 — Engine + remaining wave-1 rules++Harden the loop (fingerprint bail, multi-file targeting), add `sync-controller-inputs` (with the optionals-marker and prerequisite-clean guards) and `strip-native-concept-redecl`. Attempt position-preserving rename; ship `strip-namespace` only if it lands clean. `suggested_fix` lands on `ValidationErrorItem`.++**CHECKPOINT 1**: all wave-1 rules green with golden format-preservation tests. Decisions on strip-namespace recorded here.++**CHECKPOINT 1 findings — `sync-controller-inputs` (2026-07-07, step-2 Phase A):**++- **Enrichment shape settled as a *pair* of mappings**: `expected_inputs` (what the pipe should declare) **and** `declared_inputs` (what it declares today), both `dict[str, str] | None`, both rendered domain-relative, on `PipeValidationError` → `PipesAndConceptValidationErrorData`. The pair keeps the planner pure: it diffs two mappings instead of needing file access, and emits `set_key` per added/changed variable + `delete_key` per extraneous one (deterministic order → stable fingerprints). This is the first multi-op fix; `SuggestedFix`/`FixOp` absorbed it unchanged.+- **Rendering factored to `StuffSpec.to_bundle_representation(relative_to_domain=...)`** — the spike's inline rendering in `PipeSequence` now reuses it; declared-spec renderings preserve the author's `?`/`!` markers when concept+multiplicity already match (presence is deliberately outside the drift contract).+- **Only the raise sites holding `the_needed_inputs` are enriched.** The `required_variables()` site stays bare: for a PipeCondition it fires for expression variables whose needed spec would come from the declared inputs themselves (unknowable, and `needed_inputs()` raises `InputStuffSpecNotFoundError` there). Suppression stays structural.+- **Prerequisite-clean guard needed no code**: library validation resolves all pipe dependencies (raising `UNRESOLVED_PIPE_DEPENDENCY` immediately) *before* any `validate_with_libraries()` runs, and skips controllers with unresolved cross-package deps — co-occurrence is impossible by ordering; pinned by test.+- **PipeLLM's missing/extraneous prompt-variable errors live on the blueprint channel** (static validation at model construction, reconstructed from pydantic messages), not the pipe-validation channel — structurally out of the planner's reach, pinned by test.+- **`TomlValue` widened** to `TomlScalar | dict[str, TomlScalar]` for the no-`inputs`-table case (one `set_key` writes the whole mapping as an inline table). First container value on the wire enum's `value` slot; nothing else bent.+- **Applier finding — inline-table canonicalization (superseded by Phase A′; kept for history).** tomlkit's incremental edits inside inline tables leave non-canonical whitespace (`{ a = "x", b = "y"}`). The Phase A cut hand-canonicalized this in the applier (re-emit the mutated inline table with `{ key = value, ... }` spacing, trivia transplant), and the checkpoint-A review corrected the string-assembly crashes by building via `tomlkit.inline_table()` + outer-brace splice. **Phase A′ deletes all of that** — see the next section. The reviewers' recurring "why not just use `plxt`?" question is exactly what A′ answers: the *runtime* toolchain library `pipelex-tools-py` (in-process, distinct from the `plxt` CLI dev-dep) now owns canonical formatting.++**CHECKPOINT 1′ — `format_mthds` canonical-output backend (2026-07-07, step-2 Phase A′):**++- **Decision (Louis): ADOPT `pipelex_tools.format_mthds` as the single source of canonical style.** Added `pipelex-tools-py` as a **core runtime dependency** (import `pipelex_tools`; the in-process PyO3 extension built from `vscode-pipelex/crates/pipelex-py`, *distinct* from the `pipelex-tools` CLI-binary dev-dep — same `taplo`/MTHDS engine as `plxt`, embedded schema, offline, PEP 561 stubs; already a runtime dep of `pipelex-api`, precedent). This dissolves the "why not plxt?" tension: the earlier objection (dev-only Rust binary, no Python API, whole-file, breaks surgical byte-preservation) doesn't apply to the in-process library, and the fix tool *wants* whole-file canonical output anyway.+- **Applier is now pure mutation.** Deleted the hand-rolled `_canonical_inline_table` and `_canonicalize_mutated_inline_table` (and their two call sites). `apply_fix_ops` mutates the tomlkit DOM and stops there. The new `applier.serialize_and_format(toml_doc) -> str` dumps the DOM and hands it to `format_mthds`, which reflows inline-table/array spacing to canonical form; a `kind="syntax"` diagnostic means the applier emitted malformed TOML → `PipelexUnexpectedError` (never silently written). `fix_loop` writes `serialize_and_format(...)` instead of `save_toml_to_path(...)`.+- **Output philosophy shift (intended): surgical byte-preservation → canonical whole-file MTHDS.** Correct for a file-rewriting fix tool, and a no-op on already-formatted files (the norm — MTHDS is formatted on save + CI-enforced). Consequence surfaced by the loop tests: on a *hand-drifted, unaligned* fixture the formatter column-aligns single-line tables (`output = "x"` → `output = "x"`), so convergence-test assertions moved from whitespace-coupled string counts to semantic reload checks (parse the fixed file, assert field values). This is the A′ design *working*, not a regression — re-validation passing already proves the fixes are correct.+- **Deviation from the literal plan, recorded:** the plan said "pass a plain dict on the whole-mapping `SET_KEY`, `format_mthds` canonicalizes it." Empirically a plain-dict assignment makes tomlkit emit a **detached `[pipe.x.inputs]` block table at end-of-file**, and `format_mthds` preserves block-vs-inline (it doesn't convert). So `_as_tomlkit_value` keeps a **minimal** `tomlkit.inline_table()` builder (no string-splicing, no brace-padding — the fragile parts are gone; tomlkit owns key quoting/value rendering, `format_mthds` owns spacing) so a freshly-created mapping stays inline and attached to its pipe. This reproduces every existing golden byte-for-byte (no golden regeneration needed) and gives strictly nicer output than a detached block table.+- **Goldens are now the `format_mthds` canonical output.** The applier golden tests (`test_fix_applier*.py`) route byte-compares through `serialize_and_format`; the F1 dotted-key and F2 whole-pipe-inline regression tests pass *by construction* now (the real parser can't crash on valid TOML, unlike the deleted hand-rolled canonicalizer). All four pre-existing goldens were unchanged.+- **`pipelex_tools` stub/runtime drift gotcha (found during review triage).** The PEP 561 stub declares `Diagnostic` / `Range` / `FormatResult` / `LintResult` in `__all__`, but those are **type-only** TypedDicts — not runtime exports of the compiled module. So `from pipelex_tools import Diagnostic` type-checks (pyright/mypy read the stub) yet raises `ImportError` at runtime. `applier.py` imports `Diagnostic` under a `TYPE_CHECKING` guard (quoted annotation) and imports only the real callable `format_mthds` at runtime. Since `pipelex-tools-py` is ours, Louis is fixing the drift upstream; the follow-up to simplify our workaround once it ships is tracked in [deferred-checkpoint-a-prime-review-items.md](deferred-checkpoint-a-prime-review-items.md) (item 1), which also carries a Phase-C exploration note (item 2: an upstream rename / canonical-ordering primitive, since `format_mthds` reflows spacing but does not reorder tables).++**CHECKPOINT B — `strip-native-concept-redecl` (2026-07-07, step-2 Phase B): blueprint channel opened end-to-end.**++- **The blueprint channel now runs the planner.** `build_validation_error_items`' blueprint loop calls `plan_fix_for_blueprint_validation_error(...)`, mirroring the pipe loop — so a blueprint-validation error can now ride a `suggested_fix`. This is the first fix that is **not** a pipe-validation fix and the first whose `SuggestedFix.source` is populated from real validation (blueprint error data carries `source` from `blueprint_dict["source"]`; the pipe raise sites still emit `source=None`).+- **Enrichment = typed raise + structural unwrap, no message matching.** `validate_concept_keys` raised a bare `ValueError` whose only carrier of the offending concept code was the message text (pydantic `loc` is just `("concept",)`, so the concept categorizer produced `error_type=None`, `concept_code=None`). Replaced it with `NativeConceptRedeclarationError(ValueError)` carrying `concept_code`; because it subclasses `ValueError`, a `mode="before"` field validator can raise it and pydantic preserves it in `ctx["error"]`. The blueprint categorizer unwraps it structurally (`_extract_wrapped_native_concept_redeclaration_error`, the exact pattern of `extract_wrapped_pipe_validation_error`) — placed **before** the scope dispatch so it wins over the un-enriched concept-scope path. The other bare `ValueError` in the same validator (invalid concept-code *syntax*) is left untyped → stays uncategorized → no fix (structural suppression; pinned by test).+- **Enum home decision: widen the shared `PipeValidationErrorType`, do not add a new enum.** The field type of `PipelexBundleBlueprintValidationErrorData.error_type` is `PipeValidationErrorType | None`, and that enum is already the de-facto MTHDS *validation-error-type* enum (it holds concept-scope values like `UNRESOLVED_CONCEPT`), despite the legacy `Pipe`-prefixed name. Added `NATIVE_CONCEPT_REDECLARATION` there — smallest correct surface, field type unchanged, wire projection unchanged. Did **not** resurrect the deleted `PipelexBundleBlueprintFixableErrorType` stub. Cost: the enum has exhaustive `@property` match/case methods, so the new value had to be added to `is_controller_input_drift` / `is_inadequate_output` (False arms) and a new single-case `is_native_concept_redeclaration` property added (house style: single-out-one-case via a property, never enum equality).+- **The applier needed no new code.** `DELETE_KEY` on `["concept"]` (key = the offending code) covers **every** authoring form — `[concept.X]` table (incl. a `[concept.X.structure]` sub-table, deleted with it), `X = "…"` string shorthand under `[concept]`, and dotted `concept.X` — because tomlkit represents all three as a `concept` table keyed by the code. `format_mthds` keeps dotted keys dotted (just column-aligns), so a dotted fixture is a genuine, format-stable authoring form. Golden byte-compare across all three forms.+- **Source-guard first live exercise.** With a populated `source`, the loop's `Path(source) == mthds_file_path` check applies the fix single-file (convergence test) **and** under `library_dirs` when the source is the file being fixed (positive complement to the pre-existing source-*less*-dropped test). Multi-redeclaration bundles converge error-by-error (the `mode="before"` validator raises on the first offending code per pass) — the same cascade shape as the pipe channel, now on the blueprint channel.+- **Known minor artifact (not fixed, low value):** deleting a `[concept.X]` table whose *leading* line is a standalone comment reflows that comment onto the successor element (tomlkit trivia behavior; `format_mthds` doesn't reposition it). Comments on *untouched* content are preserved (that is the guarantee). Fixtures put comments on surviving content to keep the goldens clean; a comment sitting directly on the deleted concept is the only thing that can dangle. Acceptable for a fix tool whose output the author reviews (and which CI reformats).+- **Abstraction verdict so far:** `SuggestedFix`/`FixOp` absorbed the delete-shaped fix and the blueprint channel **unchanged** — the only new wiring was one planner function + one builder-loop call. The remaining stress (position-preserving rename, array-of-tables addressing) is Phase C's to produce.++**CHECKPOINT C — `strip-namespace` rename-mechanics spike (2026-07-07, step-2 Phase C.1): the gate opens.**++The spike answered both gating questions in favor of building the rule, and — unexpectedly — the scary one dissolves entirely:++- **Position-preserving rename is achievable.** tomlkit's `Container._replace(old_key, new_key, item)` renames a `[pipe]` sub-table key **in place**: it does `self._body[idx] = (new_key, value)` and `value.invalidate_display_name()`, so the renamed table keeps its position among siblings, its leading standalone comment and trailing inline comments, and re-renders the header with correct quoting (`[pipe."greetings.hello"]` → `[pipe.hello]`). The old `feature/Bundle-fixer` reordering bug came from `del` + re-add (append semantics send the pipe to the bottom); `_replace` sidesteps it. Verified end-to-end in the **full runtime context** — after `Pipelex.make()` + a real `validate_bundle`, serialized through `format_mthds` (no syntax diagnostics), then re-validated VALID — plus idempotence (re-apply skips: key absent) and collision suppression (bare code already declared → skip). The single wart: `_replace` is a tomlkit **private** method; a golden byte-compare test is the CI tripwire if a tomlkit bump changes its semantics (pin is `tomlkit>=0.13.2`). `format_mthds` does not reorder tables, so no upstream ordering primitive was needed — dissolving the Phase-C exploration note (item 2 of [deferred-checkpoint-a-prime-review-items.md](deferred-checkpoint-a-prime-review-items.md)).++- **The array-of-tables addressing gap NEVER needs crossing** — this is the decisive finding, and it inverts the plan's premise. The plan assumed `strip-namespace` must rewrite every internal reference (`steps[].pipe`, `branches[].pipe`, …) to the renamed pipe, and that addressing items inside arrays would force a `FixOp.table_path` extension. Two empirical facts collapse that whole line of work: **(1)** a same-domain **qualified** reference (`greetings.hello`) already resolves to the bare pipe `hello` in domain `greetings` (pinned by validating a bundle whose `steps[].pipe` uses the qualified form against a bare declaration → VALID); **(2)** **no** controller reference field runs a snake_case check — only the pipe-declaration keys (`validate_pipe_keys`) and `main_pipe` (`validate_main_pipe_syntax`) do. So the *only* things that make a same-domain-dotted bundle invalid are the **declaration key** and (if the author over-qualified it) **`main_pipe`**. Fixing those — a rename of the `[pipe]` key and a root `set_key` — makes the bundle valid; the `steps[].pipe` references keep resolving untouched (leaving them qualified is a style nit, not a validity error, and normalization is a wave-2 lint concern per D4). **`FixOp.table_path: list[str]` stays unchanged; no index segments, no new op kind.**++- **Architecture: the same Phase B pattern, no blueprint needed.** `INVALID_PIPE_CODE_SYNTAX` is raised in a `mode="before"` validator, so the blueprint never constructs and `collect_pipe_references()` is unavailable — but since references need no rewrite, the planner needs only the offending code + stripped code + which site (pipe key vs `main_pipe`), all rideable on a typed exception exactly as `NativeConceptRedeclarationError` carried `concept_code` in Phase B. No planner→blueprint access, no message matching.++- **Verdict: GO** (Louis confirmed 2026-07-07) — **implemented and landed.** Rationale: the mechanics gate is clean, the abstraction holds **unchanged** (the strongest possible verdict is proving `RENAME_TABLE_KEY` end-to-end rather than declaring it unproven), and the implementation is small and follows Phase B. The rule's niche trigger (a quoted-dotted declaration `[pipe."domain.code"]`, typically machine-generated) is a minor concern for an opt-in fix that costs nothing when not triggered.++**CHECKPOINT C outcome — `strip-namespace` landed:**++- **Enrichment = typed raise + structural unwrap, no message matching** (the Phase B pattern). `InvalidPipeCodeSyntaxError(ValueError)` carries `offending_code` + `stripped_code`, raised at `validate_pipe_keys` / `validate_main_pipe_syntax` **only when safely strippable** (the `_strippable_same_domain_pipe_code` gate: prefix == own `domain`, valid snake_case bare tail, and for a declaration no collision with an existing bare key). Both validators gained an `info: ValidationInfo` param to read `domain` from `info.data` (field order guarantees `domain` is validated first). The categorizer unwraps structurally and sets `stripped_pipe_code`, with `pipe_code` discriminating the two raise sites (offending dotted key for a rename; `None` for `main_pipe`, read from `loc`). Bare-`ValueError` codes (malformed, cross-package) still flow through the message-matching categorizer → `INVALID_PIPE_CODE_SYNTAX` without `stripped_pipe_code` → unfixable.+- **`RENAME_TABLE_KEY` is the last op kind, now proven.** The applier implements it via tomlkit's position-preserving `Container._replace` (reached through `_container_of`, since a `Table`'s dict facade doesn't expose it), with guarded skips on key-absent and collision. `main_pipe` reuses the existing root `SET_KEY`. `new_key` joined `_fix_fingerprint` (deferred item 1b closed).+- **Abstraction verdict: `SuggestedFix`/`FixOp` absorbed the rename-shaped fix UNCHANGED.** No wire-model change (no `table_path` widening, no new op kind — `RENAME_TABLE_KEY` was already on the enum), only its applier implementation + one planner branch + one enum property + one error-data field. This completes the wave-1 stress test: multi-op (Phase A), delete-shaped + blueprint channel (Phase B), and rename-shaped (Phase C) all rode the abstraction without bending it.+- **The one wart: reliance on tomlkit's private `Container._replace`.** It is tomlkit's own internal position-preserving primitive (what `__setitem__` uses to re-home an existing key); the public API only offers `del` + re-add, which appends to the bottom. The golden byte-compare test (`test_fix_applier_strip_namespace.py`) is the CI tripwire if a tomlkit bump changes its semantics (pin is `tomlkit>=0.13.2`).+- **Deviation from the plan's literal C.2 tasks (recorded):** the plan expected reference-rewrite ops driven by `collect_pipe_references()` and an array-of-tables addressing decision. Both were dropped: the C.1 spike proved same-domain qualified refs resolve, so references need no rewrite, and `collect_pipe_references()` is unavailable anyway (the blueprint aborts construction in a `mode="before"` validator). The fix strips only the two snake_case-enforcing sites.++### Step-2 exit — abstraction verdict (CHECKPOINT 1)++This is the gate the human-CLI step (master-plan step 5) reads. It consolidates the per-phase verdicts above into one statement.++**Verdict: `SuggestedFix`/`FixOp` survived every wave-1 fix shape with no structural change.** Step 2 deliberately added rules of four different *shapes* to stress the wire model before any human sees it; each rode the existing abstraction:++- **Multi-op, in-place table sync** (`sync-controller-inputs`, Phase A) — the first fix emitting more than one op (a `set_key` per added/changed variable + a `delete_key` per extraneous one). Rode `FixOp` unchanged. The one wire-level change in the *entire* step happened here and is a *value-type* widening, not a shape change: `TomlValue` (the type of `FixOp.value`) went from `TomlScalar` to `TomlScalar | dict[str, TomlScalar]`, so a single op can carry a whole inline-table mapping for the no-`inputs`-table case. `FixOp`'s fields, `SuggestedFix`'s fields, and the `table_path: list[str]` addressing were untouched.+- **Delete-shaped, on a new channel** (`strip-native-concept-redecl`, Phase B) — the first blueprint-channel fix and the first with a populated `SuggestedFix.source`. Rode the abstraction unchanged; the only new wiring was one planner function plus one call in the blueprint loop of `build_validation_error_items`. `DELETE_KEY` on `["concept"]` covered every authoring form with no new op kind.+- **Rename-shaped, position-preserving** (`strip-namespace`, Phase C) — exercised the last unexercised op kind, `RENAME_TABLE_KEY` (on the enum since the spike). It gained its applier implementation + `new_key` joined the loop fingerprint; no wire-model change. **The array-of-tables addressing extension the plan feared was never needed:** same-domain qualified refs (`steps[].pipe = "domain.code"`) keep resolving, and only declaration keys + `main_pipe` enforce snake_case, so the fix touches only those two sites — no `table_path` index segments, no new op kind.++So the human-CLI gate (master-plan step 5, bar 1 — "the abstraction has been stress-tested by rules of *different shapes* … so the wire shape and the `description` wording are known-stable before humans see them") **is met.** The wire shape is frozen for wave 1 modulo the additive `TomlValue` widening above; `description` stays a one-line human/agent string across all four rules.++**Warts carried forward** (not abstraction failures — honest caveats for the next steps):++- **`RENAME_TABLE_KEY` relies on tomlkit's private `Container._replace`** (the public API only offers `del`+re-add, which appends to the bottom and reintroduces the old branch's reordering bug). Mitigated by the golden byte-compare test as a CI tripwire on a tomlkit bump; pin is `tomlkit>=0.13.2`.+- **Canonical whole-file output** (Phase A′): the applier no longer preserves untouched bytes surgically — `serialize_and_format` reflows the whole file to canonical MTHDS style via `pipelex_tools.format_mthds`. Correct for a fix tool, a no-op on already-formatted files. The `pipelex_tools` stub/runtime `__all__` drift is worked around with a `TYPE_CHECKING` guard (upstream fix pending — [deferred-checkpoint-a-prime-review-items.md](deferred-checkpoint-a-prime-review-items.md) item 1).+- **Comment-reflow on `DELETE_KEY`**: a standalone comment sitting on the *deleted* element's leading line reflows onto the successor (tomlkit trivia). Comments on untouched content are preserved. Acceptable for author-reviewed, CI-reformatted output.+- **Loop maturity**: the source/file guard is exercised live (Phase B), but real multi-file targeting (populate `source` at every raise site; derive `is_single_file` from resolved dirs) is still step 3 (deferred items 0, 1). Two Phase-C behaviors — a one-rename-per-iteration convergence cap and the `main_pipe`-to-nonexistent-pipe strip — are deferred design tradeoffs, not bugs ([deferred-checkpoint-c-review-items.md](deferred-checkpoint-c-review-items.md)).++**strip-namespace decision: GO — shipped.** The stretch rule landed and `RENAME_TABLE_KEY` is proven end-to-end; recorded as the step-2 exit criterion in the master plan.++**Step-2 final review (2026-07-08).** An unanchored `/code-review` sub-agent (no plan/design context, diff pointer `5e62bd43c..HEAD` only) swept the whole step-2 diff and surfaced **one confirmed correctness bug**, fixed immediately (silent data loss, not a design tradeoff — so fixed, not deferred): `_rename_key_in_place` renamed only the **first** out-of-order sub-table holding the dotted key. A pipe whose header `[pipe."d.x"]` and whose block `[pipe."d.x".inputs]` straddle an intervening `[concept]` section carries the same dotted key `d.x` in *two* of the `OutOfOrderTableProxy`'s sub-tables, so the rename orphaned the pipe's `.inputs` under a phantom, still-invalid dotted key **while reporting the op APPLIED** — the file was mutated and left unfixable (the bare code now collides, so a re-strip is refused). Fix: rename in *every* chunk holding the key (the `DELETE_KEY` path was already safe — it uses tomlkit's public `__delitem__`, which removes from all chunks). Pinned by `test_rename_carries_nested_subtable_across_interleaved_chunks` (offending pipe with its own nested block sub-table split across chunks; the pre-existing interleaved fixtures never gave the offending pipe a nested sub-table, so this shape was uncovered). Everything else the review checked (categorizer `main_pipe` gating, the `StuffSpec.to_bundle_representation` refactor, `_expected_inputs_for_fix` flexible-type carve-out, the cross-file collision guard, enum match/case exhaustiveness, `_as_tomlkit_value`) it verified sound or already-documented. `make agent-check` + full `make agent-test` green after the fix.++### Phase 2 — CLI + docs + changelog++`pipelex-agent fix bundle` + `pipelex fix` commands, two-stream output, docs page (`docs/`), CHANGELOG entry ([Unreleased]). Update the `mthds-fix` skill guidance is wave-2 territory (plugins repo), but note the hand-off. Sequencing inside this phase is deliberate — agent command first, human CLI (`pipelex fix` + the `💡 Suggested fix` line in `validate`) last and gated on rule breadth + the apply command existing; see the master plan's "Sequencing doctrine".++**CHECKPOINT 2**: wave 1 shippable. `make agent-check` + `make agent-test` green. Record the hand-off list for wave 2.++### Wave 2 (separate plan, not scoped here)++Protocol promotion (spec sections in `docs/specs/`, conformance arm, schema sync to mthds / mthds-js / mthds-python), API `POST /fix`, MCP `mthds_fix` tool, VS Code `CodeActionProvider` (first code action in the LSP — keyed on `diag.code = error_type`, fix payloads already ride the validation backends), `mthds-fix` / pipelex-plugins skill updates, pruning rules as lint warnings with attached fixes.++## Salvage map from `feature/Bundle-fixer`++Worth harvesting (as reference, reimplemented under TDD): the `needed_inputs()` sync semantics and diff-message construction; the last-step-output derivation incl. multiplicity override; the `_should_strip` namespace guard (strip only when prefix == own domain AND bare code exists locally); the reachability BFS + concept transitive closure (for wave-2 pruning lints). Not worth harvesting: the orchestrator (parallel validation pipeline), the single-pass model, the inline-table rebuild, the unpopulated `line` field, the pyright blanket suppressions.diff --git a/wip/autofix/validation-error-reporting-plan.md b/wip/autofix/validation-error-reporting-plan.mdnew file mode 100644index 000000000..98e72b397--- /dev/null+++ b/wip/autofix/validation-error-reporting-plan.md@@ -0,0 +1,123 @@+# Validation-error reporting & surfacing — improvement plan++> **ARCHIVED — track COMPLETE (2026-07-09).** All phases done; the only open item is the release-gated `conformance/validate-error-qa/` corpus regen (folded into the autofix step-6 release train). The durable record now lives in the code, the wording-pinning tests (`test_validation_render.py`, `test_validate_bundle_error_format.py`, `test_handle_pipe_errors_suffix.py`, `test_fix_loop_bail.py`, and the `*_enrichment.py` suites), the CHANGELOG `[Unreleased]` entries, and the conformance corpus. The `wip/validation-reporting/` before/after captures + `phase0-inventory.md` + `writeup.html` referenced throughout were dogfooding artifacts, removed at archival — recoverable from git history (`d4fc4749a`, `4911b6b90`). Archived here from the worktree-root `TODOS.md`.++## Goal (use this as the /goal)++Perfect, clear validation-error reports and fix reports on every surface: every validation error must state — in MTHDS author syntax, never internal repr — what is wrong, where it is, and exactly what to write to fix it; and every surface (human `pipelex validate` / `pipelex fix`, agent `pipelex-agent validate` / `pipelex-agent fix` in markdown and JSON, the API `/validate` payload) must present that explanation at full strength, with an actionable next step, verified hands-on against the `pipelex-demos/bad_bundles` playground.++## Where this work lives++- Branch/worktree: `feature/Autofix` in `_autofix/` (this directory). The autofix track's steps 1–5 are done (rules, loop, agent + human `fix bundle` CLIs, `💡 Suggested fix:` lines in validate); step 6 (release train) is pending — see `master-plan.md` and `step5-human-cli-surfacing.md` (this folder). This plan is a follow-on quality track born from dogfooding the playground.+- Related deferred items to fold in opportunistically: `deferred-checkpoint-e-review-items.md` (this folder — validate footer over-count; cross-CLI duplications) and the step-5 doc's explicitly-deferred "richer still-invalid markdown for the agent command".++## The test bed (built 2026-07-09, session before this plan)++`/Users/lchoquel/repos/Pipelex/pipelex-demos/bad_bundles/` — a playground of deliberately broken `.mthds` bundles, one scenario per directory, covering every autofix rule plus an unfixable-collision safety case and a kitchen-sink combo. Its `README.md` documents every scenario and the exact commands; `_pristine/` holds backups and `./restore.sh` re-breaks everything, so it can be exercised repeatedly. **This is where every before/after comparison in this plan gets verified.**++Run everything from the `pipelex-demos` repo root with its own venv (the user fixed it; it has the `fix` command):++```bash+cd /Users/lchoquel/repos/Pipelex/pipelex-demos+source .venv/bin/activate+export PIPELEX_NO_DECK_NOTICE=1+pipelex validate bundle bad_bundles/01_wrong_sequence_output/bundle.mthds+pipelex-agent validate bundle bad_bundles/01_wrong_sequence_output/bundle.mthds+pipelex fix bundle bad_bundles/01_wrong_sequence_output/bundle.mthds --diff+./bad_bundles/restore.sh+```++## Confirmed diagnosis (from the dogfooding session — reproduce on scenario 01)++Comparing `pipelex validate`, `pipelex-agent validate`, and `pipelex fix --diff` on `bad_bundles/01_wrong_sequence_output` showed the three surfaces are *consistent* (one engine, zero drift) but the explanation quality is carried almost entirely by the `💡 Suggested fix:` line — the core message is weak, and the agent surface doesn't even show that line as prose. Specifics, with pointers:++1. **Messages leak internal repr instead of author syntax.** The sequence-multiplicity raise site (`pipelex/pipe_controllers/sequence/pipe_sequence.py:114-118`) says `declares output multiplicity=None, but the last step ... has output multiplicity=True` — Python internals (`None` = single, `True` = list). An author writes `StoryIdea` vs `StoryIdea[]`. The message never shows the solution.+2. **The `(required: [...], provided: ...)` suffix is misleading on multiplicity errors.** Appended generically in `categorize_pipe_validation_with_libraries_error` (`pipelex/core/pipes/handle_pipe_errors.py:193`) by raw-repr-ing `required_concept_codes` (a Python list) and `provided_concept_code` (a string). For `INADEQUATE_OUTPUT_MULTIPLICITY` the concepts are identical by definition (the concept check passed just above), so it prints two same-looking refs — and the list-repr brackets `['story_studio.StoryIdea']` accidentally mimic MTHDS `[]` multiplicity syntax. It reads like a multiplicity statement it is not making.+3. **The correct solution string exists at the raise site and is thrown away by the message.** `expected_output_ref` is computed as exactly `"StoryIdea[]"` (`pipe_sequence.py:86-90`, via `StuffSpec.to_bundle_representation`) but flows only into the fix-planner enrichment (the `💡` line). Any surface showing only `message` (agent top line, API consumers) gets the `None`/`True` riddle.+4. **The agent markdown under-delivers on the workspace's own "format follows consumer" doctrine.** `pipelex-agent validate` markdown = a title, a *truncated* top message (drops the required/provided detail the item has), a boilerplate hint ("Check the validation_errors array for specific issues", from `pipelex/pipeline/exceptions.py:92`), then a raw JSON dump of `validation_errors`. The per-item prose rendering the human renderer got in step 5 (titled error, field lines, `💡 Suggested fix:` line, actionable footer naming the fix command) never got mirrored to the agent markdown. Doctrine reference: workspace-root `CLAUDE.md` § "Surface output conventions" and `docs/specs/pipelex-mthds-protocol.md` § "Presentation vs contract".+5. **The human footer is the model to generalize:** `💡 N of these errors can be fixed automatically — run: pipelex fix bundle <path>` — "a hint needs an action behind it". The agent surfaces have no equivalent (neither validate nor the hint text), even though the payload carries `suggested_fix` with `safety: "safe"`.++## Key code map++| Concern | Where |+| --- | --- |+| Raise sites of pipe validation errors (message wording) | `pipelex/pipe_controllers/sequence/pipe_sequence.py` (multiplicity + concept + taint); sibling controllers/operators under `pipelex/pipe_controllers/`, `pipelex/pipe_operators/` |+| Error-type enum + `is_*` properties | `pipelex/core/pipes/exceptions.py` (`PipeValidationErrorType`, `INADEQUATE_OUTPUT_MULTIPLICITY` at :108) |+| Categorizer that builds error data + appends the required/provided suffix | `pipelex/core/pipes/handle_pipe_errors.py:180-209` |+| Shared items builder (single source of truth; attaches `suggested_fix`) | `pipelex/pipeline/validation_errors.py:24` (`build_validation_error_items`) |+| Fix planner (rules, descriptions, `KNOWN_FIX_CODES`) | `pipelex/pipeline/fixes/planner.py` |+| Fix loop + result model | `pipelex/pipeline/fixes/fix_loop.py` |+| Human validate/fix rendering (items renderer, 💡 lines, footer) | `pipelex/cli/error_handlers.py` (`display_validation_error_items`, `handle_validate_bundle_error`); `pipelex/cli/commands/fix/` (`_fix_core.py`, `_diff_sandbox.py`) |+| Agent CLI output plumbing (markdown/JSON two-stream, error envelope) | `pipelex/cli/agent_cli/commands/agent_output.py` (`_render_error_markdown` at :289); `pipelex/cli/agent_cli/commands/fix/`; agent CLI conventions in `pipelex/cli/agent_cli/CLAUDE.md` |+| Agent/API fix markdown renderer (CLI-free) | `pipelex/pipeline/fixes/fix_render.py` (`format_fix_markdown`) |+| API error envelope (`ValidateBundleError.to_error_report`, boilerplate hint) | `pipelex/pipeline/exceptions.py` (hint at :92, report at ~:154) |+| Tests pinning current wordings/renderings | `tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py`, `tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py`, `tests/integration/pipelex/cli/test_fix_bundle_human.py`, `tests/integration/pipelex/pipeline/test_fix_convergence_loop.py`, e2e under `tests/e2e/pipelex/cli/` and `tests/e2e/agent_cli/` |+| Cross-repo wording corpus (regen after wording changes) | `conformance/validate-error-qa/` — the generated error-explanation QA corpus, freshness-tested against the live API (see workspace-root `CLAUDE.md`) |++## Guardrails++- **Presentation vs contract:** wordings, markdown shape, exit codes, and hints are presentation — free to improve. The structured fields (`is_valid`, `error_type`, `category`, `suggested_fix`, `validation_errors[]`) are the machine contract — additive changes only, and any addition ripples to the API report and conformance fixtures (step-6 already owes a `suggested_fix` fixture regen; coordinate, don't collide).+- **One engine, every surface:** improvements go into the message at the raise site or the shared items builder/renderers — never into per-surface private wording that can drift.+- Wording changes WILL break string-pinning tests; update the pins in the same change (that's the point of them).++## Phase 2 design notes (gathered from reading the renderers — not yet implemented)++The intended architecture for Phase 2 (agent surfaces catch up), converged after reading the code:++- **Add a shared, CLI-free markdown renderer** for validation-error items — e.g. `format_validation_errors_markdown(items, *, bundle_path, fix_command, header)` in a non-CLI module (put it beside `format_validate_markdown` in `pipelex/pipeline/validation_render.py`, or in `validation_errors.py`). It mirrors the *structure* of the human `display_validation_error_items` (`cli/error_handlers.py:266-328`) but emits markdown (`**bold**`/backticks) instead of Rich markup: group by category, per item render humanized `error_type` title + identity fields (Pipe/Concept/Domain/Field/Missing*/Variables) + the message + `💡 Suggested fix: <description>` + source, then a fix-aware footer. Reuse it for (a) agent validate markdown, (b) agent fix still-invalid markdown (`fix_render.py`), (c) API `rendered_markdown` in Phase 3.+- **Agent validate error path**: mirror the human `handle_validate_bundle_error`. Cleanest is a dedicated `agent_error_validate_bundle(exc, *, bundle_path, library_dirs, allow_signatures)` (in `agent_cli/commands/agent_output.py`) that, for **markdown**, prints the prose (title `# Bundle validation failed`, bundle path, prose items via the shared renderer, fix-aware footer naming `pipelex-agent fix bundle <path>`) and for **JSON** emits the *exact same envelope as today* (`_agent_error_json` with `is_valid`/`bundle_path`/`validation_errors`). Call it from `validate/bundle_cmd.py:194` and `validate/method_cmd.py:119` in place of the generic `agent_error(...)`. **The JSON contract must not change** — hooks pin `--format json` and branch on structured fields (`mthds-plugins/docs/mthds-agent-output-audit.md`).+- **Fix-aware footer (disease E)**: replace the boilerplate hint `"Check the validation_errors array for specific issues"` (`ValidateBundleError.user_action` at `pipeline/exceptions.py:90-93`) *for the agent markdown presentation only* — the footer names `pipelex-agent fix bundle <path>` when N items carry a `safe` suggested_fix, mirroring the human footer (`error_handlers.py:367-388`). Keep `user_action.detail` as the JSON `hint` (or improve it too — it's presentation, not contract).+- **Truncated top-line + pydantic leak (disease C)**: the agent prose body shows the *items*, not `exc.message`, so the pydantic `Value errors: '<field>': Value error,` leak won't appear in prose. To also clean the JSON `message` field, fix it at the source where `ValidateBundleError.message` is built from the pydantic `ValidationError` — `pipeline/validate_bundle.py:~142` `_translate_to_validate_bundle_error` (summarize from items: count + first clean message). `message` is presentation, safe to improve; verify no hook branches on it.+- **Fix still-invalid markdown (`fix_render.py` `format_fix_markdown`)**: render `remaining_errors` (already `ValidationErrorItem`s) as prose via the shared renderer with their 💡 lines — this is the step-5 deferred "richer still-invalid markdown".+- Tests: agent-CLI unit + e2e under `tests/e2e/agent_cli/`; keep the JSON snapshot contract byte-stable; only the markdown stream changes.++## Phases++### Phase 0 — Cold-start orientation — DONE++- [x] Read this file top to bottom; skim `wip/autofix/step5-human-cli-surfacing.md` (design decisions D5.4/D5.5 explain the human renderer) and `pipelex/cli/agent_cli/CLAUDE.md` (two-stream output conventions).+- [x] Run the playground: `./bad_bundles/restore.sh`, then all surfaces on scenario 01 (commands above) and capture the current outputs as the "before" baseline. Captured **all** scenarios × five surfaces → `wip/validation-reporting/before/` (regen: `scratchpad/capture_before.sh`).+- [x] Sweep the remaining scenarios (02–10) across the surfaces and note, per scenario, every message that fails the bar "states the problem AND the concrete author-syntax action". → **inventory** (diseases A–F, per-scenario verdict table, Phase 1 scope) — was captured in `phase0-inventory.md` (removed at archival); its findings are summarized in "Confirmed diagnosis" above and the Phase 0 status-log entry below.++### Phase 1 — Message quality at the source (the engine, so every surface benefits) — DONE++- [x] Rewrite the sequence multiplicity-mismatch message (`pipe_sequence.py:114`) in author terms using the already-computed `expected_output_ref` and a `to_bundle_representation` rendering of the declared output. Now: *"the sequence 'brainstorm' declares its output as 'StoryIdea', but its last step 'gen_ideas' yields 'StoryIdea[]'. Update the sequence's output to 'StoryIdea[]' (or change the last step)."*+- [x] Rewrite the `input_stuff_spec_mismatch` message (`pipe_abstract.py:361-373`) — the worst offender (4 lines of `Concept(...)`/`PresenceMarker` repr) → *"In pipe 'make_recipe', input 'dish' is declared as 'Number' but its step needs 'Text'. Update the input to 'Text'."* Removed the `mismatch_details` machinery.+- [x] Fix the required/provided suffix (`handle_pipe_errors.py:192`): suppress it for multiplicity errors (new enum property `is_inadequate_output_multiplicity`), and for the cases where it stays, render author-syntax refs joined without Python list-repr brackets.+- [~] Audit every other pipe/blueprint validation message for the same diseases. Done: the messy ones (A) are the two above. **Disease F (`invalid_pipe_code_syntax` "Must be in snake_case" on a dotted code) DEFERRED** — low value (the 💡 line already says "Strip the same-domain prefix"), and it would touch the well-tested categorizer/message contract (typed error categorizes structurally, but 4 test files pin the wording). Native-redecl / missing-input / concept-mismatch messages already meet the bar. Disease C (pydantic top-line leak) is Phase 2 (summarize-from-items).+- [x] Update string-pinning tests: new `tests/unit/pipelex/core/pipes/test_handle_pipe_errors_suffix.py` (suffix suppression/reformatting), strengthened `test_pipe_sequence_output_multiplicity.py` (author-syntax pin + no repr leak), strengthened `test_controller_inputs_enrichment.py` (stuff-spec message pin). `make agent-check` green; targeted suites green (core + pipe_controllers + pipes + pipeline = 2010 passed/1 pre-existing xfail; cli = 820 passed).+- [x] **CHECKPOINT 1** — re-captured all scenarios → `wip/validation-reporting/after/`. Exactly 01/02/03/08 changed (all disease-A/B); diseases A+B markers now **absent** from every after-capture; verified cascade (02: `Idea`→`Idea[]`) and multi-file (08: `Quote`→`Quote[]`) render correctly. Good handoff point.++### Phase 2 — Agent surfaces catch up to the human renderer (markdown presentation) — DONE++- [x] `pipelex-agent validate` markdown: renders `validation_errors` items as prose (humanized `error_type` title, message, per-field lines, `💡 Suggested fix:` line), not a JSON dump. New shared CLI-free renderer `format_validation_error_items_markdown(items)` in `pipeline/validation_render.py` mirrors the human `display_validation_error_items` structure; wired via new dispatcher `agent_error_validate_bundle(exc, *, bundle_path, library_dirs, allow_signatures)` in `agent_output.py`, called from `validate/bundle_cmd.py` + `method_cmd.py`. JSON stream kept byte-identical (verified: all 10 scenarios' AGENT-json capture unchanged).+- [x] Truncated/leaky top-line: the markdown prose shows the *items*, not `exc.message`, so the pydantic `Value errors: '<field>': Value error,` leak (disease C) is **gone from the markdown surface** (verified 05/06/09/10). **Deferred to Phase 3:** cleaning the JSON top-level `message` field at the source (`_translate_to_validate_bundle_error` / interpreter) — doing it CLI-only would create CLI≠API drift, so it belongs with Phase 3's "API carries improved messages" (one-engine). JSON `message` intentionally left as-is here to keep the JSON contract byte-stable.+- [x] Boilerplate hint (disease E) replaced for the **markdown** presentation with a fix-aware footer: when N items carry a suggested fix, names the exact `pipelex-agent fix bundle <path>` command (with `-L`/`--allow-signatures` echo, via shared `build_fix_command`); else "no automatic fix" pointer. JSON `hint` kept unchanged ("Check the validation_errors array…") per the contract.+- [x] `pipelex-agent fix` still-invalid markdown: new `format_fix_still_invalid_markdown(result, *, bundle_path)` in `fix_render.py` renders applied fixes + bail reason + remaining errors as prose (with 💡 lines) + context tip; wired in `fix/bundle_cmd.py` (markdown branch), JSON `FixBundleError` envelope unchanged. (The step-5-deferred "richer still-invalid markdown".)+- [x] Human `handle_validate_bundle_error` refactored to use the shared `build_fix_command` (drift reduction; output byte-identical — verified HUMAN-validate capture unchanged across all 10).+- [x] Tests: new `test_validate_bundle_error_format.py` (dispatcher: markdown prose + fix-aware footer, JSON envelope byte-stable); strengthened `test_validation_render.py` (shared items renderer + `build_fix_command`), `test_fix_render.py` (still-invalid prose + tip branches), `test_fix_format.py` (command-level markdown still-invalid). `make agent-check` green; cli+pipeline+e2e suites green (2054+ passed). Hook JSON contract untouched (see audit note below).+- [x] **CHECKPOINT 2 CLEARED** — re-captured all 10 scenarios × 5 surfaces → `wip/validation-reporting/after/`. Per-section diff vs Phase-1: **AGENT validate markdown CHANGED on all 10** (JSON dump → prose), **AGENT validate json SAME on all 10** (contract preserved), **HUMAN validate + HUMAN fix --diff SAME on all 10** (footer refactor byte-stable), **AGENT fix markdown CHANGED only on 09** (the sole still-invalid case). No `Value errors:` / `multiplicity=None` / json-fence leak in any markdown surface. Good handoff point.++### Phase 3 — JSON / API parity and the fix-report surfaces — DONE++- [x] **Carry-over from Phase 2 (disease C, JSON `message`):** cleaned the leaky top-level `message` at its **source** — a new `_summarize_bundle_validation_message(...)` in `pipeline/exceptions.py`, called from `ValidateBundleError.__init__`, replaces the raw pydantic/interpreter top-line with a clean summary derived from the per-error item messages (the lone item message when there's one categorized error; `N validation errors (first: …)` when several). Falls back to the raw message only when there is NO categorized data (a parse-level failure whose raw message is authoritative — e.g. TOML syntax; keeps the pipelex-api `"TOML" in body["message"]` pin green). One engine → **every** surface benefits (agent JSON `message`, API `InvalidReport.message`/report `detail`), not CLI-only. Verified live on the playground: the JSON `message` is now clean on all 10 scenarios (the *only* line that changed; the human/agent-md/fix surfaces are byte-identical). No hook branches on `message`.+- [x] API `/validate` parity: `to_error_report` carries the improved messages verbatim (the summary rides `report.message` → `InvalidReport.message`; a produced verdict stays a 200/`is_valid` body — no contract change). **Unified** `render_invalid_validation_markdown` (the API `rendered_markdown` invalid-arm renderer, `validation_render.py`) to reconstruct the typed items and delegate to the shared `format_validation_error_items_markdown` — so the API markdown now carries per-item `💡 Suggested fix` lines and is structurally identical to the agent/human prose (was the older dict-based `## Errors (N)` list with no fix lines). The redundant top summary line was dropped (matches the agent CLI prose surface; no CLI-command footer since an API consumer applies fixes via the structured `suggested_fix` ops). `rendered_markdown` is presentation, never the contract.+- [x] Fix reports: reviewed all `bail_reason` wordings against the message bar. The one that leaked internal repr — the no-progress bail dumping raw `_fix_fingerprint` strings (`fix_loop.py`) — now names the re-proposed fix's author-facing **description** instead (`"no progress: the same fix was re-proposed without changing the bundle (<description>); its target could not be applied as written — fix the remaining errors manually"`). The other bail reasons (out-of-scope, cross-file collision, max-iterations) already met the bar. The `--diff` preview runs the **real** loop against a sandbox copy and reuses `_render_fix_result(preview=True)`, so preview wording matching the real run is structurally guaranteed (no change needed). The still-invalid "still shows a suggested fix that was not applied" tip already meets the bar.+- [x] Additive structured fields: **decided NOT to add any.** The `suggested_fix` ops already carry the machine-actionable data (e.g. `set_key output = "StoryIdea[]"`) and the message states it in author syntax, so an `expected_output_ref` wire field would be redundant and would expand the contract (changelog + conformance regen) for no concrete consumer — against the "smallest correct surface, no speculative additions" guardrail.+- [x] **CHECKPOINT 3** — this doc updated (below). Tests updated in the same change: retargeted `test_validate_bundle_category_framing.py` (the `.message` framing pin → a clean-summary invariant across all four entry points, since the category-framing prefix was subsumed by the structured items), `test_validation_render.py` (invalid-arm prose shape + 💡 line), `test_fix_loop_bail.py` (no-progress wording). `make agent-check` green; targeted suites green (pipeline + cli + core + fixes + e2e agent_cli = 1798 passed).++### Phase 4 — Full-sweep QA and closeout — DONE (conformance regen release-gated)++- [x] Restored the playground and re-captured every scenario × every surface → `wip/validation-reporting/after/`. **The only per-scenario delta vs Phase 2 is the JSON `message` line (now clean) on all 10**; human validate, agent-md, human fix `--diff`, and agent fix are byte-identical — zero regressions. Zero leak fragments (`Value errors:` / `multiplicity=None` / `Could not load …` / json-fence) remain in any capture. Goal-bar spot-check on scenario 03 (the Phase-0 worst offender): human/agent-md/agent-json all state the problem AND the concrete author-syntax action; scenario 09's collision bail renders the remaining error as prose + the actionable bail reason + tip.+- [ ] **Regenerate `conformance/validate-error-qa/` corpus — DEFERRED, release-gated (belongs to step 6).** All 40 `invalid_*.json` + `invalid_*.md` fixtures pin the old leaky top-line `message`; the freshness guard (`conformance/tests/validate_error_qa/test_corpus_fresh.py`) asserts them byte-for-byte against the **live** `/validate`, and the conformance repo pins a *released* pipelex — so the corpus can only be regenerated (`make validate-error-qa`) once these wordings ship. Coordinate with the step-6 `suggested_fix` fixture regen already owed (guardrail: "coordinate, don't collide"). The `invalid_*.agentcli.md` channel is unaffected (it already renders items via `format_validation_error_items_markdown`, ungated).+- [x] Docs: CHANGELOG `[Unreleased]` gained the validation-error-reporting entries (author-syntax messages, agent prose rendering, clean summary message on every surface + API `rendered_markdown` 💡 lines, no-progress bail wording). The CLI docs (`docs/tools/cli/validate.md`, `fix.md`, `agent-cli.md`) describe the 💡 line / fix command / error envelope **generically and remain accurate** — no stale reprs were embedded, so no edits were needed. `pipelex-demos/bad_bundles/README.md` embeds no error-output strings (commands unchanged), so it needs no update.+- [x] `make agent-check` green. `make agent-test` (full suite — run because the change touches the shared `ValidateBundleError` base) — see status log for result. Final status update below.++## Status log++- 2026-07-09 — **Phase 4 DONE — TRACK COMPLETE (conformance regen release-gated to step 6).** Full-sweep re-capture confirms the only per-scenario delta vs Phase 2 is the now-clean JSON `message` on all 10 scenarios; every other surface byte-identical; zero leak fragments anywhere; goal bar met on every surface (spot-checked scenario 03, the Phase-0 worst offender, + scenario 09 collision bail). CHANGELOG `[Unreleased]` updated; CLI docs verified accurate as-is (no stale reprs embedded → no edits); `bad_bundles/README.md` unaffected. `make agent-check` green; **full `make agent-test` suite green**. Remaining follow-up = the release-gated `conformance/validate-error-qa/` corpus regen (all 40 `invalid_*.{json,md}` fixtures pin the old leaky top-line; regenerate via `make validate-error-qa` once these wordings ship, alongside step 6's owed `suggested_fix` fixture regen). All code changes UNCOMMITTED on `feature/Autofix`.+- 2026-07-09 — **Phase 3 DONE (CHECKPOINT 3 cleared).** Disease C fixed at the source: new `_summarize_bundle_validation_message(...)` in `pipeline/exceptions.py`, called from `ValidateBundleError.__init__`, replaces the leaky pydantic/interpreter top-line (`Validation error(s): … Value errors: '<field>': Value error, …`, plus `Pipe validation failed:` / `Could not load … because of:` prefixes) with a clean item-derived summary — one engine, so the agent JSON `message` **and** the API `InvalidReport.message` both benefit; raw message kept as the fallback only when there's no categorized data (keeps the TOML-syntax pin green). API markdown unified: `render_invalid_validation_markdown` now delegates to the shared `format_validation_error_items_markdown`, gaining per-item 💡 lines (was a dict-based `## Errors (N)` list). No-progress fix bail_reason no longer dumps internal fingerprints — names the fix description instead. Decided against adding speculative structured wire fields (`suggested_fix` ops already carry the actionable data). Tests: retargeted `test_validate_bundle_category_framing.py` (framing pin → clean-summary invariant), updated `test_validation_render.py` (prose+💡) and `test_fix_loop_bail.py` (wording). `make agent-check` green; targeted suites green (1798 passed). **Full-sweep re-capture** (`wip/validation-reporting/after/`): the ONLY per-scenario delta vs Phase 2 is the JSON `message` line on all 10 (now clean); human/agent-md/fix surfaces byte-identical; zero leak fragments remain anywhere. NEXT = **Phase 4** (conformance corpus regen is release-gated → deferred to step 6; docs + CHANGELOG; final agent-test).+- 2026-07-09 — Plan written from the dogfooding session (playground built + three-surface diagnosis on scenario 01). No implementation started.+- 2026-07-09 — **Phase 0 DONE.** Confirmed the step-5 code is present on `feature/Autofix` (came in via the `dev` merge `ec477700f`); demos venv points at this worktree, so code changes dogfood live. Captured every scenario × five surfaces to `wip/validation-reporting/before/`. Inventory in `phase0-inventory.md`: 6 diseases (A internal-repr messages, B misleading required/provided suffix, C pydantic top-line leak, D agent-md JSON-dump-not-prose, E boilerplate agent hint, F snake_case wording). Raise sites confirmed: `pipe_sequence.py:114` (multiplicity), `pipe_abstract.py:361-373` (stuff-spec-mismatch — worst), `handle_pipe_errors.py:192` (suffix). `StuffSpec.to_bundle_representation(relative_to_domain=…)` is the author-syntax renderer for Phase 1.+- 2026-07-09 — **Phase 2 DONE (CHECKPOINT 2 cleared).** Agent surfaces now render prose. New shared CLI-free renderer `format_validation_error_items_markdown(items)` + `build_fix_command(executable, *, bundle_path, library_dirs, allow_signatures)` in `pipeline/validation_render.py` (mirror the human `display_validation_error_items` / footer). New dispatcher `agent_error_validate_bundle(exc, *, bundle_path, library_dirs, allow_signatures)` in `agent_output.py` (markdown prose + fix-aware footer; JSON envelope byte-identical) wired into `validate/bundle_cmd.py` + `method_cmd.py`. New `format_fix_still_invalid_markdown(result, *, bundle_path)` in `fix_render.py` wired into `fix/bundle_cmd.py` markdown branch (JSON `FixBundleError` unchanged). Human `handle_validate_bundle_error` refactored to the shared `build_fix_command` (byte-identical). Disease D (JSON-dump→prose) + E (boilerplate hint→fix-aware footer) cured on the markdown surface; disease C cured in markdown (items shown, not `exc.message`) — **JSON `message` cleanup deferred to Phase 3** (fix at source, one-engine). Tests: +1 new module (`tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py`), strengthened `test_validation_render.py` / `test_fix_render.py` / `test_fix_format.py`. `make agent-check` green; cli+integration-pipeline+e2e suites green. Re-captured `wip/validation-reporting/after/` (regen script: `scratchpad/capture_after.sh` — runs human `pipelex` with `--no-logo`, strips banner/telemetry-DEBUG noise; demos venv points at this worktree so changes dogfood live). Per-section verification: AGENT-md CHANGED×10, AGENT-json SAME×10, HUMAN-validate/fix SAME×10, AGENT-fix-md CHANGED×1 (09 only). NEXT = **Phase 3** (JSON/API parity + the disease-C JSON-`message` carry-over at source; fix reports' `bail_reason` wording; consider additive structured fields).+- 2026-07-09 — **Phase 1 DONE (CHECKPOINT 1 cleared).** Rewrote the two repr-leaking messages (A) at their raise sites + suppressed/reformatted the misleading suffix (B) in the categorizer (new `is_inadequate_output_multiplicity` enum property). Every surface benefits (one engine) — verified the agent JSON/markdown carry the new message with zero `multiplicity=None/True` or `(required: [` leaks. Deferred disease F (snake_case wording) — low value, categorizer/test-contract risk. C stays for Phase 2. Tests: +1 new module, 2 strengthened; `make agent-check` green, targeted suites green. before/after captures in `wip/validation-reporting/`. NEXT = **Phase 2** (agent `validate`/`fix` markdown → prose items + 💡 lines + fix-aware footer; fix the pydantic top-line leak C + boilerplate hint E). Code map: `agent_output.py` `_render_error_markdown` (~:289), `pipeline/exceptions.py:92` (hint), `fix_render.py` (still-invalid md).