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: document the Unreleased input-semantics surfaces (#1150)
Louis Choquel875decef9140
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2d4c2615e..f3a104abf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,11 +14,11 @@### Changed-- **`pipe_io_contracts` learns presence and real multiplicity (breaking protocol reshape).** Input contracts now carry `presence` (`plain` / `optional` / `force`) — the declared marker verbatim — replacing the two-valued `optional`, so lint and graph surfaces can see where `!` assertions live without a presentation view. Input and output contracts both carry a three-valued `multiplicity` (`single` / `variable` / `fixed`) with `item_count: int` present exactly when `fixed`, retiring the old ruling that deliberately reported a fixed count as `variable` (the input contract previously had no multiplicity field at all). The output contract keeps its two-valued `optional` (`!` is rejected on outputs). Spec-first: the MTHDS Protocol spec's `pipe_io_contracts` row and optionals section moved in the same change, and the reshaped conformance assertions are gated until the release cascade.+- **`pipe_io_contracts` learns presence and real multiplicity (breaking protocol reshape).** Input contracts now carry `presence` (`plain` / `optional` / `force`) — the declared marker verbatim — replacing the two-valued `optional`, so lint and graph surfaces can see where `!` assertions live without a presentation view. Input and output contracts both carry a three-valued `multiplicity` (`single` / `variable` / `fixed`) with `item_count: int` present exactly when `fixed`, retiring the old ruling that deliberately reported a fixed count as `variable` (the input contract previously had no multiplicity field at all). The output contract keeps its two-valued `optional` (`!` is rejected on outputs). Spec-first: the MTHDS Protocol spec's `pipe_io_contracts` row and optionals section moved in the same change, and the reshaped conformance assertions are gated until the release cascade. Documented in `docs/under-the-hood/pipe-io-contracts.md` (the per-pipe contracts a valid report carries) and `docs/building-methods/pipes/understanding-multiplicity.md`.- **A structure field can no longer declare both `required = true` and a `default_value` (breaking).** The two are contradictory instructions — a default's meaning is "applied when the caller omits the field", which makes absence legal — and the generator used to resolve the conflict silently by dropping the required-ness through parameter ordering. The pair is now rejected at blueprint validation — and at the builder's spec layer, so an authoring agent fails before emitting TOML the parser would reject — with a message naming both remedies, and the generator branch that tiebroke it is an explicit invariant that raises if ever reached. Relatedly, a pydantic default on a hand-written structure class now counts as an authored fact: the input-form descriptor reports such a field as `required: false` with its `default_value`, instead of claiming it required and hiding the default.-- **Unknown keys in a structure-field table are now rejected (breaking).** A typo'd or hopeful key on a concept structure field (`minimum`, `unit`, a misspelled `hint`) used to be silently dropped at parse while the bundle validated green — silently discarded authored intent. `ConceptStructureBlueprint` now forbids unknown keys, making the field table's keys strict exactly like an input slot table's; hint *content* stays lenient (unknown hint keys still warn and are preserved). The MTHDS JSON Schema regenerates accordingly (structure-field objects carry `additionalProperties: false`), and hint-free crates keep byte-identical fingerprints.+- **Unknown keys in a structure-field table are now rejected (breaking).** A typo'd or hopeful key on a concept structure field (`minimum`, `unit`, a misspelled `hint`) used to be silently dropped at parse while the bundle validated green — silently discarded authored intent. `ConceptStructureBlueprint` now forbids unknown keys, making the field table's keys strict exactly like an input slot table's; hint *content* stays lenient (unknown hint keys still warn and are preserved). The MTHDS JSON Schema regenerates accordingly (structure-field objects carry `additionalProperties: false`), and hint-free crates keep byte-identical fingerprints. Documented in `docs/building-methods/concepts/inline-structures.md`, which now states the closed key set and points a constraint at a Python class, where pydantic `Field(...)` metadata is read as an authored fact.- **Ruff moves to 0.16.4, matching the version the VS Code extension bundles.** The extension now syncs `pyproject.toml` and `ruff.toml` documents to the language server, because Ruff from 0.16 on lints its own config files. A binary older than that parses those documents as Python source and paints phantom `invalid-syntax` diagnostics across every `pyproject.toml` — `requires-python = ...` read as `requires - python`. Pinning the dev dependency to the exact version the extension ships keeps the editor and the command line on one binary, so a rule can never fire in one and not the other. This is a dev-dependency change: nothing shipped changes, and there is no version bump.diff --git a/docs/building-methods/concepts/inline-structures.md b/docs/building-methods/concepts/inline-structures.mdindex dda032ecc..228a28467 100644--- a/docs/building-methods/concepts/inline-structures.md+++ b/docs/building-methods/concepts/inline-structures.md@@ -61,9 +61,17 @@ Each field can specify:- **choices**: For `enum`-like fields, a list of valid values- **item_type**: For `list` fields, the type of list items- **key_type** and **value_type**: For `dict` fields, the types of keys and values+- **concept_ref** and **item_concept_ref**: For `concept` fields (and `list` fields whose items are concepts), the concept being referenced+- **hints**: Non-normative presentation intent for this field — see [Intent Hints](intent-hints.md)Field names must be valid Python identifiers and cannot be Python keywords; generated Python projections use them as model attributes.+!!! warning "The key set is closed"++ The keys above are the only ones a structure field accepts, and anything else is rejected at validation. A typo (`descrption`), a hopeful constraint the language does not carry (`minimum = 0`, `unit = "kg"`), or a misspelled `hints` all fail the bundle instead of being dropped.++ This is deliberate: a silently discarded key is authored intent that vanishes without a trace, and you only find out when the value it was supposed to govern comes back wrong. If you need a numeric bound or another constraint, express it on a Python class instead — see [Python Classes](python-classes.md), whose pydantic `Field(...)` metadata is read as an authored fact. Note that hint *content* stays lenient: an unknown key inside a `hints` table warns and is preserved, rather than failing the bundle.+## Supported Field TypesInline structures support these field types:diff --git a/docs/building-methods/concepts/intent-hints.md b/docs/building-methods/concepts/intent-hints.mdindex 632218721..7ed345398 100644--- a/docs/building-methods/concepts/intent-hints.md+++ b/docs/building-methods/concepts/intent-hints.md@@ -48,7 +48,7 @@ A slot table with no `hints` is the same slot as the plain string: `x = { concepThe *shape* of a `hints` table is enforced: it must be a flat string-to-string table, and the expanded slot form admits only `concept` and `hints` — anything else (a non-table `hints`, a number value, a nested table, an unknown slot-table key like `description`) is a structural validation error.-The *content* is lenient: an unknown hint key or an unknown `intent` word parses, is preserved through the crate and onto the descriptor, and is only **warned** about. Validation emits advisory warnings (never errors) for three findings, each naming its site: an unknown hint key (`hint_unknown_key`), an unknown `intent` word (`hint_unknown_intent`), and a known word on a site it does not apply to (`hint_inapplicable_intent`) — for example `rating` on a text field. This is what lets the vocabulary grow between standard versions without breaking older validators.+The *content* is lenient: an unknown hint key or an unknown `intent` word parses, is preserved through the crate and onto the descriptor, and is only **warned** about. Validation emits advisory warnings (never errors) on the report's `warnings` array for three findings, each naming its site: an unknown hint key (`hint_unknown_key`), an unknown `intent` word (`hint_unknown_intent`), and a known word on a site it does not apply to (`hint_inapplicable_intent`) — for example `rating` on a text field. This is what lets the vocabulary grow between standard versions without breaking older validators.## Precedence and inheritance@@ -73,3 +73,10 @@ hints = { intent = "prose" } # overrides the inherited labelHints ride the library crate (a concept's effective hints are assembled during normalization; field and slot hints travel as authored) and land on the [input-form descriptor](../../under-the-hood/input-form-descriptor.md): every node's `hints` slot carries its final effective merge, and an applicable `intent` word feeds the node's `kind` — `prose` and `label` select between the `prose` and `text` kinds on text-valued nodes; `rating` and `quantity` ride the slot for the renderer without changing `kind`. On a plural site (a `Concept[]` slot, a list field), applicability is judged per item, and the merged hints appear on both the `list` node and its `item`.Because hints are non-normative, the runtime never reads them: execution, validation verdicts, and pipe contracts are identical with and without them — and a method that authors no hints keeps its crate fingerprint, byte for byte.++## Related Documentation++- [Refining Concepts](refining-concepts.md) - How hints inherit along a refinement chain+- [Inline Structures](inline-structures.md) - Attaching hints to a structure field+- [Designing Pipelines](../pipes/index.md#understanding-the-pipe-contract) - The expanded input slot form+- [Input-Form Descriptor](../../under-the-hood/input-form-descriptor.md) - Where effective hints surface for a rendererdiff --git a/docs/building-methods/concepts/python-classes.md b/docs/building-methods/concepts/python-classes.mdindex b2f73199a..ff188b7d8 100644--- a/docs/building-methods/concepts/python-classes.md+++ b/docs/building-methods/concepts/python-classes.md@@ -227,6 +227,17 @@ Product = "A product in the catalog"**4. Test your pipeline** - The behavior should be identical, plus your custom validation.+### Constraints and defaults are authored facts++A hand-written class is also the only place to express a constraint. An inline structure field accepts a closed set of keys, so an authored `minimum = 0` or `max_length = 8` is rejected rather than silently dropped — on a class, the same intent goes on the pydantic field, where Pipelex reads it:++```python+price: float = Field(ge=0, description="Product price")+sku: str = Field(max_length=8, pattern=r"^[A-Z]+$", description="Stock keeping unit")+```++That metadata is not merely enforced at runtime — it is carried onto the [input-form descriptor](../../under-the-hood/input-form-descriptor.md), so a form renderer sees the bound. A pydantic default counts the same way: `in_stock: bool = Field(default=True, ...)` is reported as a field that is *not* required, carrying `True` as its default. Requiring a field and giving it a default are contradictory in both worlds — inline, the pair is rejected outright; on a class, a field with a default is simply not required.+## Recommendations### The Recommended Workflow@@ -245,6 +256,7 @@ Product = "A product in the catalog"| Type hints in Python | `pipelex build structures` || IDE autocomplete | `pipelex build structures` || Custom validation | Hand-written Python class |+| Field constraints (`gt`, `max_length`, `pattern`) | Hand-written Python class || Computed properties | Hand-written Python class || Business methods | Hand-written Python class |diff --git a/docs/building-methods/concepts/refining-concepts.md b/docs/building-methods/concepts/refining-concepts.mdindex cab2115d4..aee5bd766 100644--- a/docs/building-methods/concepts/refining-concepts.md+++ b/docs/building-methods/concepts/refining-concepts.md@@ -408,5 +408,6 @@ refines = "Customer"- [Native Concepts](native-concepts.md) - Complete guide to native concepts- [Inline Structures](inline-structures.md) - Add structure to concepts- [Python StructuredContent Classes](python-classes.md) - Advanced customization+- [Intent Hints](intent-hints.md) - Non-normative presentation intent, inherited along the refinement chain- [Packages](../packages.md) - Package system, dependencies, and cross-package referencesdiff --git a/docs/building-methods/pipes/index.md b/docs/building-methods/pipes/index.mdindex 66df41e94..5260d883f 100644--- a/docs/building-methods/pipes/index.md+++ b/docs/building-methods/pipes/index.md@@ -86,6 +86,14 @@ Every pipe defines a **contract** through its `inputs` and `output` fields. This* **`inputs`**: This dictionary defines the **mandatory and necessary** data that must be present in the [Working Memory](working-memory.md) before the pipe can execute. Each key in the dictionary becomes a variable name that you can reference in your pipe's logic (e.g., in prompts), and each value specifies the concept type that the data must conform to. If any required input is missing or doesn't match the expected concept, the pipeline will fail a clear error message.You can specify multiple inputs by using a list of concepts. For example, `inputs = { description = "ProductDescription", keywords = "Keyword[]" }` will require a `ProductDescription` and a list of `Keyword`s. (See more about [Understanding Multiplicity](./understanding-multiplicity.md) for details.)+ Each input slot can be written in two equivalent ways. The **plain form** gives the concept as a string — `topic = "Text"` — and is what you want almost always. The **expanded form** gives a table instead, so the slot can carry [intent hints](../concepts/intent-hints.md) beside its concept:++ ```toml+ inputs = { topic = { concept = "Text", hints = { intent = "prose" } } }+ ```++ The `concept` key takes exactly the grammar the plain string does, presence markers and multiplicity included (`"Note?"`, `"Keyword[]"`). The table is closed — `concept` and `hints` are the only keys it accepts, and anything else is a validation error. A slot table with no hints is the same slot as the plain string: `x = { concept = "Text" }` and `x = "Text"` parse to identical blueprints, so reach for the expanded form only when you have hints to attach.+* **`output`**: This field declares what the pipe will produce. The output will always be an instance of the specified concept. The structure and type of the output depend on the concept definition (See more about concepts [here](../concepts/native-concepts.md)).* You can specify **multiple outputs** using bracket notation (e.g., `Keyword[]` for a variable list, or `Image[3]` for exactly 3 images)diff --git a/docs/building-methods/pipes/understanding-multiplicity.md b/docs/building-methods/pipes/understanding-multiplicity.mdindex 8b09038ce..dd6831cc6 100644--- a/docs/building-methods/pipes/understanding-multiplicity.md+++ b/docs/building-methods/pipes/understanding-multiplicity.md@@ -425,3 +425,12 @@ Multiplicity in Pipelex gives you precise control over how many items flow throuBy understanding and using multiplicity effectively, you can build pipelines that handle both single items and collections with clarity and type safety.+## How Multiplicity Crosses the Wire++A validate report tells a consumer exactly what you declared. On both the input and the output side of [`pipe_io_contracts`](../../under-the-hood/pipe-io-contracts.md), `multiplicity` is three-valued — `single`, `variable`, or `fixed` — and a `fixed` slot carries its exact count in `item_count`. Input entries additionally carry a JSON Schema, where a fixed count is stamped as `minItems`/`maxItems` on the array wrap and a variable list carries no bounds; the output entry reports the concept and the count without a schema. `Concept[1]` is reported as `single`, with no list framing, exactly as it behaves at run time.++## Related Documentation++- [Understanding Optionality](understanding-optionality.md) — the other axis of a slot's shape+- [Intent Hints](../concepts/intent-hints.md) — how a hint on a plural slot applies per item+diff --git a/docs/building-methods/pipes/understanding-optionality.md b/docs/building-methods/pipes/understanding-optionality.mdindex fddde15ee..275403733 100644--- a/docs/building-methods/pipes/understanding-optionality.md+++ b/docs/building-methods/pipes/understanding-optionality.md@@ -25,6 +25,8 @@ Two grammar rules keep the model coherent:Concept definitions, `refines`, and structure-field references never carry markers — presence is a property of a pipe's contract, not of a concept.+Markers work the same way in the [expanded slot form](index.md#understanding-the-pipe-contract): the `concept` key takes the identical grammar, so `notes = { concept = "Note?", hints = { intent = "prose" } }` is an optional input carrying a hint.+## The Runtime Trichotomy: Skip, Run, or FailAt run time, a value slot resolves to a value **or a recorded absence** — never a silent hole. When a pipe is about to run and one of its inputs is absent, the marker decides what happens:@@ -118,3 +120,4 @@ Two more optionality facts surface on the **valid** report (`pipelex validate`,- [PipeParallel](pipe-controllers/PipeParallel.md) — combining under absence- [PipeBatch](pipe-controllers/PipeBatch.md) — compaction of absent branch results- [Execution Graph Tracing](../../under-the-hood/execution-graph-tracing.md) — skipped nodes, `skip_reason`, and optional data edges+- [Per-Pipe IO Contracts](../../under-the-hood/pipe-io-contracts.md) — how the marker is reported on `pipe_io_contracts` as the three-valued `presence`diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex a5ba9e3e6..70b1c7582 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -78,7 +78,7 @@ For `bundle`, additional options are available:On a successful run, the envelope also carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), each namespaced by `pipe_ref` (`domain.code`). In JSON it is a `pending_signatures` array, in markdown a "Pending signatures" section. A top-down build reads it to see exactly which headers remain to implement. The envelope also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown states the runnability verdict in plain English — runnable when complete, NOT yet runnable above the "Pending signatures" section otherwise. `validate bundle`, `validate method`, and `validate pipe --all` carry them and gate on them: without `--allow-signatures`, the command exits non-zero when `is_runnable` is false. Bare `validate pipe <code>` omits them, and a `--pipe` slice surfaces them for information without gating.!!! note "Advisory warnings on validate"- Whole-bundle and whole-library validate surfaces (`validate bundle`, `validate method`, `validate pipe --all`) 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).+ Whole-bundle and whole-library validate surfaces (`validate bundle`, `validate method`, `validate pipe --all`) 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. The [intent-hint](../../building-methods/concepts/intent-hints.md) lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`) ride the same `warnings` shape on the protocol validation report; they are not wired into this CLI's array. 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).### Fixdiff --git a/docs/under-the-hood/pipe-io-contracts.md b/docs/under-the-hood/pipe-io-contracts.mdnew file mode 100644index 000000000..ec8d282a1--- /dev/null+++ b/docs/under-the-hood/pipe-io-contracts.md@@ -0,0 +1,49 @@+# Per-Pipe IO Contracts++Every valid `validate` report carries a **`pipe_io_contracts`** map: for each pipe, the typed contract of what it takes in and what it produces. It sits beside the [input-form descriptor](input-form-descriptor.md) on the same report, and the two are keyed identically — by the namespaced `pipe_ref` (`domain.code`) — over exactly the same set of pipes, `PipeSignature` placeholders and controller-inferred inputs included.++Reach for `pipe_io_contracts` when you need the schema and the declared contract; reach for `input_form` when you are building a form and want field kinds, defaults, and choices without reading schemas.++## Where it lives++- `pipelex/pipeline/pipe_io_contracts.py` — the wire models (`PipeInputContract`, `PipeOutputContract`, `IOMultiplicity`) and the one public derivation, `build_pipe_io_contracts(pipes)`.+- `PipelexValidationReport.pipe_io_contracts` (`pipelex/pipeline/validation_report.py`) — where the artifact travels.+- `pipelex/pipeline/validate_in_process.py` — the in-process assembly derives it inside the validation library's window, right beside `build_input_form`. Iterating the same loaded pipes is what makes the two key sets equal by construction.++## What an entry carries++Each pipe gets an `inputs` map and one `output`.++An **input entry** carries the `concept_ref`, the JSON Schema of its content (`json_schema`), and two facts about the slot as declared:++- `presence` — the authored marker, verbatim: `plain`, `optional` (`?`, the caller may omit it and the pipe handles absence itself), or `force` (`!`, must be provided, and the author asserted so). `plain` and `force` are both required; the distinction is the assertion, which lint and graph surfaces read.+- `multiplicity` — `single`, `variable` (`Concept[]`, unbounded), or `fixed` (`Concept[N]`), with `item_count` carrying the exact N on the `fixed` arm and `null` otherwise. `Concept[1]` is `single`: no list framing.++An **output entry** carries `concept_ref`, the same `multiplicity` / `item_count` pair, and a two-valued `optional` — `!` is rejected on outputs, so there is nothing three-valued to report. It carries **no `json_schema`**: the schema render runs per input only. A consumer that wants the output's payload shape gets it from [`build output --format schema`](../tools/cli/build/output.md), not from this contract.++## Where the concept identity sits on the schema++The JSON Schema on an input names its concept: `title` is the `concept_ref`, `description` the concept's authored description. On a `single` slot those sit at the top level; on `variable` and `fixed` slots the schema is an array wrap that keeps them on `items`, and a fixed count adds `minItems`/`maxItems` on the wrap itself. A variable list carries no bounds.++```json+{+ "type": "array",+ "items": { "type": "object", "title": "my_domain.Gadget", "description": "…", "properties": { "…": "…" } },+ "minItems": 2,+ "maxItems": 2+}+```++## Which surfaces carry it++The protocol `validate` operation carries `pipe_io_contracts` on its report. The [Agent CLI](../tools/cli/agent-cli.md#validate) does not: `pipelex-agent validate` emits the verdict, `pending_signatures`, `is_runnable`, and its own advisory `warnings` array, and stops there — the typed contracts are not part of its envelope.++## Seeing it++`pipelex-dev trace-input-semantics` captures the contracts as `hop5_pipe_io_contracts.json` beside `hop5_input_form.json`, so an authored fact can be checked on both projections at once — see [Tracing Input Semantics](../contribute/trace-input-semantics.md). The emitted shapes are pinned by `tests/integration/pipelex/pipeline/test_pipe_io_contracts.py`.++## Related Documentation++- [Input-Form Descriptor](input-form-descriptor.md) — the renderer-facing view of the same inputs+- [Understanding Optionality](../building-methods/pipes/understanding-optionality.md) — the markers behind `presence`+- [Understanding Multiplicity](../building-methods/pipes/understanding-multiplicity.md) — the bracket notation behind `multiplicity`diff --git a/mkdocs.yml b/mkdocs.ymlindex 52879c64b..6fc0b2ac5 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -319,6 +319,7 @@ plugins:- under-the-hood/build-time-elaboration.md: "Build-time Elaboration"- under-the-hood/codegen-projections.md: "Codegen Projections"- under-the-hood/input-form-descriptor.md: "Input-Form Descriptor"+ - under-the-hood/pipe-io-contracts.md: "Per-Pipe IO Contracts"- under-the-hood/dry-run-mock-generation.md: "Dry Run Mock Generation"- under-the-hood/execution-graph-tracing.md: "Execution Graph Tracing"- under-the-hood/tokens-usage-wire-records.md: "TokensUsage Wire Records"@@ -470,6 +471,7 @@ nav:- Python classes: building-methods/concepts/python-classes.md- Native Concepts: building-methods/concepts/native-concepts.md- Refining Concepts: building-methods/concepts/refining-concepts.md+ - Intent Hints: building-methods/concepts/intent-hints.md- Design and Run Methods:- Overview: building-methods/pipes/index.md- Libraries: building-methods/libraries.md@@ -567,6 +569,7 @@ nav:- Build-time Elaboration: under-the-hood/build-time-elaboration.md- Codegen Projections: under-the-hood/codegen-projections.md- Input-Form Descriptor: under-the-hood/input-form-descriptor.md+ - Per-Pipe IO Contracts: under-the-hood/pipe-io-contracts.md- Dry Run Mock Generation: under-the-hood/dry-run-mock-generation.md- Execution Graph Tracing: under-the-hood/execution-graph-tracing.md- TokensUsage Wire Records: under-the-hood/tokens-usage-wire-records.mddiff --git a/wip/input-semantics/deferred-report-artifacts-on-cli-channels.md b/wip/input-semantics/deferred-report-artifacts-on-cli-channels.mdnew file mode 100644index 000000000..82951397e--- /dev/null+++ b/wip/input-semantics/deferred-report-artifacts-on-cli-channels.md@@ -0,0 +1,25 @@+# Deferred: report-only artifacts are absent from the CLI validate channels++Surfaced by the PR #1150 review triage (three bots independently flagged the same two claims on `docs/tools/cli/agent-cli.md`). The documentation was corrected in that PR — the claims now name the protocol validation report, which is the artifact that actually carries them. What follows is the runtime work those corrections make visible. Neither item is a defect; each needs a decision rather than a patch.++## 1. Hint lints reach only the protocol report++Already tracked at [`wip/engine-hints/deferred.md`](../engine-hints/deferred.md), first bullet — read that entry first; this is an addendum, not a duplicate.++What the review established beyond it: the wiring really is mechanically available at every site. `build_current_library_hint_warnings()` needs only a current library with a crate, and all three agent-CLI sites sit inside an open, current validation window — `acquire_library` leaves the library current, and `validate_bundle` deliberately leaves its validation library open and current on success. So the appends themselves are one-liners.++The prerequisite recorded in the engine-hints note still stands and should gate the work: authored hint content is interpolated raw and unbounded into `ValidationErrorItem.message`, one item per unknown key, so a hostile or merely sloppy bundle can inflate the warning payload. Cap the per-site findings and elide long tokens **before** the lint reaches a channel an author invokes casually. The same note's design preference also stands — build one shared "all advisory warnings" composition point rather than an eighth copy of the `build_optionality_warnings(...)` pattern.++Blast radius, for whoever picks this up: the bare human CLI (`pipelex/cli/commands/validate/_validate_core.py`), the agent CLI (`pipelex/cli/agent_cli/commands/validate/_validate_core.py`, three sites) and the builder ops (`pipelex/builder/operations/validate_ops.py`, three sites) are all equally hint-blind.++## 2. `pipe_io_contracts` / `input_form` on the agent CLI envelope — needs a design decision++**Do not wire this without deciding the shape first.** The mechanics are trivial and that is exactly the trap.++`build_pipe_io_contracts` and `build_input_form` both take a `Sequence[PipeAbstract]`, and every agent-CLI validate site already has the pipes in hand inside its open window. Appending both to the success envelope would take minutes.++The reason not to: it would put a full JSON Schema per input, per pipe, into **every** `validate` success envelope on a CLI whose whole point is cheap machine-readable output. The protocol report puts these behind an explicit opt-in for precisely that reason — `PipelexValidationReport.input_form`'s own docstring says the HTTP route decides whether the field travels on the wire, absent unless a caller opts in via `views`, and [`docs/under-the-hood/input-form-descriptor.md`](../../docs/under-the-hood/input-form-descriptor.md) repeats it.++So the open question is not "should the CLI expose the contracts" but "what is the CLI's equivalent of `views`". Candidates: a `--views` / `--include` flag mirroring the protocol parameter, or a separate `pipelex-agent contracts` command that returns them without pretending they are part of a validation verdict. Deciding that is what unblocks the work.++Until then, `docs/under-the-hood/pipe-io-contracts.md` states the boundary explicitly in its "Which surfaces carry it" section, so a reader is told which surface to reach for rather than discovering the absence.