Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

docs(changelog): move Highlights to a top section under the version header

Louis Choquel580a8a0ebbba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 116224621..41c128878 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,20 +2,23 @@
## [v0.34.0] - 2026-06-17
-### Added
+### Highlights
-- **Highlight — Structured validation errors**: validation failures now return a typed, per-error `validation_errors[]` on the error wire instead of a bare `detail` string, with the same shape across the HTTP API and the agent CLI.
+- **Structured validation errors** — validation failures now return a typed, per-error `validation_errors[]` on the error wire instead of a bare `detail` string, with the same shape across the HTTP API and the agent CLI.
- **Structured `validation_errors` on the error wire**: `ErrorReport` gains a typed `validation_errors: list[ValidationErrorItem] | None` field. `ValidateBundleError.to_error_report()` flattens its per-error data onto it via a single shared builder (`pipelex/pipeline/validation_errors.py`), so the structured error report an HTTP API surfaces carries machine-mappable per-error diagnostics — `category`, `message`, identity fields, and a `source` (declaring file) for cross-file mapping — instead of only a `detail` string. The closed `ValidationErrorCategory` set is `blueprint_validation` / `pipe_factory` / `pipe_validation` / `dry_run`; a **residual dry-run failure** (`DryRunError` / `PipeRunError`, no structured locator) is projected as one `dry_run` item **only when no categorized error has data**, so an invalid verdict always carries a non-empty `validation_errors[]` (the structured-info invariant) rather than a bare message. The same builder feeds the agent CLI's `validation_errors` JSON array, so the CLI and API structured shapes cannot drift. The list is surfaced under STRICT disclosure (`_STRICT_KEPT_FIELDS`) because it describes the caller's own submitted bundle, not server internals.
- **Changed — agent CLI `validation_errors` shape**: the `validate` commands' error envelope now omits null-valued keys per entry (`exclude_none`) and gains the previously-dropped `source`, `field_name`, and `concept_code` fields. Entries are guaranteed to carry `category` and `message`; all other keys are present only when populated, so consumers must treat them as optional rather than assume a fixed key set.
- **Per-content `source` on the in-memory validate path**: `PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_source=...)` and `validate_bundle(mthds_sources=...)` let a caller attach a logical source to each in-memory bundle string, threaded into `blueprint.source`. A sourceless `mthds_contents` submission previously produced `source=None`, breaking cross-file diagnostics; a host (e.g. an HTTP API) can now pass per-item sources so the structured `validation_errors` carry a real owning file. The on-disk CLI path is unchanged (it already records real file paths).
- **`dry_run` validation category**: `ValidationErrorCategory` gains a `dry_run` value. A dry-run residual failure that previously produced a bare-message `ValidateBundleError` with an empty `validation_errors[]` now surfaces one structured `dry_run` item carrying the message (graph-level, so typically no `source`) — closing the structured-info gap that drove consumers to fabricate a category.
-- **`is_valid` on the canonical validation report**: `PipelexValidationReport` gains `is_valid: Literal[True] = True`, the always-true discriminant of the valid arm of the hosted `/validate` response union (mirrored by pipelex-api's `InvalidReport`'s `Literal[False]`). It sits beside `is_runnable`: a sound bundle may still be not-yet-runnable.
-- **Highlight — Keyword-only argument enforcement**: a mechanical guard enforces the keyword-only argument convention across `pipelex/`, end to end — local autofix through the CI gate.
+- **Keyword-only argument enforcement** — a mechanical guard enforces the keyword-only argument convention across `pipelex/`, end to end — local autofix through the CI gate.
- **Keyword-only AST guard**: A custom AST-based linter (`pipelex-dev check-keyword-only` / `make cko`) that mechanically enforces the keyword-only argument convention across `pipelex/`, wired into `make check` and `make agent-check`.
- **Keyword-only auto-fix**: A non-gating `--fix` mode (`pipelex-dev check-keyword-only --fix` / `make fix-keyword-only` / `make fko`) that rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible (after `self`/`cls`), re-parsing each rewrite before writing and reporting the shapes it can't fix mechanically. It runs early in `make agent-check`; the read-only check still runs last and owns the pass/fail gate.
- **Claude Code hook**: A `PostToolUse` bash hook (`.claude/hooks/check-keyword-only.sh`) that runs the guard on edited files for immediate blocking feedback to AI agents.
- **CI integration**: A dedicated `lint-keyword-only` job in the GitHub Actions linting workflow to block non-compliant signatures from merging.
- **Convention documentation**: New `docs/contribute/keyword-only-arguments.md`, plus updates to `CLAUDE.md` and `AGENTS.md` establishing the keyword-only convention as a standing rule.
+
+### Added
+
+- **`is_valid` on the canonical validation report**: `PipelexValidationReport` gains `is_valid: Literal[True] = True`, the always-true discriminant of the valid arm of the hosted `/validate` response union (mirrored by pipelex-api's `InvalidReport`'s `Literal[False]`). It sits beside `is_runnable`: a sound bundle may still be not-yet-runnable.
- **Offline CLI unit tests**: Coverage for the pipelex-internal logic behind the CLI commands — `doctor` diagnostics, `run` execution and its sync wrapper, the `build` codegen cores, the readiness gate, `show`/`which`, and the gateway/telemetry/signature error handlers (the spec'd CLI interface stays owned by the conformance suite).
- **Offline inference & runtime unit tests**: Coverage for layers that can break without a provider — structured-output↔instructor mode mapping, model-deck reference checks, the image-gen argument and worker-routing factories, gateway request-shaping and extract parsing, the Mistral factory, the local observer sink, the output renderer, builder spec validation / `to_blueprint()`, the pipeline runner's error paths, the TOML config-sync engine, and the storage config validators.
- **Offline Temporal entry-point unit tests**: Coverage for operational surfaces that previously only failed inside a live cluster — the worker CLI, the codec HTTP server (encode/decode, CORS, error→status mapping), and the server connection logic (API-key resolution, TLS, codec selection).