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.

feat: vacuous presence lint, and one composition point for advisory warnings (#1152)

Louis Choquel8e2ad695c909
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 807da5865..d010e2e6d 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:a2001ebaf33421c58b9d42c0a02cd3b6871a9da01bac3a64849bac79e729761c"
+digest = "sha256:c3043b7ae643783145bc6b481ead8e5c866c80017fff0d339e6aaa052f148b8b"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-21T09:18:57Z"
-rationale = "Trigger fired on a lint-comment migration only. The ruff 0.16 upgrade rewrote '# noqa: CODE' suppressions across pipelex/cli/** into the new '# ruff: ignore[rule-name]' spelling, and removed the per-line '# noqa: PLC2701' halves that a tests/** per-file-ignore now covers; filtering the diff over pipelex/cli/** for any changed line that is not a noqa, ruff-ignore or pyright-ignore comment returns nothing. No command was added, removed or renamed, no option or argument changed, no output format or exit code moved, and the agent-CLI report contract is untouched. docs/tools/cli/**, the agent-CLI contract doc and the doctor/migrate pages therefore need no edit."
+reviewed_at = "2026-08-25T09:27:54Z"
+rationale = "The bare CLI's validate bundle now echoes its advisory warnings before the strict pending-signature gate rather than after it, matching validate --all. Reviewed both targets: docs/tools/cli/validate.md said the warnings print beside the success message, which is no longer where they appear and hid the case that motivated the change, so its Advisory Warnings section now states the ordering and that a bundle with an unimplemented placeholder still shows them while exiting non-zero. The agent-CLI contract doc needed no ordering change (its envelope is JSON) but its composition-point sentence was overstating the channel scope and now says advisory-bearing, naming the surfaces that carry none. No command, option, argument or exit code moved."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -47,7 +47,7 @@ rationale = "Trigger fired on a lint-comment migration only. The ruff 0.16 upgra
"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad"
"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:cd1dd07661fc5ce60971ed0d2c7579cba6da7861"
+"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:6e9e8488573fe17d7769608e299879a092ceaf6c"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3207973c194b096ed5c6ec2d3a955c417789e019"
"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:985226bdaf005a41f8c9fa7559485b67cb1b3d19"
@@ -120,7 +120,7 @@ rationale = "Trigger fired on a lint-comment migration only. The ruff 0.16 upgra
"pipelex/cli/commands/show_cmd.py" = "blob:7974d91404ea93f05b16b05b9aef3c1a540b965d"
"pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca"
"pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/validate/_validate_core.py" = "blob:ac7133943c4d217d6afa4d84742d2d5551d9b9bc"
+"pipelex/cli/commands/validate/_validate_core.py" = "blob:3294c9c716ac616a89213c7356d38a8eff62da40"
"pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab"
"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"
"pipelex/cli/commands/validate/method_cmd.py" = "blob:2cb68d5c371a5b45841fce9c26da5e4622e6b042"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ccbf52ff..d86f348ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,21 @@
# Changelog
+## [Unreleased]
+
+### Added
+
+- **The vacuous-presence lint (`input_presence_vacuous`)**: A method input declared without `?` says the caller must supply it, but when the concept behind it declares no required field the empty object already satisfies the declaration — nothing is actually demanded, and a form, an API client or a person filling it in has no way to tell what to put there. Validation now names that on the report's advisory `warnings` array, so the bundle stays valid and the verdict never moves. The message states both remedies: mark the input optional if the method can run without it, or give the concept a required field. It is scoped to **entry pipes** — the bundle's declared `main_pipe`, where a method meets its caller — because on an inner pipe the slot is fed by dataflow and an all-optional structure is a legitimate producer shape. The lint reads the input-form descriptor, so class-backed concepts whose pydantic fields all carry defaults are judged exactly as authored all-optional structures are. See [Understanding optionality](building-methods/pipes/understanding-optionality.md) and [Inline structures](building-methods/concepts/inline-structures.md).
+
+### Changed
+
+- **Every whole-bundle validate channel now carries the same advisory warnings**: The `warnings` array used to be assembled site by site, and the sites disagreed — the protocol validation report carried the optionality and intent-hint lints, while the agent CLI, the builder operations and the bare CLI each carried the optionality lint alone, so which advisories an author saw depended on which command they typed. One composition point now builds all three families in one fixed order and every whole-bundle channel calls it — the protocol report, the agent CLI, the builder's per-bundle operations, and the bare CLI's `validate bundle` and `validate --all` — which brings the intent-hint lints to the CLI and builder surfaces for the first time. Two surfaces stay out and say so: single-pipe `validate <PIPE_CODE>`, which makes no bundle-wide claim, and the builder's `validate_all`, which carries no `warnings` key at all. Riding along is the bound those lints needed before reaching a channel invoked casually: a site naming many undefined hint keys reports the first few and then how many more there were, and a long authored key or value is elided in the message rather than interpolated whole. Breaking: `LibraryManagerAbstract` gained an abstract `get_accumulated_blueprints`, which the collector reads to find the entry pipes, so an alternative manager injected through `Pipelex.setup(library_manager=...)` implements it or fails loudly at construction — the same rule the report's shared assembly follows, and for the same reason: a silent `[]` would report zero entry pipes and look clean.
+
+### Fixed
+
+- **An empty `[concept.X.structure]` table is no longer described as prose**: The input-form deriver decided a concept was structured by testing its merged structure table for *truthiness*, while the engine's own `ConceptFactory` branches on `structure is not None`. A concept authoring an empty structure table — legal MTHDS, backed at run time by a field-less structured model whose schema is `{"type": "object", "properties": {}}` — therefore fell through to the prose branch, and the descriptor claimed `kind: "prose"` with a `refines` link to `native.Text` that nobody authored, contradicting the schema sitting beside it. The deriver now makes the engine's distinction, so such a slot is an `object` with an empty `fields` list; a concept refining an empty-structure base is decided by the dict one link up the chain. This also makes the vacuous-presence lint's field-less wording reachable from a real bundle rather than only from a hand-built descriptor.
+- **The bare CLI's `validate bundle` no longer swallows its advisory warnings behind the signature gate**: The strict pending-signature gate raised `typer.Exit(1)` before the advisory echo ran, so a bundle holding any unimplemented `PipeSignature` placeholder printed none of its warnings — and a half-implemented method is exactly the state an author is in while building. The echo now runs before the gate, the same ordering `validate --all` has always used and states in its own comment.
+- **A field-less structure class is described as an empty object, not as `unknown`**: `reflect_structure_class` answers `None` for two different situations — a registered class declaring no field, and a field whose annotation it could not map — and the input-form deriver treated both as opaque, reporting `kind: "unknown"`. Zero fields is a faithful reading of that class rather than a failure to read it, so a class-backed concept whose class declares nothing is now an `object` with an empty `fields` list, exactly like the authored empty structure table it mirrors; a genuinely unmappable annotation still reports `unknown`. The shared reflection helper keeps its `None`, because its other consumer — the native consistency probe — reads that as "structureless by design".
+
## [v0.52.0] - 2026-08-24
### Highlights
diff --git a/TODOS.md b/TODOS.md
index 2554ab1e7..948a88c19 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,107 +1,98 @@
-# S2 — Enrich: implementation tracker
-
-Seeded from [`wip/enrich/design.md`](wip/enrich/design.md) §7 (the design stays authoritative for rationale; this file tracks live progress). Milestone branch: `feature/Enrich`.
-
-## Decisions ratified (Phase 0, 2026-08-23, by Louis)
-
-1. **E3 — reject the pair.** A structure field declaring both `required = true` and a `default_value` is a validation error (breaking; mthds spec sentence via inbox; the sole fixture instance moves to `rejected/`).
-2. **E5/E9 — replace, not add.** Input contract `presence: "plain" | "optional" | "force"` **replaces** `optional`; `multiplicity` goes three-valued (`single`/`variable`/`fixed`) with `item_count` exactly when `fixed`, on input and output contracts. Output keeps its two-valued `optional`. Breaking protocol change, spec-first, rides the release cascade.
-3. **Reflected defaults are authored facts.** A pydantic default on a reflected class field reports `required: false` + its `default_value` in the descriptor; `field_info.is_required()` is the single source of truth.
-
-## Phase 0 — ratify and sweep
-
-- [x] Decisions §6 confirmed by Louis (see above)
-- [x] Sweep at head: hopeful extra keys in structure-field tables across fixtures, corpus entries, and cookbook-adjacent test data (E7 fallout list)
-- [x] Sweep at head: `required = true` + `default_value` pairs across the same surfaces (E3 fallout list)
-- [x] Inventory captures that pin emitted schema bytes (codegen/validate parity corpora, conformance captures, characterization tests) so Phase 2 re-baselines are deliberate
-- [x] Record the fixture-fallout list for Phases 1–2 below
-
-### Phase 0 findings
-
-- **Structure-field sweep (2026-08-23, at head of `feature/Enrich`):** parsed every `.mthds`/concept-bearing `.toml` under this worktree, `pipelex-cookbook`, and `pipelex-starter-python`. The ONLY unknown-key carrier is the probe bundle's `constrained_count` (`tests/data/input_semantics/probe_bundle.mthds:61` — extras `minimum`, `maximum`, `examples`, `unit`), and the ONLY `required`+`default_value` pair is the probe bundle's `titled_default` (`probe_bundle.mthds:30`). No fallout anywhere else; both fields are handled by the design's own plan (extras: E7 flip keeps them as deliberate rejected-case material; `titled_default` moves to a `rejected/` fixture in Phase 4).
-- **Schema-byte capture inventory (very thorough sweep):** NOTHING under `tests/` pins schema bytes — every schema assertion is key-presence or single-value, so Phase 2's render changes are test-green without re-baselining (no snapshot framework exists in the repo). The only committed full-schema payloads are the S1 audit captures under `wip/input-semantics/probe/` (hop3 raw schemas, hop4 renders, hop5 contracts), re-baselined by one command: `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`. Hand edits Phase 2 owes: `docs/tools/cli/build/output.md:161-239` (its example `--format schema` output shows the class-name `title`, no top-level `description`, and a `MyType[5]` array with no `minItems`/`maxItems` — falsified by all three enrichments). Digest surfaces checked (migration fingerprints, crate fingerprints, codegen stamps): none hashes rendered schema. Conformance (sibling repo) pins nothing schema-byte-wise; it becomes relevant only at Phase 3. Natural home for new seam unit tests: `tests/unit/pipelex/core/concepts/test_concept_representation_generator.py`; for integration assertions: `tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py`.
-
-## Phase 1 — loudness (E7, E8)
-
-- [x] E7: `extra="forbid"` on `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`) — field-table *keys* strict; hint *content* stays lenient (unknown hint keys still warn + preserve)
-- [x] E8: builder writes `default_value`, not `default` (`pipelex/builder/operations/concept_ops.py`)
-- [x] E8: write-then-validate round-trip test for builder-authored defaults (`tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py` — two existing assertions had pinned the buggy `default` key and were fixed too)
-- [x] Regenerate `mthds_schema.json` — `ConceptStructureBlueprint` now carries `additionalProperties: false` (schema is generated + gitignored; downstream copies sync at release per the filed inbox item)
-- [x] Apply Phase 0 fixture fallout: probe bundle's `constrained_count` lost its hopeful extras (its description string kept byte-identical — it is hashed by the fingerprint pins); the extras live on in the new `tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid`
-- [x] Unit tests: forbid rejection + hint leniency (`tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py`)
-- [x] H2 fingerprint invariant check: `test_fingerprint_pins.py` green with UNCHANGED pins
-- [x] Changelog (Unreleased): E7 breaking (Changed) + E8 fix (Fixed)
-- [x] Deliver + remove inbox item `../wip/inbox/2026-08-21-pipelex-builder-default-key-dropped.md` (deleted; fix, round trip, and forbid all delivered)
-
-**Checkpoint 1** — authoring loop honest, nothing wire-visible changed yet.
-
-- [x] Checkpoint 1: tracker updated, `make agent-check` green, targeted tests green (concepts + builder + fingerprint pins + input-form integration)
-
-### Checkpoint 1 state (for cold start)
-
-Decisions all ratified (§ above). Phase 1 delivered E7+E8 entirely inside: `concept_structure_blueprint.py` (forbid), `concept_ops.py` (key fix), probe bundle + new rejected fixture, three test modules touched. Note for Phase 4: removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `tests/unit/pipelex/libraries/test_fingerprint_pins.py` — that is a legitimate fixture-content change, not a model leak; the pins must be recomputed then, against the test docstring's usual advice, or the pin test moved onto a stable fixture. The check-mthds PostToolUse hook flags the probe bundle with a stale bundled schema — `plxt lint` with the regenerated `derived/mthds_schema.json` is the authority and passes.
-
-## Phase 2 — schema enrichment (E6, E1-title, E4)
-
-- [x] E6: `_render_schema_representation` (`pipelex/core/concepts/concept.py`) injects the concept's authored description as top-level `description` (no-op for generated classes; authored fact for class-backed; pinned native blueprint description for native direct inputs)
-- [x] E6: docstrings on native content classes lacking one (`TextContent`, `ImageContent`, `DocumentContent`, `PageContent`, `NumberContent`, `HtmlContent`, `YesNoContent`) — pinned description text verbatim; the pinned-consistency test (`tests/unit/pipelex/codegen/test_native_expansion.py`) compares factory descriptions, not docstrings, so no interference
-- [x] E1: top-level `title` becomes the concept ref at the same render seam (nested identity stays descriptor-only; no `$defs` renames)
-- [x] E4: `render_concept_representation` takes real multiplicity (not a boolean) — threaded through `render_stuff_spec`; new helpers `is_multiple_multiplicity` / `fixed_item_count` in `variable_multiplicity.py`; `StuffSpec.is_multiple()` delegates; `runner_code.py` local `_is_multiple` deleted in favor of the shared helper
-- [x] E4: array wrap emits `minItems`/`maxItems` = N when fixed; variable `[]` gets neither bound; `[1]` stays single (no wrap, no bounds)
-- [x] E4: contract memo key normalized to `(concept_ref, is_multiple, fixed_count)` (avoids the `hash(True) == hash(1)` collision between `Concept[]` and `Concept[1]`)
-- [x] Guard: `DocumentContent.url` field-description wording untouched (class gained only a docstring)
-- [x] Probe bundle + trace harness: no extension needed — the existing fixtures already exercise class-backed (`probe_refined.classbacked`), native-direct (`probe_native_inputs`), and fixed-count (`probe_markers.two = Gadget[2]`) inputs; all three enrichments verified present in the regenerated captures
-- [x] Re-baseline the Phase 0-inventoried schema-byte captures: `wip/input-semantics/probe/` regenerated; `docs/tools/cli/build/output.md` schema examples hand-updated (concept-ref title, top-level description, `minItems`/`maxItems`)
-- [x] Unit tests at the render seams: four new tests in `TestSchemaRepresentationWithMultiple` (title/description injection, array identity on items, fixed-count bounds, `[1]` stays single) + `tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py` for the two helpers
-- [x] Changelog (Unreleased): additive schema enrichments
-
-**Checkpoint 2** — the "zero client changes" half complete and measurable.
-
-- [x] Checkpoint 2: tracker updated, checks green
-
-### Checkpoint 2 state (for cold start)
-
-Phase 2 delivered entirely inside: `concept.py` (render seam: multiplicity param + title/description injection + array bounds), `variable_multiplicity.py` (two new helpers), `stuff_spec.py` (delegation + pass-through), `runner_code.py` (shared helper), `pipe_io_contracts.py` (normalized memo key), seven native content classes (docstrings), plus tests, probe re-baseline, and the docs example. Signature change is breaking for direct callers of `render_concept_representation` (`is_multiple` → `multiplicity`) — all in-repo callers and tests updated. Phase 3 recon (from the paused-note, still valid): `PresenceMarker` in `variable_multiplicity.py` is exactly the contract's `presence` vocabulary; contract models to replace are `pipe_io_contracts.py` (`IOMultiplicity`, `PipeInputContract`, `PipeOutputContract`). Note for Phase 4 (unchanged): removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `test_fingerprint_pins.py` — recompute the pins then.
-
-## Phase 3 — contract reshaping (E5, E9) — protocol change, spec-first
-
-- [x] Spec: `../docs/specs/pipelex-mthds-protocol.md` — `pipe_io_contracts` row, "Optional IO contracts and liftable pipes" section, Verified-by line, and the abridged `ValidReport` example all updated to `presence` / three-valued `multiplicity` + `item_count`
-- [x] Spec: one sentence documenting `json_schema` as pydantic-canonical, single-choice enums as `const` (E10's documentation half) — appended to the `pipe_io_contracts` row
-- [x] Conformance: assertions reshaped in `conformance/tests/pipelex_api/test_validate_optionals.py` — the gate is shape-detected (`presence` absent → skip), so it arms automatically when `pipelex-api` re-pins at the cascade; the fixed-count arm stays pinned in pipelex's own suite (the shared optionals fixture has no `[N]` slot, deliberately not extended)
-- [x] `make check-spec-links` in `conformance/` — green (note: `make agent-check` there also surfaced PRE-EXISTING vendored-corpus drift on `vocabulary.toml` from H2, covered by the filed release-time sync inbox item — not this branch's to fix)
-- [x] Engine: `PipeInputContract.presence` replaces `optional` (reuses `PresenceMarker` — same wire values as the descriptor); input + output gain three-valued `IOMultiplicity` (+`FIXED`) and `item_count` via the new `make_io_multiplicity` projection; output `optional` unchanged
-- [x] Emission threads real multiplicity (retired `IOMultiplicity`'s fixed-reports-as-variable ruling)
-- [x] Tests on the contract fields: `tests/integration/pipelex/pipeline/test_pipe_io_contracts.py` reshaped + new `make_two` fixed-count pipe pinning `fixed`/`item_count=2` on input and output plus the bounded array schema
-- [x] Changelog (Unreleased): breaking protocol reshape
-- [x] Probe hop5 capture re-baselined (same regen command); verified `opt/many/two/forced` report exactly (`optional`,`single`) / (`plain`,`variable`) / (`plain`,`fixed`,2) / (`force`,`single`)
-
-**Checkpoint 3** — the protocol change contained in one reviewable unit.
-
-- [x] Checkpoint 3: tracker updated, checks green (`make check` exit 0; the full suite surfaced ONE stale assertion — `test_trace_input_semantics_cmd.py` still pinned the pre-reshape `inputs.hint.optional` — fixed to `presence`/`multiplicity`; full-suite green rides Phase 4's final gate)
-
-## Phase 4 — semantics and close (E3, reflected defaults)
-
-- [x] E3: model validator on `ConceptStructureBlueprint` rejecting `required = true` + `default_value` (message names both remedies) + unit seam `test_concept_structure_blueprint_required_default.py`
-- [x] E3: generator's accidental branch replaced by an explicit raising invariant (`ConceptStructureGeneratorError`) + unit seam `test_structure_generator_required_default_invariant.py`
-- [x] E3: probe bundle's `titled_default` moved to `rejected/required_with_default.mthds_invalid`; pair-sweep fallout applied (builder fixture `test_data.py` had authored the pair — `age` keeps `required`, drops the default); `test_input_form.py` now pins `motto` (`required: false` beside its default); fingerprint pins legitimately recomputed (fixture-content change, recorded in the pin module's docstring)
-- [x] Reflected defaults: `_with_reflected_constraints` reads `field_info.is_required()` + `field_info.default` (a `None` default is the optionality artifact, never reported); kind-table row via the new `retries` field on `InputFormConstrainedPayload`
-- [x] Descriptor spec touch-up: the "may carry both" sentence retired (`default_value` row now states the rejection), the "Facts over emission accidents" bullet notes the founding case resolved, the Verified-by line follows; the D2 conformance skeleton's fixture + assertions moved with it (`required = true` dropped from its `title` field) — `make check-spec-links` green
-- [x] Survival table updated with before/after closure rows (E3, E4, E5, E6/E1, E7, E9) against regenerated `wip/input-semantics/probe/` captures (`titled_default` gone from all hops)
-- [x] Findings addendum §F: per-entry closure evidence table
-- [x] Roadmap Track S closure bullet: in-engine close now, hosted-wire half at the cascade
-- [x] Changelog (Unreleased): E3 breaking + reflected-defaults ruling (Changed)
-- [x] Cross-repo inbox filings (§8): `2026-08-23-mthds-structure-field-validation-sentences.md`, `2026-08-23-pipelex-js-mirror-schema-enrichments-and-contract-reshape.md`, `2026-08-23-mthds-js-protocol-types-contract-reshape.md`
-- [x] In-repo docs swept: `inline-structures.md` gains the `required` bullet + the pair rule; `under-the-hood/input-form-descriptor.md` constraint paragraph updated (E7 made the "parser drops unknown constraint keys" claim false) + reflected-defaults sentence
-- [x] Final: `make agent-check` + full `make agent-test` green (suite exit 0)
-
-## PR #1149 review loop
-
-- [x] PR created (`feature/Enrich` → `dev`), CI fully green on first push
-- [x] Bot reviews (Greptile + codex): both converged on ONE finding — `item_count: null` for non-fixed multiplicity "violates the contract". REJECTED after verification: the protocol spec, its wire example, and `conformance/tests/pipelex_api/test_validate_optionals.py` all pin `item_count: null` off the fixed arm for `pipe_io_contracts` (the omit-when-absent convention belongs to the input-form descriptor; the two artifacts deliberately differ). Replied with evidence, resolved both threads; the misleading docstring wording disambiguated
-- [x] gstack `/review @TODOS.md` (fresh context): verdict SHIP, no P1. Clear wins applied: spec-layer E3 validator on `ConceptStructureSpec` (same two-remedies message; an authoring agent no longer validates green then dies on its own TOML) + spec-level test; stale `default_value` docstring in `input_form.py` fixed; inline duplicate of `fixed_item_count` in `derive_slot` replaced by the helper; parser-level tests wiring both new `rejected/` fixtures (`test_parser_rejected_structure_fields.py`); `force` presence pinned on the wire contract (`brief = "Text!"`); `Text[1]`→single contract projection + memo-key collision pinned (`make_from_one`); reflected `default_factory` (no fabricated default) and falsy default (`False` survives the None guard) pinned; wire-level `item_count`-always-present pinned in the trace test; changelog extended with the spec-layer half
-- [x] Deferred (review findings short of clear wins): `wip/enrich/deferred.md` — non-serializable reflected default, `_peel_multiplicity` `[1]`-as-list divergence (pre-existing), `_with_reflected_constraints` naming, double multiplicity normalization, mostly-inert `rejected/` corpus audit. Skipped outright: 0/negative-count helper rows (unreachable from bundles)
-- [x] Cross-repo: `../wip/inbox/2026-08-23-mthds-form-contract-reshape.md` filed — `mthds-form` still gates the Run button on the retired input `optional` and lacks the `fixed` multiplicity arm; no reshape item covered it
-
-## Out of scope (per design §9)
-
-Language ceiling (S1 §B) syntax, app-side fixes (M1), corpus widening, `const`→`enum` render rewrite, descriptor wire-model round-trip alias (D4).
+# Vacuous presence lint — implementation tracker
+
+**Design:** [`wip/full-optional/design.md`](wip/full-optional/design.md) — read it first; this tracker assumes its decisions (entry-pipe scope, descriptor substrate, one composition point, the `input_presence_vacuous` wire name, the hint-lint cap riding along) and does not restate the rationale. Its §9 holds the three decisions, ratified as designed.
+
+## Live state — rewrite this block, never append to it
+
+Record only what the tools cannot re-derive: the SHA a step landed in, a decision and its reason, the exact error a gate printed. Never branch, PR or working-tree status.
+
+- **All phases are closed.** The lint, its composition point, every advisory-bearing channel, the docs and the changelog landed on `feature/Full-optional`; `wip/full-optional/design.md`'s status line names the SHAs. What outlives this tracker is the follow-up: design §8's cross-repo items and the entries in `wip/full-optional/deferred.md`.
+- **What the `validate all` test found (step 2.1's open question):** `_blueprints` IS populated on the `acquire_library` path, so the accessor works and no fallback was needed. `LibraryManager.get_accumulated_blueprints` returns them, `collect_current_library_entry_pipe_refs()` qualifies each bundle's `main_pipe`, and `test_agent_cli_validate_all_warns_on_the_main_pipe` proves it end to end. The transported-crate path (a direct `load_from_crate`, used by the Temporal workflow) accumulates none, which yields the same silence as a batch with no `main_pipe` — stated in the accessor's docstring.
+- **Decisions taken since the design:** §9's three ratified as designed. Beyond them: (a) `build_input_form` gained an optional `qualified_crate` param and `qualify_current_library_crate()` was extracted beside it, so the crate is qualified ONCE per validate instead of twice — the design called this opportunistic and it fell out cleanly, closing that engine-hints deferral; (b) `build_current_library_hint_warnings()` was DELETED rather than kept, since the composition point supersedes it and nothing else called it; (c) the builder's `validate_all` is the one channel left out, recorded with its structural cause in `wip/full-optional/deferred.md`.
+- **Two bugs this lint exposed rather than introduced**, both fixed here under the flag-and-fix rule: `_blueprint_node_for_chain` decided a concept was structured by testing the merged structure table for truthiness while `ConceptFactory` branches on `is not None` (`24520d69f`), and both advisory lints truncated a dotted domain at its first `.` when building the warning locator (`51e0f9d9f`).
+- **Gates:** `make agent-check` and the full `make agent-test` were run green on every pushed SHA of this branch. No local storage override was in place, so the boot tests ran normally throughout.
+- **Decision on the §8 inbox items:** they were written into the workspace-root `wip/inbox/` (`2026-08-25-workspace-input-presence-vacuous-spec-and-conformance.md`, `2026-08-25-pipelex-js-input-presence-vacuous-enum-member.md`, `2026-08-25-pipelex-starter-js-point-shape-to-avoid-at-the-lint.md`) with the frontmatter and `repo/path` evidence the queue contract asks for, and deliberately NOT committed there — that repo carried a large set of staged deletions from an earlier triage that is not this session's to sweep up, and a commit would have dragged them in.
+
+## Standing rules
+
+- **Branch:** `feature/Full-optional` off `dev` — it already carried the design commit when implementation started, so the plan's `feature/Full-optional-lint` was never cut. The PR targets `dev`. The prefix vocabulary is closed and spelled out (`feature/`, never `feat/`).
+- **Tests before code** (red → green) for every rule in the design's decision table; mutation-test a green test by breaking the predicate it guards and watching it go red.
+- **Gates before any push:** `make agent-check` and the full `make agent-test` (never `make test`). If the local `.pipelex/pipelex_override.toml` storage override is still in place, the boot tests it reds are pre-existing — move it aside for the full run.
+- **Docs in the same change**, changelog under `## [Unreleased]` only, no counts, no mention of `wip/` docs in the changelog.
+- **Cross-repo work goes to `../wip/inbox/`** (design §8) at close — never widen this diff into another repo.
+- **Update this tracker as work happens:** tick a box the moment its step is done, append a dated line to the progress log after every commit, gate run, decision and surprise, and rewrite the live-state block the moment it stops being true.
+
+## Phase 1 — the lint itself
+
+Pure, unit-tested, not yet wired anywhere.
+
+- [x] 1.1 Add `PipeValidationErrorType.INPUT_PRESENCE_VACUOUS = "input_presence_vacuous"` with its advisory-only comment beside `OPTIONAL_FORCE_REDUNDANT`; extend the enum's exhaustive `match` properties (`is_controller_input_drift`, `is_inadequate_output`) so pyright stays green; confirm `tests/unit/pipelex/errors/test_validation_error_types.py` picks the member up unchanged.
+- [x] 1.2 Write the unit decision table first, red: `tests/unit/pipelex/pipeline/test_vacuous_presence_warnings.py` over hand-built `PipeInputFormDescriptor`s — one case per row of design §3 (all-optional object warns; one required field is silent; field-less object warns with the variant wording; `?` is silent; variable list silent; fixed-count list silent; every scalar/file kind silent; `unknown` silent), plus: a non-entry pipe with the warning shape is silent, `!` warns and names the marker, output order is by entry pipe ref then authored slot order, and the item shape (category `pipe_validation`, bare `pipe_code`, `domain_code`, `variable_names`, no `concept_code`).
+- [x] 1.3 Implement `pipelex/pipeline/vacuous_presence_warnings.py`: `build_vacuous_presence_warnings(*, input_form, entry_pipe_refs) -> list[ValidationErrorItem]`, the two message variants of design §D7, module docstring stating the rule and the one-level depth.
+- [x] 1.4 Green; mutation-test at least the `gating` read (flip to `required`: the variable-list case must go red) and the `required` scan (drop the empty-fields branch: the field-less case must go red).
+
+## Phase 2 — composition point, entry pipes, every channel
+
+- [x] 2.1 Add the accumulated-blueprints accessor to `LibraryManagerAbstract` / `LibraryManager` (design §D2). Write the `validate all` test first: a library dir holding a bundle with a `main_pipe` whose gating input is all-optional must produce the warning on the `validate all` envelope — this is the test that proves `_blueprints` is populated on the `acquire_library` path; if it is not, record what you found in the live-state block and decide between populating it and deriving entry refs another way before going on.
+- [x] 2.2 Add `pipelex/pipeline/advisory_warnings.py` (design §D6): `build_advisory_warnings(*, taint_analyses, input_form, entry_pipe_refs, qualified_crate)` pure, and `collect_advisory_warnings(*, pipes, entry_pipe_refs)` gathering the ingredients inside the window (taint walk, descriptor, the current library's crate qualified once). A helper that qualifies every bundle's `main_pipe` with `PipeFactory.make_pipe_ref_with_domain` — the spelling `select_primary_blueprint` uses — lives beside it or in `blueprint_selection.py`.
+- [x] 2.3 Hint-lint prerequisite (design §D6): in `hint_warnings.py`, elide interpolated authored tokens beyond a fixed length and cap findings per site with an "and N more" tail; unit-test both in `test_hint_warnings.py`. Extend the existing cap-free tests only where the cap changes their expectation.
+- [x] 2.4 Switch every site to the composition point: `validate_in_process.py` (pure builder, with the `input_form` and taint analyses it already computes and the entry refs from `result.blueprints`); every site in `cli/agent_cli/commands/validate/_validate_core.py` and in `builder/operations/validate_ops.py`; the bare CLI's `_echo_optionality_warnings` becomes `_echo_advisory_warnings`. Remove the direct `build_optionality_warnings` imports at those sites; fix the docstrings in `validation_report.py` and `base_exceptions.py` that name it as the warnings source.
+- [x] 2.5 Integration tests, protocol path (`tests/integration/pipelex/pipeline/test_protocol_validate.py` or a sibling module): entry pipe with a plain all-optional input warns and the report stays valid and runnable; the same input shape on a non-main pipe of the same bundle is silent; a class-backed concept whose pydantic fields all carry defaults warns; a batch with no `main_pipe` is silent; `?` on the same slot is silent; the hint lint still rides beside it.
+- [x] 2.6 Agent-CLI envelope test for `validate bundle` (the warning rides `warnings`, `is_valid` stays true, exit code unchanged) and the markdown rendering shows it under "Warnings"; builder `validate_bundle_content` twin.
+- [x] 2.7 Verify the three presentation surfaces the engine-hints deferral asked to check now that hint lints reach them: agent-CLI JSON and markdown, bare-CLI yellow echo, builder-ops JSON — one fixture with all three families firing at once, asserting family order and item shape.
+
+**CHECKPOINT 1 — after Phase 2.** ✅ Reached. The live-state block above records what the `validate all` test found, the three deviations from the design, and where the gate results live.
+
+## Phase 3 — vocabulary, docs, changelog
+
+- [x] 3.1 `generate_corpus_vocabulary_cmd.py`: add the advisory exclusion for `input_presence_vacuous` (same reason as `optional_force_redundant`); run `make generate-corpus-vocabulary`; confirm the corpus exhaustivity and linter-exclusion gates stay green.
+- [x] 3.2 `docs/building-methods/pipes/understanding-optionality.md`: the `warnings` bullet becomes a short list of the advisory lints (useless `!`, vacuous presence, the intent-hint trio), each with its wire name and one sentence.
+- [x] 3.3 `docs/building-methods/concepts/inline-structures.md`: a note that `required` defaults to `false` in the long form, that the shorthand string field is required, and that an all-optional structure named by a gating method input triggers `input_presence_vacuous` — with the two remedies.
+- [x] 3.4 `docs/under-the-hood/input-form-descriptor.md` § "Required, presence and gating": state that the lint is defined on `gating` and why.
+- [x] 3.5 `docs/tools/cli/agent-cli.md` advisory note: list the three families; delete the sentence saying the hint lints are not wired into the CLI array; keep the single-pipe exclusion.
+- [x] 3.6 `docs/under-the-hood/error-model.md` and `docs/contribute/mthds-test-corpus.md`: the advisory-only registry members are now several; reword the "one has no shape" passages accordingly.
+- [x] 3.7 `CHANGELOG.md` `[Unreleased]`: one **Added** entry for the lint (bold label, a few sentences: what fires, where, the two remedies, entry-pipe scope) and one **Changed** entry for the composition point (every whole-bundle validate channel now carries the same advisory families, the hint lints included, with the message cap). No counts.
+- [x] 3.8 If `docs/specs/` links or a drift contract fire on any touched file, resolve through `make drift-plan` / `make drift-ack` with an honest rationale.
+
+## Phase 4 — gates, PR, follow-ups
+
+- [x] 4.1 `make agent-check` green.
+- [x] 4.2 Full `make agent-test` green (override moved aside if needed); record the run in the progress log.
+- [x] 4.3 Commit and open the PR against `dev`; wait for Greptile and Codex by SHA (`gh pr view --json reviews,comments`), triage with `/review-pr-agents`, reply and resolve threads in the same pass.
+- [x] 4.4 File the inbox items of design §8: `workspace` (protocol spec section + conformance rows and tests), `pipelex-js` (`categorize.ts` member), `pipelex-starter-js` (docs pointer). Each with `repo/path:line` evidence.
+- [x] 4.5 Add a dated status line to `wip/full-optional/design.md` naming the merge SHA, and rewrite the live-state block here for the last time. Do not delete or archive this tracker — that is a separate decision after review.
+
+**CHECKPOINT 2 — after Phase 4.** The work is done when the PR is merged and the inbox items are filed; the release that carries the lint is what unblocks the conformance and corpus-consumer halves, and that version goes in the live-state block when it is cut.
+
+## Progress log
+
+- 2026-08-25 — Design written to `wip/full-optional/design.md` from the inbox request; the three amendments (entry-pipe scope, descriptor substrate, one composition point) recorded as decisions to ratify. No code yet.
+- 2026-08-25 — Phase 1 done. The enum member landed with its advisory comment and all five exhaustive `match` properties extended (the tracker named two; there are five). `build_vacuous_presence_warnings` is pure over `PipeInputFormDescriptor`s and never touches the crate.
+- 2026-08-25 — **Surprise, and a correction to step 1.4's stated expectation.** Flipping the `gating` read to `required` did NOT redden the variable-list case: a `Concept[]` slot is a `list` node, so the `kind != OBJECT` check excludes it before `gating` is ever consulted — and on an object node the deriver computes `gating = required and not (is_list and no item_count)`, which for a non-list kind is exactly `required`. The two reads are therefore indistinguishable on every descriptor the deriver builds today. Added `test_a_non_gating_object_slot_is_silent_even_when_required`, a hand-built object slot with `required=True, gating=False`, which is the only shape that can tell the reads apart; the mutation now reddens it. The `required`-scan mutation (refusing the empty-`fields` case) reddens the field-less test as the tracker predicted.
+- 2026-08-25 — Phase 2 done, CHECKPOINT 1 reached. `advisory_warnings.py` composes the three families in one fixed order (optionality, presence vacuity, hints); `collect_entry_pipe_refs` lives in `blueprint_selection.py` beside the one-main-pipe rule it deliberately differs from. Every warning-assembling site switched — `validate_in_process`, the agent CLI's, the builder's, and the bare CLI's echo (now `_echo_advisory_warnings`). The hint lint gained its payload bounds (`MAX_HINT_FINDINGS_PER_SITE`, `MAX_AUTHORED_TOKEN_LENGTH`), which was D6's stated prerequisite for letting it reach a channel an author invokes casually.
+- 2026-08-25 — **Scope call.** The builder's `validate_all` was left without a `warnings` key. It never had one, and it cannot grow one at the call site: it delegates to `acquire_and_validate`, which tears its library down before returning, so there is no open window left to collect in. Fixing it means reshaping a method several callers share — outside a lint's blast radius. Written up with its remedy in `wip/full-optional/deferred.md`; the same conclusion was already reached in `wip/pr-1026-review-notes.md`.
+- 2026-08-25 — Phase 3 done. Corpus vocabulary regenerated with the advisory exclusion (one added `[error.input_presence_vacuous]` block, nothing reshuffled). Docs updated across the six targets, plus two fixes to things the change made visible: the bare CLI's `docs/tools/cli/validate.md` had never documented its yellow advisory echo at all, and `docs/under-the-hood/error-model.md` plus the `validation_error_types` module docstring still said the registry was a union of THREE enums — stale since `HintLintErrorType` landed.
+- 2026-08-25 — Two gate surprises, both resolved. (1) `make agent-check` ran `fix-keyword-only`, which keyword-only'd `elide_authored_token`'s subject as CLAUDE.md warns it will; taken as-is and the three call sites made keyword, rather than recording a grant. (2) The full `make agent-test` reddened `test_runner_validate_plumbing.py` — it mocks the window-dependent artifact builders by name at the `validate_in_process` namespace so the body runs with no real library, and the new `qualify_current_library_crate` / `build_advisory_warnings` were not in that list. Worth knowing: the OLD hint-lint wrapper was lenient about a missing current library and the new helper is strict, which is what turned an unmocked name into a raise.
+- 2026-08-25 — Both gates green on the full tree: `make agent-check` clean, `make agent-test` all passed.
+- 2026-08-25 — PR #1152 opened against `dev`; all CI checks green. Round one of review triage: Codex raised two P2s, verified empirically by a read-only subagent before either was acted on.
+- 2026-08-25 — **A pre-existing descriptor bug the lint made visible, fixed in `24520d69f`.** Codex was right that the field-less message variant was unreachable, and the cause was worse than reported: `_blueprint_node_for_chain` decided a concept was structured by testing the merged structure table for *truthiness*, while the engine's own `ConceptFactory` branches on `structure is not None`. An authored-but-empty `[concept.X.structure]` — legal MTHDS, backed at run time by a field-less structured model with an empty object schema — therefore fell through to the prose branch, and the descriptor claimed `kind: "prose"` with a `refines` link to `native.Text` nobody authored, contradicting the schema beside it. `_merged_structure` now answers `None` versus `{}`. Both new tests were mutation-checked by restoring the truthiness test and watching them redden.
+- 2026-08-25 — **Codex's second finding declined.** Adding an abstract `get_accumulated_blueprints` does break any external `LibraryManagerAbstract` implementation, but none exists in or outside this repo, `docs/specs/pipelex-transport-boundary.md` forbids consumers reaching library-manager internals, and the suggested `return []` default would silently report zero entry pipes rather than fail loudly. Recorded as breaking in the changelog instead, matching how `build_validation_report`'s required-argument change was handled.
+- 2026-08-25 — Round two: cubic raised ten threads. Seven were acted on in `51e0f9d9f`, two declined with reasons on the thread, one taken half-way. The one that mattered: **a domain is a dotted path** (`is_domain_code_valid` accepts `legal.contracts`), so `pipe_ref.partition(".")` was truncating the warning locator's `domain_code`. Both advisory lints now split through `QualifiedRef.parse` — the optionality lint carried the same bug before this branch and was fixed alongside, per the repo's flag-and-fix-existing-bugs rule.
+- 2026-08-25 — **The 'every channel agrees' claim was overstated and is now narrowed rather than widened.** Two surfaces carry no advisories: the builder's `validate_all` (structural, already deferred) and the bare CLI's single-pipe `validate <PIPE_CODE>`, which makes no bundle-wide claim and which neither lint has anything to say about. The changelog, the CLI reference, the optionality guide and the channel test's docstring now all say so. Declined: dropping the hint-lint assertions from the agent-CLI test (that contract change is the point of this PR) and genericizing the design's §8 cross-repo paths (a follow-up item has to name repo/path to be actionable).
+- 2026-08-25 — A real test leak cubic caught: two channels the advisory test calls directly (`validate_bundle` and `do_validate_all_libraries_and_dry_run`) leave a library current for a caller that does not run under pytest. An autouse fixture now tears down whatever was left and restores the outer binding.
+- 2026-08-25 — All twelve review threads replied to and resolved in the same pass; the three bots re-pinged with their exact trigger phrases.
+- 2026-08-25 — Round three. Greptile came back 5/5 with no blocking failures, and CI went fully green. Codex raised one further P2 and cubic seven more (one P2, six P3).
+- 2026-08-25 — **The empty-structure fix had a twin one layer down, and Codex found it.** `reflect_structure_class` answers `None` for two different situations — a registered class declaring no field, and a field whose annotation it could not map — and `_class_backed_node` treated both as opaque, so a class-backed concept demanding nothing came back `kind: "unknown"` and the object-only guard silenced the lint. The deriver now separates them: zero fields is a reading, not a failure to read. The shared helper keeps its `None` because its other consumer, the native consistency probe, reads that as "structureless by design" — changing it there reddened `Dynamic` and `Composite`, which is how that distinction was found. Declined the other half of the finding: a model whose fields could not be read cannot honestly be told it "declares no required field".
+- 2026-08-25 — cubic's enum-convention point taken: the lint reads `FieldKind.is_object` (a new property mirroring the `is_list` beside it) and the `PresenceMarker.is_force` that already existed, rather than comparing members. Its P2 about `load_empty_library` accumulating one library per call was verified and **declined for this PR** — the fixture is class-scoped and shared by most of the suite, several modules calling it a dozen-plus times, so this is a conftest-level decision rather than a lint's; written up in `deferred.md`.
+- 2026-08-25 — Remaining cubic P3s all applied: the error-model page no longer says the registry is the enums the runtime *raises* (advisory members are never raised) nor that the corpus `error.*` namespace is still to come, and the design doc's status and channel-contract sentences match what actually landed.
+- 2026-08-25 — Round three landed in `f536e7c9e` (the deriver fix and the enum-convention reads) and `a10765d35` (the error-model, design and deferred-doc wording), with `make agent-check` and the full `make agent-test` green on that tree. All eight threads replied to and resolved in the same pass, and the three bots re-pinged.
+- 2026-08-25 — Round four. CI fully green on `a10765d35` and Greptile at six reviews with nothing blocking; cubic raised five more. Three taken: the hardcoded site count in this log dropped rather than corrected (the workspace rule is no counts at all), the design's §9 heading no longer presents settled decisions as pending, and — the one that was a real inaccuracy — `deferred.md` claimed the vacuous lint never comments on a library you merely depend on, which holds on the bundle channels but NOT on `validate all`, where `collect_current_library_entry_pipe_refs()` reads the same accumulated blueprints the hint lint does.
+- 2026-08-25 — **Two round-four P2s declined, both about the integration module's library lifecycle.** One repeats the `load_empty_library` accumulation already deferred. The other asks `_warnings` to restore the outer current-library binding instead of clearing it; verified false — `load_empty_library` captures `prev_library_id` before the class's FIRST `_load` (the `if library_id is None` guard) and restores it at class teardown, so the outer binding survives every intervening clear. What the `finally` clears is the library `validate_bundle` leaves open on success, which is exactly the binding that should not escape the test.
+- 2026-08-25 — Round five, all three taken and all documentation. The design's D2 said "the bare CLI" holds `ValidateBundleResult.blueprints`, which is true of its `validate bundle` and false of its `validate all` — the same distinction round four corrected in `deferred.md`, missed one doc over. The other two were this tracker contradicting its own storage rule: the live-state block recorded PR and branch status, and the header still called §9 pending. The branch deviation moved into the standing rule that named the wrong branch, which is where it belongs.
+- 2026-08-25 — Round six. Codex raised one P2 and it was **declined**: a `@model_validator` can reject the `{}` the descriptor calls satisfiable, which is true, but both offered remedies cost more than the symptom (dropping class-backed coverage, or running author validator code from inside a lint) and the blind spot belongs to `InputFormDeriver.is_required()`, which the form is rendered from — so the lint is reporting what the form will actually do. Recorded in `deferred.md` with the shape a real fix would take.
+- 2026-08-25 — Round seven, and the one real code finding since the descriptor fixes. **Codex caught an ordering bug this PR introduced the conditions for:** the bare CLI's `validate bundle` echoed its advisories AFTER the strict pending-signature gate raised `typer.Exit(1)`, so a bundle with any unimplemented placeholder printed none of them — while its `validate --all` twin, three functions up, deliberately echoes before its equivalent gate and says so in a comment. Moved, with a regression test that was mutation-checked by putting the call back. Note for anyone writing a similar test: `typer.Exit` is `click.exceptions.Exit`, NOT a `SystemExit`, so `pytest.raises(SystemExit)` never fires.
+- 2026-08-25 — cubic's channel over-claim was found for the third time in a third document, so it was swept rather than patched again: `hint_warnings.py` (twice), `pipelex/cli/agent_cli/CLAUDE.md` and `deferred.md` now all say "advisory-bearing" and name the two surfaces that carry none. The live-state block was trimmed once more to obey its own rule — the review-loop narrative moved to this log, and the inbox bullet reads as the decision it is rather than as another repo's working-tree state.
+- 2026-08-25 — Round eight, four cubic findings and all four valid. The one with teeth: **the "single-pipe surfaces carry none" wording was itself an over-claim**, the mirror image of the one round seven swept. `validate_pipe_in_bundle_core` — the `--pipe` slice of `validate bundle` / `validate method` — DOES carry the warnings, because it validates the whole bundle and narrows only the dry run; only bare `validate pipe <code>` omits them. Corrected at the three sites claiming otherwise plus the user-facing `agent-cli.md`. Also added the `validate --all` twin of the round-seven ordering test (mutation-checked the same way: moving that echo behind its gate reddens it), and made `deferred.md` say leaked manager state rather than "memory, not state any assertion can see" — the discarded ids do sit in the manager's bookkeeping until the class ends, even though nothing live is touched. The live-state block lost its "where the work stands" bullet, which restated the checkboxes above it and the bot-review loop below it.
+- 2026-08-25 — Round nine, two Codex findings, both valid and both taken minimally. **A shipped message was literally false:** the field-less variant said "only an empty object fits it", but `StructuredContent` inherits pydantic's default `extra="ignore"`, so `model_validate({'anything': 1})` succeeds and dumps to `{}` — verified in the venv before touching anything. Reworded to "any object satisfies it and none of it is read", which is both true and more useful. Only that branch was touched: the sibling "an empty object satisfies it" is not an exclusivity claim and is true, so the ~8 docs carrying it were left alone. The **one-TestClass-per-module rule** (AGENTS.md) was the other: `test_hint_warnings.py` already held three classes on `dev` and this branch made it four. Codex asked for a new module, which would duplicate the `_lint`/`_crate` helpers AND leave three classes behind — so the payload-bounds tests were merged into `TestHintLintFindings` instead, restoring the module to the count it had on `dev`. Splitting the pre-existing three is a separate refactor, not this PR's.
+- 2026-08-25 — Round ten. One of four taken: the two pending-signature tests raised on any `typer.Exit`, including code 0, while their whole point is the gate that exits **non-zero** — both now assert `exit_code == 1` (mutation-checked against 0). The other three declined and worth recording as a pattern: two were third-round wordsmithing of this tracker's own prose (a standing rule naming the branch, and step 4.3 unticked while the review loop it describes is still running — it is unticked because it is not finished), and one was the **third** pass over the same `deferred.md` paragraph, now asking for speculative effects ("can affect", "not necessarily invisible") on top of the rewording the previous round already made. A deferral note that is accurate does not get more accurate by accumulating hedges.
+- 2026-08-25 — Round eleven, and it corrected the previous round's own fix. Codex pointed out that "any object satisfies it and none of it is read" is only true under pydantic's DEFAULT `extra`: a structure class setting `extra="forbid"` rejects `{"x": 1}`, one setting `extra="allow"` retains and exposes it — both verified in the venv. The descriptor records `fields` only and never the model's extra policy, so the lint cannot speak to it at all. Both drafts had claimed more than the descriptor knows; the message now says "an empty object satisfies it", which is the strongest universally true claim and is the same clause the all-optional variant already used (the two variants are distinguished by their first half). The lesson worth keeping: when a message describes a model the lint only sees through a projection, the safe statement is the one the projection actually supports.
diff --git a/docs/building-methods/concepts/inline-structures.md b/docs/building-methods/concepts/inline-structures.md
index 228a28467..f728a2601 100644
--- a/docs/building-methods/concepts/inline-structures.md
+++ b/docs/building-methods/concepts/inline-structures.md
@@ -72,6 +72,27 @@ Field names must be valid Python identifiers and cannot be Python keywords; gene
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.
+## All-Optional Structures and the `input_presence_vacuous` Lint
+
+`required` defaults to **`false`** in the long form, and this is the difference between the two spellings that is easiest to miss:
+
+```toml
+[concept.RunOptions.structure]
+tone = "The tone to use" # shorthand: a REQUIRED text field
+depth = { type = "integer", description = "How deep to go" } # long form: OPTIONAL, because required defaults to false
+```
+
+A structure written entirely in the long form with no `required = true` anywhere is **all-optional**: its payload admits `{}`. That is perfectly legal, and often exactly right — an extraction concept that records whatever a document happens to state should not demand any particular field. A structure table holding *no* field at all is the degenerate case of the same thing — its payload admits only `{}` — and the lint below names it in its own words.
+
+It becomes a problem at one place only: when such a concept is named by a **method input that must be supplied** — an input of the bundle's declared `main_pipe`, written without a `?`. The declaration says "the caller must provide this", but since the empty object satisfies the concept, the only thing it can enforce is that the caller provides `{}`. Nothing is actually demanded, and a form, an API client or a person filling the input in has no way to tell what to put there. Validation reports this as the advisory `input_presence_vacuous` warning — the bundle stays **valid**, the warning never flips the verdict.
+
+There are two remedies, and which one is right depends on what you meant:
+
+- **The method can run without it.** Mark the input optional: `opts = "RunOptions?"`. Now absence is a declared, handled outcome rather than an empty object.
+- **The method genuinely needs something in it.** Give the concept at least one required field — either `required = true` on the field that matters, or the shorthand form, which is required by definition.
+
+The lint looks one level deep and only at entry pipes. A slot on an inner pipe is fed by dataflow, not by a caller, so it is never warned about; and a required field that is *itself* an all-optional concept is not warned about either.
+
## Supported Field Types
Inline structures support these field types:
diff --git a/docs/building-methods/pipes/understanding-optionality.md b/docs/building-methods/pipes/understanding-optionality.md
index f61378732..f4b93950a 100644
--- a/docs/building-methods/pipes/understanding-optionality.md
+++ b/docs/building-methods/pipes/understanding-optionality.md
@@ -101,10 +101,14 @@ You never discover an unhandled absence at run time. Validation walks every cont
| `optional_input_unguarded` | An unguarded template reference to a declared-optional input. |
| `optional_branch_required_field` | A maybe-absent parallel branch feeding a required structure field. |
-Two more optionality facts surface on the **valid** report (`pipelex validate`, the agent CLI, and the API):
+Two more facts surface on the **valid** report (`pipelex validate`, the agent CLI, and the API) — the first about optionality, the second a mixed bag of advisories that the same report carries:
- **`liftable_pipes`** — every pipe that may be silently skipped at run time, with the slots whose absence triggers the skip and where that absence can come from. Implicit lifting is acceptable *because* it is visible at build time.
-- **`warnings`** — advisory lints that never flip the verdict. The first is `optional_force_redundant`: a `!` whose slot is guaranteed present in every analyzed flow — the assertion can never fire, so the marker is dead weight.
+- **`warnings`** — advisory lints that never flip the verdict, spanning optionality and the intent-hint vocabulary alike. Every whole-bundle validate channel carries the same set — the protocol report, the agent CLI, the builder's per-bundle operations, and the bare CLI's `validate bundle` and `validate --all`. (`pipelex validate <PIPE_CODE>` makes no bundle-wide claim and prints none of them; neither does the builder's `validate_all`, which carries no `warnings` key at all.)
+
+ - `optional_force_redundant` — a `!` whose slot is guaranteed present in every analyzed flow, so the assertion can never fire and the marker is dead weight.
+ - `input_presence_vacuous` — a **method input** (an input of the bundle's declared `main_pipe`) that must be supplied, but whose concept declares no required field. The empty object satisfies it, so the declaration enforces nothing and a caller cannot tell what to fill in. Either mark the input `?`, or give the concept a required field. See [Inline Structures](../concepts/inline-structures.md#all-optional-structures-and-the-input_presence_vacuous-lint).
+ - `hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent` — the intent-hints lints: a hint key this version of the standard does not define, an `intent` word outside the vocabulary, and a known word on a site it does not apply to. Hints are non-normative, so the entry is preserved and only named.
## Best Practices
diff --git a/docs/contribute/mthds-test-corpus.md b/docs/contribute/mthds-test-corpus.md
index bb55c04a3..b8e114d89 100644
--- a/docs/contribute/mthds-test-corpus.md
+++ b/docs/contribute/mthds-test-corpus.md
@@ -90,7 +90,7 @@ An **exclusion** marks a registry code that no standalone focused entry could me
No native concept is excluded — every one of them turned out to support a real entry. `PipeFunc` is excluded: it names a Python function that the runtime resolves against its function registry *at validation time*, so an entry declaring one fails with `Function '<name>' not found in registry` in every consumer that has not registered that exact function — and a cross-language consumer cannot register a Python function at all. Exercise `PipeFunc` in a consumer's own fixtures, where the function exists.
-`error.*` carries the rest of the exclusions, and the distinction they turn on is worth stating: **membership in the registry means a value is reachable on the wire, never that a focused entry can produce it.** A corpus entry is a `.mthds` bundle validated through `validate bundle`, so a fault the validate path cannot reach is excluded here rather than pruned from the runtime's own truth. Two are unreachable by construction — `circular_dependency_error` is raised only by the pipe sorter, which runs on the builder's spec-to-blueprint conversion and never on a parsed `.mthds` file, and `unknown_concept` fires in the pipe factory under exactly the condition the earlier concept-reference resolution has already rejected as `unresolved_concept`. One has no shape an entry could take: `optional_force_redundant` rides the validation report's `warnings` array and never makes a verdict invalid, and the manifest models no warnings axis. The two `unknown_*` fallbacks are excluded because an entry pinning one would be pinning the absence of a diagnosis, and would have to be rewritten the moment the fault got a code of its own.
+`error.*` carries the rest of the exclusions, and the distinction they turn on is worth stating: **membership in the registry means a value is reachable on the wire, never that a focused entry can produce it.** A corpus entry is a `.mthds` bundle validated through `validate bundle`, so a fault the validate path cannot reach is excluded here rather than pruned from the runtime's own truth. Two are unreachable by construction — `circular_dependency_error` is raised only by the pipe sorter, which runs on the builder's spec-to-blueprint conversion and never on a parsed `.mthds` file, and `unknown_concept` fires in the pipe factory under exactly the condition the earlier concept-reference resolution has already rejected as `unresolved_concept`. Several have no shape an entry could take: the advisory-only codes — `optional_force_redundant`, `input_presence_vacuous`, and the three `hint_*` lints — ride the validation report's `warnings` array and never make a verdict invalid, so the bundle they fire on is valid and has no `expected_error` to carry, and the manifest models no warnings axis. The two `unknown_*` fallbacks are excluded because an entry pinning one would be pinning the absence of a diagnosis, and would have to be rewritten the moment the fault got a code of its own.
**Measure an exclusion, do not reason your way to one.** Every `error.*` exclusion reason above was established by writing the bundle that ought to trigger it and reading what the runtime actually said — which is how the first two turned out to be shadowed rather than merely awkward, and how the two the registry made look unreachable (`missing_pipe_type`, `native_concept_redeclaration`) turned out to have entries after all.
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 70b1c7582..ba32083b6 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. 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).
+ 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. Three families ride the array, always in this order: 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 vacuous-presence lint (`input_presence_vacuous`), an entry-pipe input that must be supplied but whose concept declares no required field, so the empty object satisfies it and a caller cannot tell what to fill in (see [Understanding Optionality](../../building-methods/pipes/understanding-optionality.md)); and the [intent-hint](../../building-methods/concepts/intent-hints.md) lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`). Every whole-bundle validate channel — this CLI, the bare CLI, the builder ops and the protocol validation report — assembles them from one composition point, so which advisories you see does not depend on which command you typed. Hint findings are bounded per site: a site naming many undefined keys reports the first few and then how many more there were, and a long authored key or value is elided in the message. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report; `validate pipe` omits it (no flow context to lint in). `validate bundle`/`validate method` with `--pipe` keep it, and it stays bundle-wide there — the slice narrows the dry run, not the validation.
### Fix
diff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.md
index 8335f538f..66770fc8c 100644
--- a/docs/tools/cli/validate.md
+++ b/docs/tools/cli/validate.md
@@ -132,6 +132,16 @@ When a validation error has a deterministic safe fix, the error output includes
See [Fix Commands](fix.md) for `pipelex fix bundle`, including the `--diff` preview.
+## Advisory Warnings
+
+A bundle can be valid and still be worth commenting on. When it is, `pipelex validate bundle` and `pipelex validate --all` print one yellow `Warning:` line per finding — advisory only: a warning never changes the verdict or the exit code. The lines come out ahead of the success message, and ahead of the strict pending-signature gate too, so a method still holding an unimplemented `PipeSignature` placeholder shows its warnings even though the command exits non-zero. Three families are reported, always in this order:
+
+- `optional_force_redundant` — a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire.
+- `input_presence_vacuous` — a method input (an input of the bundle's declared `main_pipe`) that must be supplied, but whose concept declares no required field: the empty object satisfies it, so a caller cannot tell what to fill in.
+- `hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent` — the [intent-hint](../../building-methods/concepts/intent-hints.md) lints. Hints are non-normative, so the entry is preserved and only named.
+
+The same findings ride the `warnings` array of the [agent CLI](agent-cli.md)'s JSON envelope and of the validation report, built from one composition point, so the surfaces cannot disagree. See [Understanding Optionality](../../building-methods/pipes/understanding-optionality.md) for what each one means for your method.
+
## What Validation Checks
All validation commands check:
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 48eff67e5..b412631d6 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -95,11 +95,11 @@ Besides `category` and `message`, each item carries whatever identity fields its
An item's `error_type` names the fault it reports, and that vocabulary is closed: `pipelex/validation_error_types.py` holds it in full, enumerated as `VALIDATION_ERROR_TYPES`. A consumer that needs to know which faults the language surface can report — a coverage gate, a test corpus, a client mapping errors onto its own UI — reads that registry instead of collecting strings from whichever diagnostics it happens to have seen.
-The registry is the union of the enums the runtime already raises, never a second list beside them: `PipeValidationErrorType` and `PipeFactoryErrorType` are the two stage vocabularies, and `ValidationResidualErrorType` names the one residual channel with no stage enum of its own. A member added to any of the three is in the registry the moment it is declared. `ValidationErrorItem.error_type` is typed against their union, so an unregistered string cannot be constructed or parsed onto an item — which is what makes the enumeration *closed* rather than merely documented, and what publishes the vocabulary into the OpenAPI schema `pipelex-api` serves for `/validate`.
+The registry is the union of the enums validation already reports through, never a second list beside them — "reports through", not "raises", because the advisory members ride `warnings` and are never raised as an exception at all: `PipeValidationErrorType` and `PipeFactoryErrorType` are the two stage vocabularies, `ValidationResidualErrorType` names the one residual channel with no stage enum of its own, and `HintLintErrorType` carries the intent-hint lints (which attach to concepts and structure fields too, so the pipe enum is the wrong home for them). A member added to any of them is in the registry the moment it is declared. `ValidationErrorItem.error_type` is typed against their union, so an unregistered string cannot be constructed or parsed onto an item — which is what makes the enumeration *closed* rather than merely documented, and what publishes the vocabulary into the OpenAPI schema `pipelex-api` serves for `/validate`.
Two spellings live in that one vocabulary, deliberately. The stage enums are snake_case codes (`missing_input_variable`); the dry-run residual is `DryRunError`, the name of the exception that produced it, because that residual is raised as an error object rather than classified into a code. Normalizing it would be a wire break across every consumer that pins the string, and it would buy nothing — the enumeration is closed either way.
-Membership means a value is *reachable on the wire*, not that it is a useful thing to exercise. `optional_force_redundant` rides `warnings` and never an invalid verdict, and the two `unknown_*` fallbacks fire on states no author can ask for. A consumer building coverage over the registry excludes those on its own side with a stated reason, rather than pruning them from the runtime truth here — that is what the [MTHDS Test Corpus](../contribute/mthds-test-corpus.md) vocabulary generator will do when its `error.*` namespace arrives with this registry.
+Membership means a value is *reachable on the wire*, not that it is a useful thing to exercise. Several members are advisory-only — `optional_force_redundant`, `input_presence_vacuous`, and the three `hint_*` lints — riding `warnings` and never an invalid verdict, and the two `unknown_*` fallbacks fire on states no author can ask for. A consumer building coverage over the registry excludes those on its own side with a stated reason, rather than pruning them from the runtime truth here — which is what the [MTHDS Test Corpus](../contribute/mthds-test-corpus.md) vocabulary generator already does, excluding each with its reason as it generates the `error.*` namespace from this registry.
`validation_errors` is one of the fields kept under STRICT disclosure (it is in `_STRICT_KEPT_FIELDS`): the items describe the caller's *own* submitted bundle, not server internals, so redacting them would gut the hosted path's diagnostics.
@@ -433,7 +433,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
|------|---------|
| `pipelex/base_exceptions.py` | `PipelexError`, `ErrorReport`, `ErrorDomain`, `ValidationErrorItem`, `error_domain_to_http_status()` |
| `pipelex/pipeline/validation_errors.py` | `build_validation_error_items()` — shared CLI/API structured bundle-validation builder |
-| `pipelex/validation_error_types.py` | The closed `error_type` registry — `VALIDATION_ERROR_TYPES`, `PipeValidationErrorType`, `PipeFactoryErrorType`, `ValidationResidualErrorType` |
+| `pipelex/validation_error_types.py` | The closed `error_type` registry — `VALIDATION_ERROR_TYPES`, `PipeValidationErrorType`, `PipeFactoryErrorType`, `ValidationResidualErrorType`, `HintLintErrorType` |
| `pipelex/cogt/exceptions.py` | `CogtError`, `InferenceErrorCategory` |
| `pipelex/cogt/inference/error_classification.py` | Extract — `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, per-provider `extract_*_metadata` functions, pure discriminators |
| `pipelex/cogt/inference/error_classify.py` | Classify — `classify_inference_error()`, `ClassificationResult` |
diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.md
index 71ee925d8..adb77cba7 100644
--- a/docs/under-the-hood/input-form-descriptor.md
+++ b/docs/under-the-hood/input-form-descriptor.md
@@ -26,7 +26,7 @@ The derivation is total. A node it cannot map honestly reports `kind: "unknown"`
Kinds are decided by chain membership and declared types — never by sniffing a schema shape. Per node, in precedence order:
-1. A concept with authored structure fields anywhere along its refinement chain is an `object`; its fields are the merged structures along the chain, base fields first, a refining concept overriding its parents'.
+1. A concept with an authored structure *table* anywhere along its refinement chain is an `object`; its fields are the merged structures along the chain, base fields first, a refining concept overriding its parents'. The table decides even when it is empty — the engine backs an empty `[concept.X.structure]` with a field-less structured model, not with `TextContent`, so the descriptor reports `object` with an empty `fields` list rather than falling through to rule 4.
2. Otherwise, the first `structure = "ClassName"` on the chain decides: a native class name (`TextContent`, `ImageContent`, …) maps by identity to that native's row; any other registered class is reflected field by field into an `object`; an unregistered or unmappable class is `unknown`.
3. Otherwise, a chain bottoming at a native concept takes that native's row, keeping the concept's own `concept_ref`, description and `refines`.
4. Otherwise — a description-only or string-described concept — `prose` with `refines` ending in `native.Text`: this engine backs such a concept with a `TextContent` subclass, so that is a stated fact, not shape invention.
@@ -59,6 +59,8 @@ Every node carries an optional `hints` slot: the node's **effective** MTHDS inte
On a top-level field, `required` is `presence != "optional"`, and `gating` — whether the run is blocked until the caller provides content — is `required` and not a variable-multiplicity list. A plain `Concept[]` slot is therefore `required: true, gating: false`: its empty form is the legitimate value `[]`. A fixed-count `Concept[N]` slot is a `list` with `item_count: N` that gates like any scalar. `Concept[1]` is a single node, because the runtime takes one value there (`StuffSpec.is_multiple()` is `count > 1`), and the descriptor says what the runtime accepts. Nested fields carry neither `presence` nor `gating`; their `required` is the payload fact.
+`gating` is also what the **vacuous-presence lint** is stated on. When a gating slot of an entry pipe names an `object` node whose `fields` carry no `required: true`, validation reports the advisory `input_presence_vacuous` warning: the caller is told the slot must be supplied, but the empty object satisfies it, so nothing is actually demanded. Keying the lint on `gating` rather than on `presence` is deliberate — `gating` is the fact a renderer blocks Run on, so the lint and the form cannot disagree about which slots demand content, and the variable-multiplicity exclusion falls out of the rule above instead of being restated. See [Understanding Optionality](../building-methods/pipes/understanding-optionality.md) for the author-facing description and its two remedies.
+
## Wire shape
Inapplicable slots are absent, never JSON `null`: the report's valid arm is dumped without `exclude_none`, so `InputFormField` owns its wire shape through a serializer that drops `None` values and writes the `date` kind's flag under its spec name `datetime`. Applicable falsy values (`required: false`, `integer: false`, `gating: false`) are kept. Per-kind validators keep a node honest at construction (`enum` needs `choices`, `object` needs `fields`, `list` needs `item`, `number` needs `integer`, `date` needs `datetime`).
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index d9013adfc..af3b714d5 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -299,7 +299,7 @@ class ValidationErrorItem(BaseModel):
(``ValidateBundleError.to_error_report``) call — so the CLI's structured
output and the API's 422 ``validation_errors`` can never drift. The same
item type also carries the report's advisory ``warnings``, built by
- ``pipelex.pipeline.optionality_warnings``: a warning is the same shape of
+ ``pipelex.pipeline.advisory_warnings``: a warning is the same shape of
diagnostic, differing only in that it does not make the verdict invalid.
``source`` is the declaring file path (CLI) or the per-content source the API
diff --git a/pipelex/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.py
index 1bcd0528c..13a9acb51 100644
--- a/pipelex/builder/operations/validate_ops.py
+++ b/pipelex/builder/operations/validate_ops.py
@@ -12,9 +12,9 @@ from pipelex.interpreter_hub import (
resolve_library_dirs,
set_current_library,
)
+from pipelex.pipeline.advisory_warnings import collect_advisory_warnings
+from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
from pipelex.pipeline.bundle_validator import BundleValidator
-from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
-from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.validate_bundle import build_validated_pipes, validate_bundle
if TYPE_CHECKING:
@@ -84,7 +84,8 @@ async def validate_bundle_file(
"pending_signatures": result.pending_signatures,
"is_runnable": not result.pending_signatures,
"warnings": [
- warning.model_dump(exclude_none=True) for warning in build_optionality_warnings(collect_controller_taint_analyses(result.pipes))
+ warning.model_dump(exclude_none=True)
+ for warning in collect_advisory_warnings(pipes=result.pipes, entry_pipe_refs=collect_entry_pipe_refs(result.blueprints))
],
}
@@ -117,7 +118,7 @@ async def validate_bundle_content(
"is_runnable": not validate_bundle_result.pending_signatures,
"warnings": [
warning.model_dump(exclude_none=True)
- for warning in build_optionality_warnings(collect_controller_taint_analyses(validate_bundle_result.pipes))
+ for warning in collect_advisory_warnings(pipes=validate_bundle_result.pipes, entry_pipe_refs=collect_entry_pipe_refs(blueprints))
],
}
@@ -211,6 +212,7 @@ async def validate_pipe_in_bundle(
"pending_signatures": result.pending_signatures,
"is_runnable": not result.pending_signatures,
"warnings": [
- warning.model_dump(exclude_none=True) for warning in build_optionality_warnings(collect_controller_taint_analyses(result.pipes))
+ warning.model_dump(exclude_none=True)
+ for warning in collect_advisory_warnings(pipes=result.pipes, entry_pipe_refs=collect_entry_pipe_refs(result.blueprints))
],
}
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 853f63058..8e8c71f68 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -18,7 +18,7 @@ Only the error format is backed by a module-level `ContextVar` in `agent_output.
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).
+- `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). The whole-bundle and whole-library surfaces also carry a `warnings` array — the advisory lints, rendered as a "Warnings" section in markdown — assembled by `pipelex/pipeline/advisory_warnings.py`, the ONE composition point every advisory-bearing channel calls (this CLI, the bare CLI, the builder ops and the protocol report). Bare `validate pipe <code>` carries none, and neither does the builder's `validate_all`; `validate bundle` / `validate method` with `--pipe` DO carry them, because they validate the whole bundle and only narrow the dry run, so the array stays bundle-wide there. Add a new advisory family there, never at a call site: the sites used to assemble their own and disagreed about which families they carried.
- `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`.
- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count, then one `## <path>` section per file that is not clean listing the entries applied, the entries blocked with their reason and guidance, and any unexplained paths. Paths, operation kinds and ledger-supplied values only — no value read from the user's file is ever rendered, in either format.
- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.
diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
index cd1dd0766..6e9e84885 100644
--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
@@ -13,10 +13,10 @@ from pipelex.interpreter_hub import (
resolve_library_dirs,
set_current_library,
)
+from pipelex.pipeline.advisory_warnings import collect_advisory_warnings, collect_current_library_entry_pipe_refs
+from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
from pipelex.pipeline.bundle_validator import BundleValidator
-from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
from pipelex.pipeline.execution_seams import acquire_library
-from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.validate_bundle import build_pending_signatures, build_validated_pipes, validate_bundle
if TYPE_CHECKING:
@@ -57,7 +57,10 @@ async def validate_all_core(*, library_dirs: list[Path] | None = None, allow_sig
pending_signatures = build_pending_signatures(get_pipe_library().get_pipes_dict())
# warnings: same advisory lint channel as the bundle surfaces — `validate all` has the
# whole library loaded, which is all the flow context the cross-flow aggregation needs.
+ # Its entry pipes come off the blueprints the library manager accumulated on the way in;
+ # there is no `ValidateBundleResult` on this path to read a `main_pipe` from.
library_pipes = list(get_pipe_library().get_pipes_dict().values())
+ warnings = collect_advisory_warnings(pipes=library_pipes, entry_pipe_refs=collect_current_library_entry_pipe_refs())
return {
"success": True,
"is_valid": True,
@@ -65,9 +68,7 @@ async def validate_all_core(*, library_dirs: list[Path] | None = None, allow_sig
"total_pipes": len(dry_run_results),
"pending_signatures": pending_signatures,
"is_runnable": not pending_signatures,
- "warnings": [
- warning.model_dump(exclude_none=True) for warning in build_optionality_warnings(collect_controller_taint_analyses(library_pipes))
- ],
+ "warnings": [warning.model_dump(exclude_none=True) for warning in warnings],
}
finally:
# Restore the caller's outer current-library FIRST (so the guarantee survives a teardown
@@ -119,7 +120,8 @@ async def validate_bundle_core(
"pending_signatures": result.pending_signatures,
"is_runnable": not result.pending_signatures,
"warnings": [
- warning.model_dump(exclude_none=True) for warning in build_optionality_warnings(collect_controller_taint_analyses(result.pipes))
+ warning.model_dump(exclude_none=True)
+ for warning in collect_advisory_warnings(pipes=result.pipes, entry_pipe_refs=collect_entry_pipe_refs(result.blueprints))
],
}
@@ -230,6 +232,7 @@ async def validate_pipe_in_bundle_core(
"pending_signatures": result.pending_signatures,
"is_runnable": not result.pending_signatures,
"warnings": [
- warning.model_dump(exclude_none=True) for warning in build_optionality_warnings(collect_controller_taint_analyses(result.pipes))
+ warning.model_dump(exclude_none=True)
+ for warning in collect_advisory_warnings(pipes=result.pipes, entry_pipe_refs=collect_entry_pipe_refs(result.blueprints))
],
}
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index ac7133943..3294c9c71 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -27,11 +27,11 @@ from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundErro
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_signature.signature_walk import collect_signature_refs
from pipelex.pipelex import Pipelex
+from pipelex.pipeline.advisory_warnings import collect_advisory_warnings, collect_current_library_entry_pipe_refs
+from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
from pipelex.pipeline.bundle_validator import BundleValidator
-from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.execution_seams import load_libraries_and_activate
-from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.validate_bundle import build_pending_signatures, validate_bundle
from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
@@ -47,13 +47,14 @@ if TYPE_CHECKING:
COMMAND = "validate"
-def _echo_optionality_warnings(*, pipes: list[PipeAbstract]) -> None:
- """Render the advisory optionality lints (e.g. the useless-`!` lint) in yellow.
+def _echo_advisory_warnings(*, pipes: list[PipeAbstract], entry_pipe_refs: list[str]) -> None:
+ """Render every advisory lint family in yellow, in the composition point's fixed order.
- Advisory only — a warning never changes the validation verdict or the exit code. Requires
- the validation library to still be loaded (the taint walk resolves child pipes via the hub).
+ Advisory only — a warning never changes the validation verdict or the exit code. Requires the
+ validation library to still be loaded: the taint walk resolves child pipes via the hub, and the
+ descriptors and the hint lint read the library's accumulated crate.
"""
- for warning in build_optionality_warnings(collect_controller_taint_analyses(pipes)):
+ for warning in collect_advisory_warnings(pipes=pipes, entry_pipe_refs=entry_pipe_refs):
typer.secho(f"Warning: {warning.message}", fg=typer.colors.YELLOW)
@@ -94,9 +95,10 @@ def do_validate_all_libraries_and_dry_run(*, library_dirs: list[Path] | None = N
# event — sweeping the library we just loaded, without teardown.
asyncio.run(BundleValidator().validate_current_library(allow_signatures=allow_signatures))
- # Advisory optionality lints over the whole loaded library (the lint's cross-flow
- # aggregation needs every flow) — printed even when the signature gate below exits non-zero.
- _echo_optionality_warnings(pipes=all_pipes)
+ # Advisory lints over the whole loaded library (the optionality lint's cross-flow
+ # aggregation needs every flow) — printed even when the signature gate below exits
+ # non-zero. The entry pipes come off the blueprints the library manager accumulated.
+ _echo_advisory_warnings(pipes=all_pipes, entry_pipe_refs=collect_current_library_entry_pipe_refs())
# Gate-from-report (D-B consumer-decides): signatures are never a validation error, but a
# library with unsatisfied PipeSignature placeholders is valid yet NOT runnable. `validate
@@ -135,6 +137,13 @@ async def _validate_pipe_or_bundle(
library_dirs=library_dirs,
allow_signatures=allow_signatures,
)
+ # Advisory lints, printed BEFORE the signature gate below exits non-zero — same ordering
+ # as `validate --all`. A method with an unimplemented placeholder is the state an author
+ # is most often in while building, and it is exactly then that the advisories help.
+ # validate_bundle leaves its validation library open on success, so the taint walk behind
+ # the lints can still resolve the bundle's pipes.
+ _echo_advisory_warnings(pipes=bundle_result.pipes, entry_pipe_refs=collect_entry_pipe_refs(bundle_result.blueprints))
+
# Gate-from-report (D-B consumer-decides): signatures are never a validation error, but a
# bundle with unsatisfied PipeSignature placeholders is valid yet NOT runnable. The CLI
# exits non-zero on `not is_runnable` unless --allow-signatures tolerates the placeholders.
@@ -152,9 +161,6 @@ async def _validate_pipe_or_bundle(
f"Successfully validated bundle '{bundle_path}'{_format_signatures_summary_suffix(signature_count=signature_count)}",
fg=typer.colors.GREEN,
)
- # validate_bundle leaves its validation library open on success, so the taint walk
- # behind the advisory lints can still resolve the bundle's pipes.
- _echo_optionality_warnings(pipes=bundle_result.pipes)
except FileNotFoundError as exc:
get_console().print(Traceback())
typer.secho(
diff --git a/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py b/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py
index 8eac782c3..99ed10b52 100644
--- a/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py
@@ -158,6 +158,13 @@ _ERROR_TYPE_EXCLUSIONS: dict[ValidationErrorType, str] = {
"valid one, so there is no shape a focused entry could take. Revisit if the manifest ever grows a "
"warnings axis."
),
+ PipeValidationErrorType.INPUT_PRESENCE_VACUOUS: (
+ "Advisory-only, for the same reason as `optional_force_redundant`: the entry-pipe vacuous-presence lint "
+ "rides the validation report's `warnings` array and never makes a verdict invalid. The bundle it fires "
+ "on is VALID — a gating input whose concept declares no required field is legal, merely undefinable for "
+ "a caller — so there is no `expected_error` an entry could carry. Revisit if the manifest ever grows a "
+ "warnings axis."
+ ),
HintLintErrorType.HINT_UNKNOWN_KEY: _ADVISORY_HINT_LINT_EXCLUSION,
HintLintErrorType.HINT_UNKNOWN_INTENT: _ADVISORY_HINT_LINT_EXCLUSION,
HintLintErrorType.HINT_INAPPLICABLE_INTENT: _ADVISORY_HINT_LINT_EXCLUSION,
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index 6359d8483..ca5789faa 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -268,6 +268,10 @@ class LibraryManager(LibraryManagerAbstract):
return matches[0]
return None
+ @override
+ def get_accumulated_blueprints(self, library_id: str) -> list[PipelexBundleBlueprint]:
+ return list(self._blueprints.get(library_id, []))
+
@override
def get_crate(self, library_id: str) -> LibraryCrate | None:
cached = self._crate_cache.get(library_id)
diff --git a/pipelex/libraries/library_manager_abstract.py b/pipelex/libraries/library_manager_abstract.py
index 706e6f67a..02c3ae598 100644
--- a/pipelex/libraries/library_manager_abstract.py
+++ b/pipelex/libraries/library_manager_abstract.py
@@ -97,6 +97,26 @@ class LibraryManagerAbstract(ABC):
A LibraryCrate built from all accumulated blueprints, or None
"""
+ @abstractmethod
+ def get_accumulated_blueprints(self, library_id: str) -> list[PipelexBundleBlueprint]:
+ """The bundle blueprints accumulated into a library, in load order.
+
+ The blueprint-derived load path (``load_libraries`` → ``load_from_blueprints``) retains what
+ it loaded so ``get_crate`` can rebuild the crate from it; this accessor hands the same list
+ to callers that need the *authored* batch facts a crate no longer carries — the declared
+ ``main_pipe`` of each bundle above all, which is what scopes the entry-pipe advisory lints
+ on the library-wide ``validate all`` path.
+
+ Empty for an unknown library, and empty on the transported-crate path (a direct
+ ``load_from_crate``, used by the Temporal workflow), which never accumulates blueprints.
+
+ Args:
+ library_id: The library to read the accumulated blueprints of
+
+ Returns:
+ The accumulated blueprints, or an empty list
+ """
+
@abstractmethod
def load_from_crate(self, *, library_id: str, crate: LibraryCrate) -> list[PipeAbstract]:
"""Load a LibraryCrate into a live Library.
diff --git a/pipelex/pipeline/advisory_warnings.py b/pipelex/pipeline/advisory_warnings.py
new file mode 100644
index 000000000..b48469208
--- /dev/null
+++ b/pipelex/pipeline/advisory_warnings.py
@@ -0,0 +1,102 @@
+"""The one composition point for the validation report's advisory `warnings`.
+
+A warning is a finding worth surfacing on a VALID bundle that must never flip `is_valid`. There are
+three families of them today, each derived from a different substrate:
+
+- **`optionality`** — the useless-`!` lint, from the controllers' taint analyses.
+- **`presence vacuity`** — the entry-pipe lint, from the input-form descriptors.
+- **`hints`** — the intent-hints lints, from the qualified crate.
+
+They used to be assembled site by site, and the sites disagreed: the protocol path carried the
+optionality and hint lints, while the agent CLI, the builder ops and the bare CLI each carried the
+optionality lint alone — so which advisories an author saw depended on which command they typed.
+This module removes that: one function builds every family in one fixed order, and every channel
+calls it. There is deliberately no flag selecting which families a channel carries, because such a
+flag would preserve exactly the disagreement this module exists to remove.
+
+Two entry points, because the channels hold different things in hand:
+
+- :func:`build_advisory_warnings` is pure over precomputed ingredients, for a caller that already
+ built them for other reasons (the protocol path needs `input_form` for the report anyway).
+- :func:`collect_advisory_warnings` gathers the ingredients itself, for a caller that holds only
+ the loaded pipes.
+
+Both must run **inside the open validation window**: the descriptors' class-backed reflection reads
+the class registry, and the crate is read off the current library.
+"""
+
+from collections.abc import Iterable, Sequence
+
+from pipelex.base_exceptions import ValidationErrorItem
+from pipelex.interpreter_hub import get_current_library, get_library_manager
+from pipelex.libraries.crate_qualification import QualifiedCrateContent
+from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
+from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
+from pipelex.pipeline.controller_taint import ControllerTaintAnalysis, collect_controller_taint_analyses
+from pipelex.pipeline.hint_warnings import build_hint_warnings
+from pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_form, qualify_current_library_crate
+from pipelex.pipeline.optionality_warnings import build_optionality_warnings
+from pipelex.pipeline.vacuous_presence_warnings import build_vacuous_presence_warnings
+
+
+def build_advisory_warnings(
+ *,
+ taint_analyses: Sequence[ControllerTaintAnalysis],
+ input_form: dict[str, PipeInputFormDescriptor],
+ entry_pipe_refs: Iterable[str],
+ qualified_crate: QualifiedCrateContent,
+) -> list[ValidationErrorItem]:
+ """Every advisory family, concatenated in one fixed order.
+
+ Pure: it derives nothing itself, so a caller that already built these artifacts pays for them
+ once. Each family is internally deterministic, and the family order is fixed here rather than
+ per channel — a consumer reading `warnings` sees the same sequence whichever command produced it.
+
+ Args:
+ taint_analyses: The controllers' analyses (`collect_controller_taint_analyses`).
+ input_form: The batch's input-form descriptors (`build_input_form`).
+ entry_pipe_refs: The qualified refs of the batch's entry pipes (`collect_entry_pipe_refs`).
+ qualified_crate: The current library's qualified crate (`qualify_current_library_crate`).
+
+ Returns:
+ The advisory items: optionality, then presence vacuity, then hints.
+ """
+ return [
+ *build_optionality_warnings(taint_analyses),
+ *build_vacuous_presence_warnings(input_form=input_form, entry_pipe_refs=entry_pipe_refs),
+ *build_hint_warnings(qualified_crate),
+ ]
+
+
+def collect_advisory_warnings(*, pipes: Sequence[PipeAbstract], entry_pipe_refs: Iterable[str]) -> list[ValidationErrorItem]:
+ """Gather every advisory ingredient inside the validation window, then build the warnings.
+
+ The crate is qualified ONCE here and handed to both consumers that need it — the descriptors and
+ the hint lint — rather than each qualifying the accumulated crate for itself.
+
+ Args:
+ pipes: The loaded pipes to judge (typically `ValidateBundleResult.pipes`, or every pipe of
+ the current library on the library-wide path).
+ entry_pipe_refs: The qualified refs of the batch's entry pipes (`collect_entry_pipe_refs`).
+
+ Returns:
+ The advisory items, in the order :func:`build_advisory_warnings` fixes.
+ """
+ qualified_crate = qualify_current_library_crate()
+ return build_advisory_warnings(
+ taint_analyses=collect_controller_taint_analyses(pipes),
+ input_form=build_input_form(pipes, qualified_crate=qualified_crate),
+ entry_pipe_refs=entry_pipe_refs,
+ qualified_crate=qualified_crate,
+ )
+
+
+def collect_current_library_entry_pipe_refs() -> list[str]:
+ """The entry pipe refs of every bundle accumulated into the current library.
+
+ What the library-wide channels use: `validate all` holds no `ValidateBundleResult`, so the
+ declared `main_pipe`s come off the blueprints the library manager retained on the way in.
+ Returns nothing for a library loaded straight from a transported crate, which accumulates no
+ blueprints — the same silence as a batch that declares no `main_pipe`.
+ """
+ return collect_entry_pipe_refs(get_library_manager().get_accumulated_blueprints(get_current_library()))
diff --git a/pipelex/pipeline/blueprint_selection.py b/pipelex/pipeline/blueprint_selection.py
index cbec48817..146989cb4 100644
--- a/pipelex/pipeline/blueprint_selection.py
+++ b/pipelex/pipeline/blueprint_selection.py
@@ -51,3 +51,28 @@ def select_primary_blueprint(blueprints: Sequence[PipelexBundleBlueprint]) -> Pr
main_pipe_ref = PipeFactory.make_pipe_ref_with_domain(domain_code=blueprint.domain, pipe_code=blueprint.main_pipe)
return PrimaryBlueprintSelection(blueprint=blueprint, main_pipe_ref=main_pipe_ref)
return PrimaryBlueprintSelection(blueprint=blueprints[0], main_pipe_ref=None)
+
+
+def collect_entry_pipe_refs(blueprints: Sequence[PipelexBundleBlueprint]) -> list[str]:
+ """The domain-qualified ``main_pipe`` of every blueprint in a batch, in declaration order.
+
+ An *entry pipe* is where a method meets its caller — a human, a form, an API client — which is
+ the boundary the advisory entry-pipe lints are scoped to. A blueprint that declares no
+ ``main_pipe`` contributes nothing, so a batch with none yields an empty list rather than
+ guessing at one.
+
+ Distinct from :func:`select_primary_blueprint`, which picks the ONE main pipe a batch is
+ canonically about (its graph target, its dry-run target). Both qualify a ``main_pipe`` the same
+ way, but a lint that must judge every declared entry point cannot use a rule that returns one.
+
+ Args:
+ blueprints: The batch's blueprints, in declaration order.
+
+ Returns:
+ The qualified entry-pipe refs, in the same order.
+ """
+ return [
+ PipeFactory.make_pipe_ref_with_domain(domain_code=blueprint.domain, pipe_code=blueprint.main_pipe)
+ for blueprint in blueprints
+ if blueprint.main_pipe
+ ]
diff --git a/pipelex/pipeline/hint_warnings.py b/pipelex/pipeline/hint_warnings.py
index fd19733cd..21be5c758 100644
--- a/pipelex/pipeline/hint_warnings.py
+++ b/pipelex/pipeline/hint_warnings.py
@@ -3,9 +3,9 @@
The spec's SHOULD-warn rules — an unknown hint key, an unknown `intent` word, a known word on a
site it does not apply to — cannot live in pydantic validators: a validator can only raise, and
these must never reject. Well-formed unknown content is preserved into the crate and the
-descriptor untouched; the lint only names it. Same channel as `build_optionality_warnings`: one
-advisory `ValidationErrorItem` per finding on the report's `warnings` array, never flipping
-`is_valid`.
+descriptor untouched; the lint only names it. One advisory `ValidationErrorItem` per finding on
+the report's `warnings` array, never flipping `is_valid` — composed with the other advisory
+families in `advisory_warnings.py`, which is what every advisory-bearing validate channel calls.
Site applicability follows the spec's Applicability section: text-valued and number-valued sites
are judged structurally over the qualified crate (description-only concepts are text-valued;
@@ -19,7 +19,6 @@ from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBl
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
from pipelex.core.qualified_ref import QualifiedRef
-from pipelex.interpreter_hub import get_current_library_id_or_none, get_library_manager
from pipelex.language.intent_hints import (
INTENT_HINT_KEY,
KNOWN_HINT_KEYS,
@@ -28,13 +27,35 @@ from pipelex.language.intent_hints import (
intent_word_applies,
is_intent_word_known,
)
-from pipelex.libraries.crate_qualification import QualifiedCrateContent, qualify_crate
+from pipelex.libraries.crate_qualification import QualifiedCrateContent
from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint
from pipelex.validation_error_types import HintLintErrorType
_NATIVE_TEXT_REF = NativeConceptCode.TEXT.concept_ref
_NATIVE_NUMBER_REF = NativeConceptCode.NUMBER.concept_ref
+MAX_HINT_FINDINGS_PER_SITE = 5
+"""How many undefined hint keys one site reports individually before the rest collapse into a tail.
+
+The unknown-key rule emits one finding per undefined key, so a site's finding count is bounded only
+by how many keys the author wrote. That was tolerable while the lint reached the API path alone; it
+now rides every advisory-bearing validate channel, including ones an author invokes casually, so a site that names fifty keys reports
+the first few and then says how many more there were."""
+
+MAX_AUTHORED_TOKEN_LENGTH = 60
+"""How much of an authored hint key or value a message quotes before eliding the rest.
+
+Hint keys and values are free strings, interpolated raw into the finding's `message`. Long enough to
+identify the entry the author wrote, short enough that a whole document pasted into a hint value
+cannot inflate the warning payload."""
+
+
+def elide_authored_token(*, token: str) -> str:
+ """An authored token, cut to a length a diagnostic can quote (an elided one ends in an ellipsis)."""
+ if len(token) <= MAX_AUTHORED_TOKEN_LENGTH:
+ return token
+ return f"{token[:MAX_AUTHORED_TOKEN_LENGTH]}..."
+
def _native_class_value_kind(*, class_name: str) -> HintSiteValueKind:
"""The value kind of a class-backed structure, by native-class identity.
@@ -68,19 +89,6 @@ def _native_class_value_kind(*, class_name: str) -> HintSiteValueKind:
return HintSiteValueKind.OTHER
-def build_current_library_hint_warnings() -> list[ValidationErrorItem]:
- """Hint lint over the current library's accumulated crate.
-
- Same window contract as `build_input_form`; with no current library or no crate the sweep
- is empty (the fallback path derives nothing to lint).
- """
- library_id = get_current_library_id_or_none()
- crate = get_library_manager().get_crate(library_id=library_id) if library_id else None
- if crate is None:
- return []
- return build_hint_warnings(qualify_crate(crate))
-
-
def build_hint_warnings(qualified: QualifiedCrateContent) -> list[ValidationErrorItem]:
"""Sweep the qualified crate's three hint sites and emit one advisory item per finding.
@@ -166,18 +174,25 @@ class _HintLinter:
variable_names: list[str] | None = None,
) -> list[ValidationErrorItem]:
findings: list[tuple[HintLintErrorType, str]] = []
- for key in hints:
- if key not in KNOWN_HINT_KEYS:
- unknown_key_message = (
- f"Hint key '{key}' on {site_desc} is not defined by this version of the standard "
- f"(known keys: {', '.join(sorted(KNOWN_HINT_KEYS))}). The entry is preserved; consumers ignore it."
- )
- findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, unknown_key_message))
+ unknown_keys = [key for key in hints if key not in KNOWN_HINT_KEYS]
+ for key in unknown_keys[:MAX_HINT_FINDINGS_PER_SITE]:
+ unknown_key_message = (
+ f"Hint key '{elide_authored_token(token=key)}' on {site_desc} is not defined by this version of the standard "
+ f"(known keys: {', '.join(sorted(KNOWN_HINT_KEYS))}). The entry is preserved; consumers ignore it."
+ )
+ findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, unknown_key_message))
+ overflow = len(unknown_keys) - MAX_HINT_FINDINGS_PER_SITE
+ if overflow > 0:
+ overflow_message = (
+ f"...and {overflow} more hint key(s) on {site_desc} are not defined by this version of the standard. "
+ f"The entries are preserved; consumers ignore them."
+ )
+ findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, overflow_message))
intent_word = hints.get(INTENT_HINT_KEY)
if intent_word is not None:
if not is_intent_word_known(intent_word):
unknown_intent_message = (
- f"Intent word '{intent_word}' on {site_desc} is not in this version's vocabulary "
+ f"Intent word '{elide_authored_token(token=intent_word)}' on {site_desc} is not in this version's vocabulary "
f"(prose, label, rating, quantity). The entry is preserved; consumers ignore it."
)
findings.append((HintLintErrorType.HINT_UNKNOWN_INTENT, unknown_intent_message))
@@ -188,7 +203,7 @@ class _HintLinter:
case IntentWord.RATING | IntentWord.QUANTITY:
needed_kind = "number"
inapplicable_message = (
- f"Intent word '{intent_word}' does not apply to {site_desc} (the site is not "
+ f"Intent word '{elide_authored_token(token=intent_word)}' does not apply to {site_desc} (the site is not "
f"{needed_kind}-valued). The entry is preserved; consumers ignore it there."
)
findings.append((HintLintErrorType.HINT_INAPPLICABLE_INTENT, inapplicable_message))
diff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.py
index 15c8df222..e633c14f3 100644
--- a/pipelex/pipeline/input_form.py
+++ b/pipelex/pipeline/input_form.py
@@ -45,7 +45,7 @@ from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import PresenceMarker, fixed_item_count
from pipelex.interpreter_hub import get_current_library, get_library_manager
from pipelex.language.intent_hints import HintSiteValueKind, IntentWord, applicable_intent, merge_hints
-from pipelex.libraries.crate_qualification import qualify_crate
+from pipelex.libraries.crate_qualification import QualifiedCrateContent, qualify_crate
from pipelex.libraries.library_crate_factory import LibraryCrateFactory
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint
@@ -86,6 +86,25 @@ class FieldKind(StrEnum):
):
return False
+ @property
+ def is_object(self) -> bool:
+ match self:
+ case FieldKind.OBJECT:
+ return True
+ case (
+ FieldKind.TEXT
+ | FieldKind.PROSE
+ | FieldKind.NUMBER
+ | FieldKind.BOOLEAN
+ | FieldKind.DATE
+ | FieldKind.ENUM
+ | FieldKind.DOCUMENT
+ | FieldKind.IMAGE
+ | FieldKind.LIST
+ | FieldKind.UNKNOWN
+ ):
+ return False
+
class InputFormField(BaseModel):
"""One field descriptor: a recursive node discriminated on `kind`.
@@ -203,7 +222,7 @@ class PipeInputFormDescriptor(BaseModel):
"""One field descriptor per input slot, in authored input order. Empty for a pipe with no inputs."""
-def build_input_form(pipes: Sequence[PipeAbstract]) -> dict[str, PipeInputFormDescriptor]:
+def build_input_form(pipes: Sequence[PipeAbstract], *, qualified_crate: QualifiedCrateContent | None = None) -> dict[str, PipeInputFormDescriptor]:
"""Derive the `input_form` descriptors of loaded pipes from the authored blueprints of the current library.
Works on any loaded `PipeAbstract`, `PipeSignature` placeholders included, iterating exactly
@@ -214,12 +233,15 @@ def build_input_form(pipes: Sequence[PipeAbstract]) -> dict[str, PipeInputFormDe
Args:
pipes: The loaded pipes to describe (typically `ValidateBundleResult.pipes`).
+ qualified_crate: The current library's already-qualified crate, when the caller holds one.
+ Qualification is a whole-crate walk, and a caller that runs several artifacts over the
+ same window (the advisory-warnings collector) would otherwise pay for it twice. Omit it
+ and the crate is read and qualified here, as before.
Returns:
`pipe_ref` → `PipeInputFormDescriptor` for every given pipe.
"""
- crate = get_library_manager().get_crate(library_id=get_current_library()) or LibraryCrateFactory.make_from_blueprints([])
- qualified = qualify_crate(crate)
+ qualified = qualified_crate if qualified_crate is not None else qualify_current_library_crate()
deriver = InputFormDeriver(concepts=qualified.concepts)
input_form: dict[str, PipeInputFormDescriptor] = {}
for pipe in pipes:
@@ -236,6 +258,18 @@ def build_input_form(pipes: Sequence[PipeAbstract]) -> dict[str, PipeInputFormDe
return input_form
+def qualify_current_library_crate() -> QualifiedCrateContent:
+ """The current library's accumulated crate, qualified — empty when the library holds none.
+
+ The single place that knows how to reach the authored facts of the open validation window, so
+ the artifacts derived from them (the descriptors, the advisory lints) cannot read different
+ facts. Requires a current library, like every other artifact built inside the window; a library
+ that accumulated no blueprints yields an empty crate, from which every consumer derives nothing.
+ """
+ crate = get_library_manager().get_crate(library_id=get_current_library()) or LibraryCrateFactory.make_from_blueprints([])
+ return qualify_crate(crate)
+
+
def _slot_hints_of(slot_value: "str | InputSlotBlueprint | None") -> dict[str, str] | None:
"""The authored hints of an input-slot value; only the expanded table form carries any."""
return slot_value.hints if isinstance(slot_value, InputSlotBlueprint) else None
@@ -327,7 +361,7 @@ class InputFormDeriver:
) -> InputFormField:
refines = chain or None
merged_structure = self._merged_structure(concept_ref=concept_ref, chain=chain)
- if merged_structure:
+ if merged_structure is not None:
fields = [self._structure_field(name=field_name, field=field, seen=seen) for field_name, field in merged_structure.items()]
return InputFormField(
kind=FieldKind.OBJECT,
@@ -433,7 +467,14 @@ class InputFormDeriver:
return _unknown_node(name=name, concept_ref=concept_ref, description=description, refines=refines)
reflected = reflect_structure_class(structure_class=structure_class)
if reflected is None:
- return _unknown_node(name=name, concept_ref=concept_ref, description=description, refines=refines)
+ if structure_class.model_fields:
+ # A field this reflection could not map: the payload's shape is genuinely opaque here.
+ return _unknown_node(name=name, concept_ref=concept_ref, description=description, refines=refines)
+ # A class declaring no field at all is not opaque — it states a payload that demands
+ # nothing, the class-backed twin of an empty authored structure table, and the form says
+ # so. (`reflect_structure_class` collapses both into `None` because its other consumer,
+ # the native consistency probe, reads `None` as "structureless by design".)
+ reflected = {}
fields = [
_with_reflected_constraints(
node=self._structure_field(name=field_name, field=field, seen=seen), field_info=structure_class.model_fields[field_name]
@@ -462,13 +503,20 @@ class InputFormDeriver:
current = self._concepts.get(link)
return chain
- def _merged_structure(self, *, concept_ref: str, chain: list[str]) -> dict[str, ConceptStructureBlueprintType]:
- """The authored structure fields along the chain, base fields first, a refining concept overriding its parents'."""
- merged: dict[str, ConceptStructureBlueprintType] = {}
+ def _merged_structure(self, *, concept_ref: str, chain: list[str]) -> dict[str, ConceptStructureBlueprintType] | None:
+ """The authored structure fields along the chain, base fields first, a refining concept overriding its parents'.
+
+ `None` when no concept along the chain authors a structure table at all; `{}` when one does and
+ that table is empty. The distinction is the engine's own: `ConceptFactory` branches on
+ `structure is not None`, so an authored-but-empty table is backed by a field-less structured
+ model with an empty object schema — not by `TextContent`. Testing truthiness here would report
+ that concept as `prose` with a `native.Text` refines link nobody authored.
+ """
+ merged: dict[str, ConceptStructureBlueprintType] | None = None
for ref in [*reversed(chain), concept_ref]:
entry = self._concepts.get(ref)
if isinstance(entry, ConceptBlueprint) and isinstance(entry.structure, dict):
- merged.update(entry.structure)
+ merged = {**(merged or {}), **entry.structure}
return merged
def _first_class_structure(self, *, concept_ref: str, chain: list[str]) -> str | None:
diff --git a/pipelex/pipeline/optionality_warnings.py b/pipelex/pipeline/optionality_warnings.py
index 7d15e8fb1..0617dbf14 100644
--- a/pipelex/pipeline/optionality_warnings.py
+++ b/pipelex/pipeline/optionality_warnings.py
@@ -21,6 +21,7 @@ from collections.abc import Sequence
from typing import TYPE_CHECKING
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.core.qualified_ref import QualifiedRef
from pipelex.pipeline.controller_taint import ControllerTaintAnalysis
from pipelex.validation_error_types import PipeValidationErrorType
@@ -57,7 +58,9 @@ def build_optionality_warnings(taint_analyses: Sequence[ControllerTaintAnalysis]
if consumption_key in asserted:
continue
pipe_ref, variable_name = consumption_key
- domain_code, _, pipe_code = pipe_ref.partition(".")
+ # Split on the LAST dot: a domain is a dotted path ('legal.contracts'), so a leading-dot split
+ # would hand the locator a truncated domain and a pipe code carrying the rest of it.
+ locator = QualifiedRef.parse(pipe_ref)
flow_refs = sorted({observation.within_pipe_ref for observation in redundant[consumption_key]})
flows_desc = ", ".join(f"'{flow_ref}'" for flow_ref in flow_refs)
message = (
@@ -69,8 +72,8 @@ def build_optionality_warnings(taint_analyses: Sequence[ControllerTaintAnalysis]
ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
error_type=PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT,
- pipe_code=pipe_code,
- domain_code=domain_code,
+ pipe_code=locator.local_code,
+ domain_code=locator.domain_path,
variable_names=[variable_name],
message=message,
)
diff --git a/pipelex/pipeline/vacuous_presence_warnings.py b/pipelex/pipeline/vacuous_presence_warnings.py
new file mode 100644
index 000000000..f13ef9130
--- /dev/null
+++ b/pipelex/pipeline/vacuous_presence_warnings.py
@@ -0,0 +1,106 @@
+"""The vacuous-presence lint (`input_presence_vacuous`) for the validate surfaces.
+
+A method input declared without `?` says "the caller must supply this". When the concept behind
+that input declares no required field, the concept's schema admits `{}` — so the only thing the
+declaration can enforce is that the caller supplies an empty object. Nothing is actually demanded,
+and every consumer that has to *materialise* the input (a form, an API client, a human) is left
+inventing a meaning. That is what this lint names, on the report's advisory `warnings` array, so it
+never flips `is_valid`.
+
+Two scoping decisions define the rule, both stated in `wip/full-optional/design.md`:
+
+- **Entry pipes only.** The smell exists at the boundary where a caller has to conjure the value —
+ the bundle's declared `main_pipe`. On an inner pipe the slot is fed by dataflow, and an
+ all-optional structure is a legitimate and common producer shape ("record whatever the document
+ states"), so neither remedy the message offers would apply.
+- **Judged on `gating`, not on `presence`.** `gating` is the descriptor's stated fact that a
+ renderer must block Run until the slot has content, and the lint is precisely "you asked for a
+ gate but content is undefinable here". Keying the lint on the same fact the renderer keys on
+ means the two cannot disagree, and the variable-multiplicity exclusion (`Concept[]` never gates,
+ because `[]` is its legitimate value) falls out of the descriptor's rule instead of being
+ restated here.
+
+Nested structures are judged **one level deep**: a required field that is itself an all-optional
+object does not warn in this version (design §7 — the transitive notion's boundary is arguable, and
+a lint whose boundary is arguable is a lint that gets ignored).
+"""
+
+from collections.abc import Iterable, Mapping
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.core.qualified_ref import QualifiedRef
+from pipelex.pipeline.input_form import InputFormField, PipeInputFormDescriptor
+from pipelex.validation_error_types import PipeValidationErrorType
+
+
+def build_vacuous_presence_warnings(
+ *,
+ input_form: Mapping[str, PipeInputFormDescriptor],
+ entry_pipe_refs: Iterable[str],
+) -> list[ValidationErrorItem]:
+ """Project the entry pipes' input-form descriptors into advisory `warnings` items.
+
+ Args:
+ input_form: The batch's `input_form` descriptors, keyed by namespaced `pipe_ref`
+ (the output of `build_input_form`).
+ entry_pipe_refs: The domain-qualified refs of the batch's entry pipes. Refs with no
+ descriptor are skipped, so a batch with no `main_pipe` is simply not linted.
+
+ Returns:
+ One `input_presence_vacuous` item per (entry pipe, gating slot whose concept demands
+ nothing), ordered by entry pipe ref then by authored slot order.
+ """
+ warnings: list[ValidationErrorItem] = []
+ for pipe_ref in sorted(set(entry_pipe_refs)):
+ descriptor = input_form.get(pipe_ref)
+ if descriptor is None:
+ continue
+ for slot in descriptor.fields:
+ item = _warning_for_slot(pipe_ref=pipe_ref, slot=slot)
+ if item is not None:
+ warnings.append(item)
+ return warnings
+
+
+def _warning_for_slot(*, pipe_ref: str, slot: InputFormField) -> ValidationErrorItem | None:
+ """The item a top-level slot earns, or `None` when the slot is silent."""
+ if not slot.gating or not slot.kind.is_object:
+ return None
+ if any(field.required for field in slot.fields or []):
+ return None
+ concept_ref = slot.concept_ref
+ if concept_ref is None:
+ # No concept to name, hence no honest message to state: the lint's whole claim is about
+ # what a named concept declares.
+ return None
+ # Split on the LAST dot: a domain is a dotted path ('legal.contracts'), so a leading-dot split
+ # would hand the locator a truncated domain and a pipe code carrying the rest of it.
+ locator = QualifiedRef.parse(pipe_ref)
+ return ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=PipeValidationErrorType.INPUT_PRESENCE_VACUOUS,
+ pipe_code=locator.local_code,
+ domain_code=locator.domain_path,
+ variable_names=[slot.name],
+ message=_message(pipe_ref=pipe_ref, slot=slot, concept_ref=concept_ref),
+ )
+
+
+def _message(*, pipe_ref: str, slot: InputFormField, concept_ref: str) -> str:
+ """The finding's prose: what was declared, why it enforces nothing, and the two remedies.
+
+ Carries no authored free text (no descriptions), so it needs no eliding — unlike the hint lint,
+ which interpolates authored content.
+ """
+ marker_desc = "declared with a force marker '!'" if slot.presence is not None and slot.presence.is_force else "declared without '?'"
+ if slot.fields:
+ defect = f"concept '{concept_ref}' declares no required field — an empty object satisfies it"
+ second_remedy = f"make at least one field of '{concept_ref}' required"
+ else:
+ defect = f"concept '{concept_ref}' declares no field at all — an empty object satisfies it"
+ second_remedy = f"give '{concept_ref}' a required field"
+ return (
+ f"Input '{slot.name}' of pipe '{pipe_ref}' must be supplied ({marker_desc}), but {defect}, "
+ f"so a caller cannot tell what to fill in. "
+ f'Mark the input optional (`{slot.name} = "{concept_ref}?"`) if the pipe can run without it, or {second_remedy}.'
+ )
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
index 3cddca5f7..9118f54bc 100644
--- a/pipelex/pipeline/validate_in_process.py
+++ b/pipelex/pipeline/validate_in_process.py
@@ -27,12 +27,11 @@ from pipelex import log
from pipelex.base_exceptions import PipelexError, ValidationErrorItem
from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
-from pipelex.pipeline.blueprint_selection import select_primary_blueprint
+from pipelex.pipeline.advisory_warnings import build_advisory_warnings
+from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs, select_primary_blueprint
from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
-from pipelex.pipeline.hint_warnings import build_current_library_hint_warnings
-from pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_form
+from pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_form, qualify_current_library_crate
from pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pipes
-from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.pipe_io_contracts import PipeIOContract, build_pipe_io_contracts
from pipelex.pipeline.validate_bundle import validate_bundle
from pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_report
@@ -108,11 +107,18 @@ async def validate_bundles_in_process(
# something inside the window later moves the contextvar.
validation_library_id = get_current_library_id_or_none()
pipe_io_contracts: dict[str, PipeIOContract] = build_pipe_io_contracts(result.pipes)
- input_form: dict[str, PipeInputFormDescriptor] = build_input_form(result.pipes)
+ # One crate qualification per validate pass — the descriptors and the hint lint read the same one.
+ qualified_crate = qualify_current_library_crate()
+ input_form: dict[str, PipeInputFormDescriptor] = build_input_form(result.pipes, qualified_crate=qualified_crate)
# One taint walk per validate pass — both report projections read the same analyses.
taint_analyses = collect_controller_taint_analyses(result.pipes)
liftable_pipes: list[LiftablePipeEntry] = build_liftable_pipes(taint_analyses)
- warnings: list[ValidationErrorItem] = build_optionality_warnings(taint_analyses) + build_current_library_hint_warnings()
+ warnings: list[ValidationErrorItem] = build_advisory_warnings(
+ taint_analyses=taint_analyses,
+ input_form=input_form,
+ entry_pipe_refs=collect_entry_pipe_refs(result.blueprints),
+ qualified_crate=qualified_crate,
+ )
graph_target_ref = graph_pipe_code if graph_pipe_code is not None else select_primary_blueprint(result.blueprints).main_pipe_ref
graph_spec: GraphSpec | None = await best_effort_graph_spec(
pipe_ref=graph_target_ref,
diff --git a/pipelex/pipeline/validation_report.py b/pipelex/pipeline/validation_report.py
index 1c916a3f7..9538b36a8 100644
--- a/pipelex/pipeline/validation_report.py
+++ b/pipelex/pipeline/validation_report.py
@@ -104,7 +104,7 @@ def build_validation_report(
pending_signatures: Library-wide unsatisfied signature refs.
graph_spec: Best-effort graph of the declared main pipe, when one was produced.
liftable_pipes: Entries from `build_liftable_pipes`, when the caller computed them.
- warnings: Advisory items from `build_optionality_warnings`, when the caller computed them.
+ warnings: Advisory items from `build_advisory_warnings`, when the caller computed them.
Returns:
The canonical report.
diff --git a/pipelex/test_extras/mthds_corpus/vocabulary.toml b/pipelex/test_extras/mthds_corpus/vocabulary.toml
index a0d8c0120..441b1b637 100644
--- a/pipelex/test_extras/mthds_corpus/vocabulary.toml
+++ b/pipelex/test_extras/mthds_corpus/vocabulary.toml
@@ -161,6 +161,10 @@ fails_at = "runtime"
code = "optional_force_redundant"
excluded = "Advisory-only: it rides the validation report's `warnings` array and never makes a verdict invalid. An entry contract that models one `expected_error` on an invalid entry has nowhere to put a warning on a valid one, so there is no shape a focused entry could take. Revisit if the manifest ever grows a warnings axis."
+[error.input_presence_vacuous]
+code = "input_presence_vacuous"
+excluded = "Advisory-only, for the same reason as `optional_force_redundant`: the entry-pipe vacuous-presence lint rides the validation report's `warnings` array and never makes a verdict invalid. The bundle it fires on is VALID — a gating input whose concept declares no required field is legal, merely undefinable for a caller — so there is no `expected_error` an entry could carry. Revisit if the manifest ever grows a warnings axis."
+
[error.native_concept_redeclaration]
code = "native_concept_redeclaration"
fails_at = "runtime"
diff --git a/pipelex/validation_error_types.py b/pipelex/validation_error_types.py
index 93f9a519c..69a4b64a8 100644
--- a/pipelex/validation_error_types.py
+++ b/pipelex/validation_error_types.py
@@ -9,10 +9,10 @@ whatever diagnostics it happens to have seen.
The registry is a **union of the enums the runtime already raises**, never a second list beside
them. ``PipeValidationErrorType`` and ``PipeFactoryErrorType`` are the two vocabularies the
-validation stages produce, and :class:`ValidationResidualErrorType` names the one residual
-channel that has no stage enum of its own. Deriving the registry from them is what stops it
-from drifting: a member added to any of the three is in the registry the moment it is declared,
-with nothing here to remember to update.
+validation stages produce, :class:`ValidationResidualErrorType` names the one residual channel
+that has no stage enum of its own, and :class:`HintLintErrorType` carries the intent-hint lints.
+Deriving the registry from them is what stops it from drifting: a member added to any of them is
+in the registry the moment it is declared, with nothing here to remember to update.
**Two spellings live in one vocabulary, deliberately.** The stage enums are snake_case codes
(``missing_input_variable``), while the dry-run residual is ``DryRunError`` — the name of the
@@ -76,6 +76,11 @@ class PipeValidationErrorType(StrEnum):
# assertion can never fire.
OPTIONAL_FORCE_REDUNDANT = "optional_force_redundant"
+ # Advisory-only (rides the validation report's `warnings` array, never raised as an error):
+ # a gating input of an entry pipe whose concept declares no required field — the empty object
+ # satisfies the declaration, so "the caller must supply this" can enforce nothing.
+ INPUT_PRESENCE_VACUOUS = "input_presence_vacuous"
+
# 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.
@@ -114,6 +119,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
@@ -143,6 +149,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
@@ -179,6 +186,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
@@ -210,6 +218,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
@@ -244,6 +253,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
@@ -304,7 +314,7 @@ ValidationErrorType: TypeAlias = PipeValidationErrorType | PipeFactoryErrorType
"""The type of a bundle-validation diagnostic's ``error_type``.
``ValidationErrorItem.error_type`` is typed against this alias, which is what makes the registry
-*closed* rather than merely documented: a value outside these three enums cannot be constructed
+*closed* rather than merely documented: a value outside these enums cannot be constructed
onto the wire, so the enumeration below and the values a consumer actually observes cannot
disagree.
"""
@@ -321,7 +331,7 @@ Ordered by contributing enum, then by declaration order within it — so a gener
on this registry (the MTHDS Test Corpus tag vocabulary is the first) is stable across runs and a
new member shows up as one added line rather than a reshuffle.
-The three enums are value-disjoint, and that is a property worth stating rather than assuming:
+The contributing enums are value-disjoint, and that is a property worth stating rather than assuming:
were two of them to share a wire value, ``error_type`` would stop identifying the fault and the
alias above would resolve it to whichever enum pydantic tried first. It is gated by
``tests/unit/pipelex/errors/test_validation_error_types.py``.
diff --git a/subject_grants.toml b/subject_grants.toml
index 4237c9e7c..3a43ce4ae 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -3828,6 +3828,10 @@ rationale = "Predicate-style check on the version constraint; single operand."
param = "blueprints"
rationale = "Derivation: finds dirs from the blueprints; single operand."
+["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_accumulated_blueprints"]
+param = "library_id"
+rationale = "Manager getter keyed by the library id; single operand."
+
["pipelex/libraries/library_manager_abstract.py::LibraryManagerAbstract.get_crate"]
param = "library_id"
rationale = "Manager getter keyed by the library id; single operand."
@@ -4400,6 +4404,10 @@ rationale = "Verb-object: walks from the root pipe; accumulators stay keyword."
param = "pipe"
rationale = "Verb-object: walks from the root pipe; visited set stays keyword."
+["pipelex/pipeline/blueprint_selection.py::collect_entry_pipe_refs"]
+param = "blueprints"
+rationale = "Derivation: collects the entry refs from the batch's blueprints; single operand."
+
["pipelex/pipeline/blueprint_selection.py::select_primary_blueprint"]
param = "blueprints"
rationale = "Verb-object: selects among the blueprints; single operand."
diff --git a/tests/integration/pipelex/cli/test_advisory_warning_channels.py b/tests/integration/pipelex/cli/test_advisory_warning_channels.py
new file mode 100644
index 000000000..4b5e91483
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_advisory_warning_channels.py
@@ -0,0 +1,307 @@
+"""Every whole-bundle validate channel carries the same advisory-warning families.
+
+The `warnings` array used to be assembled site by site, and the sites disagreed: the protocol path
+emitted the optionality and hint lints, the agent CLI, the builder ops and the bare CLI emitted the
+optionality lint alone. One composition point (`pipelex.pipeline.advisory_warnings`) now builds them
+all, and these pin that the channels agree — the agent-CLI JSON envelope, its markdown rendering,
+the builder-ops envelopes, and the bare CLI's yellow echo.
+
+`validate all` is the channel that reaches for the *library manager's* accumulated blueprints to
+know which pipes are entry pipes (it holds no `ValidateBundleResult` of its own), so its case here
+doubles as the proof that the `acquire_library` load path really does accumulate them.
+
+Two surfaces are deliberately absent. The builder's `validate_all` carries no `warnings` key at all
+and never did — see `wip/full-optional/deferred.md`. And the bare CLI's single-pipe `validate
+<PIPE_CODE>` echoes none of them: it makes no bundle-wide claim, and neither lint has anything to say
+about one pipe in isolation (the vacuous lint is scoped to entry pipes, the optionality lint
+aggregates across flows).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+import typer
+
+from pipelex.builder.operations import validate_ops
+from pipelex.cli.agent_cli.commands.validate._validate_core import validate_all_core, validate_bundle_core
+from pipelex.cli.commands.validate._validate_core import (
+ _validate_pipe_or_bundle, # pyright: ignore[reportPrivateUsage]
+ do_validate_all_libraries_and_dry_run,
+)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.pipeline.validation_render import format_validate_markdown
+from pipelex.validation_error_types import HintLintErrorType, PipeValidationErrorType
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+_VACUOUS_MTHDS = """
+domain = "advisory_channels"
+description = "Bundle whose main pipe demands a structure that declares nothing"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "Run with options"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+"""
+
+_VACUOUS_WITH_PENDING_SIGNATURE_MTHDS = """
+domain = "advisory_pending"
+description = "Bundle whose main pipe is vacuous and whose step is still a placeholder"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeSequence"
+description = "Run with options through a step that is not implemented yet"
+inputs = { opts = "RunOptions" }
+output = "Text"
+steps = [ { pipe = "step_sig", result = "out" } ]
+
+[pipe.step_sig]
+description = "Signature placeholder for the step."
+inputs = { opts = "RunOptions" }
+output = "Text"
+"""
+
+_ALL_FAMILIES_MTHDS = """
+domain = "advisory_families"
+description = "Bundle firing all three advisory families at once"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+hints = { emphasis = "strong" }
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeSequence"
+description = "Force a guaranteed slot, then use it"
+inputs = { opts = "RunOptions" }
+output = "Text"
+steps = [
+ { pipe = "draft", result = "draft_text" },
+ { pipe = "polish", result = "polished" },
+]
+
+[pipe.draft]
+type = "PipeLLM"
+description = "Draft from the options"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Draft with $opts"
+
+[pipe.polish]
+type = "PipeLLM"
+description = "Polish a guaranteed draft"
+inputs = { draft_text = "Text!" }
+output = "Text"
+prompt = "Polish $draft_text"
+"""
+
+
+def _write_bundle(*, contents: str, directory: Path) -> Path:
+ bundle_path = directory / "bundle.mthds"
+ bundle_path.write_text(contents, encoding="utf-8")
+ return bundle_path
+
+
+def vacuous_bundle_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as temp_dir:
+ directory = Path(temp_dir)
+ _write_bundle(contents=_VACUOUS_MTHDS, directory=directory)
+ yield directory
+
+
+def pending_signature_bundle_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as temp_dir:
+ path = Path(temp_dir)
+ (path / "bundle.mthds").write_text(_VACUOUS_WITH_PENDING_SIGNATURE_MTHDS)
+ yield path
+
+
+def all_families_bundle_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as temp_dir:
+ directory = Path(temp_dir)
+ _write_bundle(contents=_ALL_FAMILIES_MTHDS, directory=directory)
+ yield directory
+
+
[email protected](autouse=True)
+def restore_the_outer_library() -> Iterator[None]:
+ """Tear down whatever library a channel left current, and restore the one the test started in.
+
+ Two channels here hand teardown to a caller this test does not run: `validate_bundle` leaves its
+ validation library open on success (that is what lets the advisory lints resolve pipes), and
+ `do_validate_all_libraries_and_dry_run` leaves the loaded library current for the command that
+ owns `Pipelex` teardown. Called directly, both leak into whatever test runs next.
+ """
+ outer_library_id = get_current_library_id_or_none()
+ yield
+ leaked_library_id = get_current_library_id_or_none()
+ if leaked_library_id is not None and leaked_library_id != outer_library_id:
+ get_library_manager().teardown(library_id=leaked_library_id)
+ if outer_library_id is not None:
+ set_current_library(library_id=outer_library_id)
+ else:
+ clear_current_library()
+
+
+def _error_types(warnings: list[dict[str, Any]]) -> list[str]:
+ return [warning["error_type"] for warning in warnings]
+
+
+class TestAdvisoryWarningChannels:
+ # ---- `validate all`: entry pipes read off the library manager's accumulated blueprints ----
+
+ def test_agent_cli_validate_all_warns_on_the_main_pipe(self, vacuous_bundle_dir: Path) -> None:
+ result = asyncio.run(validate_all_core(library_dirs=[vacuous_bundle_dir]))
+
+ assert result["is_valid"] is True
+ vacuous = [warning for warning in result["warnings"] if warning["error_type"] == PipeValidationErrorType.INPUT_PRESENCE_VACUOUS]
+ assert len(vacuous) == 1
+ assert vacuous[0]["pipe_code"] == "run"
+ assert vacuous[0]["domain_code"] == "advisory_channels"
+ assert vacuous[0]["variable_names"] == ["opts"]
+
+ # ---- `validate bundle`: entry pipes read off the batch's blueprints -----------------------
+
+ def test_agent_cli_validate_bundle_envelope(self, vacuous_bundle_dir: Path) -> None:
+ result = asyncio.run(validate_bundle_core(bundle_path=vacuous_bundle_dir / "bundle.mthds", library_dirs=[vacuous_bundle_dir]))
+
+ assert result["is_valid"] is True
+ assert result["is_runnable"] is True
+ vacuous = [warning for warning in result["warnings"] if warning["error_type"] == PipeValidationErrorType.INPUT_PRESENCE_VACUOUS]
+ assert len(vacuous) == 1
+ assert "declares no required field" in vacuous[0]["message"]
+ # The locator is the pipe, never the concept: `concept_code` on a pipe_validation item is
+ # reserved for a reference that did not resolve, spelled as the author wrote it.
+ assert "concept_code" not in vacuous[0]
+
+ def test_builder_validate_bundle_content_twin(self) -> None:
+ result = asyncio.run(validate_ops.validate_bundle_content(mthds_contents=[_VACUOUS_MTHDS]))
+
+ assert result["is_valid"] is True
+ assert PipeValidationErrorType.INPUT_PRESENCE_VACUOUS in _error_types(result["warnings"])
+
+ def test_agent_cli_markdown_renders_the_warning_under_its_heading(self, vacuous_bundle_dir: Path) -> None:
+ """The markdown stream is the one an agent actually reads on `--format markdown` (the default)."""
+ result = asyncio.run(validate_bundle_core(bundle_path=vacuous_bundle_dir / "bundle.mthds", library_dirs=[vacuous_bundle_dir]))
+
+ markdown = format_validate_markdown(result)
+ assert "# Validation passed" in markdown
+ assert "## Warnings" in markdown
+ assert f"- **{PipeValidationErrorType.INPUT_PRESENCE_VACUOUS}** — Input 'opts' of pipe 'advisory_channels.run'" in markdown
+
+ # ---- All three families, one bundle, one fixed order, every channel ----------------------
+
+ def test_agent_cli_bundle_envelope_carries_all_three_families(self, all_families_bundle_dir: Path) -> None:
+ result = asyncio.run(validate_bundle_core(bundle_path=all_families_bundle_dir / "bundle.mthds", library_dirs=[all_families_bundle_dir]))
+
+ assert _error_types(result["warnings"]) == [
+ PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT,
+ PipeValidationErrorType.INPUT_PRESENCE_VACUOUS,
+ HintLintErrorType.HINT_UNKNOWN_KEY,
+ ]
+
+ def test_builder_bundle_file_envelope_carries_all_three_families(self, all_families_bundle_dir: Path) -> None:
+ result = asyncio.run(
+ validate_ops.validate_bundle_file(bundle_path=all_families_bundle_dir / "bundle.mthds", library_dirs=[all_families_bundle_dir])
+ )
+
+ assert _error_types(result["warnings"]) == [
+ PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT,
+ PipeValidationErrorType.INPUT_PRESENCE_VACUOUS,
+ HintLintErrorType.HINT_UNKNOWN_KEY,
+ ]
+
+ def test_agent_cli_markdown_lists_all_three_families_in_the_same_order(self, all_families_bundle_dir: Path) -> None:
+ result = asyncio.run(validate_bundle_core(bundle_path=all_families_bundle_dir / "bundle.mthds", library_dirs=[all_families_bundle_dir]))
+
+ markdown = format_validate_markdown(result)
+ assert "## Warnings (3)" in markdown
+ rendered = [line for line in markdown.splitlines() if line.startswith("- **")]
+ assert [line.split("**")[1] for line in rendered] == [
+ PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT,
+ PipeValidationErrorType.INPUT_PRESENCE_VACUOUS,
+ HintLintErrorType.HINT_UNKNOWN_KEY,
+ ]
+
+ def test_bare_cli_bundle_echo_carries_all_three_families(self, all_families_bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ """The bare CLI's yellow echo is the third presentation surface, and the one that used to
+ carry the optionality lint alone.
+ """
+ asyncio.run(_validate_pipe_or_bundle(bundle_path=all_families_bundle_dir / "bundle.mthds", library_dirs=[all_families_bundle_dir]))
+
+ echoed = [line for line in capsys.readouterr().out.splitlines() if line.startswith("Warning: ")]
+ assert len(echoed) == 3
+ assert "is declared with a force marker ('!')" in echoed[0]
+ assert "declares no required field" in echoed[1]
+ assert "is not defined by this version of the standard" in echoed[2]
+
+ def test_bare_cli_validate_all_echo_carries_the_entry_pipe_lint(self, vacuous_bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ do_validate_all_libraries_and_dry_run(library_dirs=[vacuous_bundle_dir])
+
+ echoed = [line for line in capsys.readouterr().out.splitlines() if line.startswith("Warning: ")]
+ assert len(echoed) == 1
+ assert "Input 'opts' of pipe 'advisory_channels.run'" in echoed[0]
+
+ def test_bare_cli_bundle_echo_survives_the_signature_gate(self, pending_signature_bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ """A pending placeholder must not swallow the advisories, on either bare-CLI path.
+
+ A half-implemented method is the state an author is most often in while building, and the
+ strict signature gate exits non-zero from it. `validate --all` has always echoed before that
+ gate; `validate bundle` used to echo after it, so the warnings were unreachable exactly when
+ they were most useful.
+ """
+ with pytest.raises(typer.Exit) as exit_info:
+ asyncio.run(
+ _validate_pipe_or_bundle(
+ bundle_path=pending_signature_bundle_dir / "bundle.mthds",
+ library_dirs=[pending_signature_bundle_dir],
+ )
+ )
+ assert exit_info.value.exit_code == 1
+
+ echoed = [line for line in capsys.readouterr().out.splitlines() if line.startswith("Warning: ")]
+ assert [line for line in echoed if "Input 'opts' of pipe 'advisory_pending.run'" in line]
+
+ def test_bare_cli_validate_all_echo_survives_the_signature_gate(
+ self, pending_signature_bundle_dir: Path, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ """The twin of the test above on the other bare-CLI path.
+
+ `validate --all` has echoed ahead of its gate since before this lint existed, but nothing
+ pinned it there — so a future edit could move it behind the gate on this path exactly as one
+ had on the other, and every test would stay green.
+ """
+ with pytest.raises(typer.Exit) as exit_info:
+ do_validate_all_libraries_and_dry_run(library_dirs=[pending_signature_bundle_dir])
+ assert exit_info.value.exit_code == 1
+
+ echoed = [line for line in capsys.readouterr().out.splitlines() if line.startswith("Warning: ")]
+ assert [line for line in echoed if "Input 'opts' of pipe 'advisory_pending.run'" in line]
diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.py
index ecd4406ce..06eb7b68b 100644
--- a/tests/integration/pipelex/pipeline/test_input_form.py
+++ b/tests/integration/pipelex/pipeline/test_input_form.py
@@ -452,6 +452,10 @@ class InputFormConstrainedPayload(StructuredContent):
tags: list[str] = Field(default_factory=list, description="PROBE_desc_reflected_tags")
+class InputFormFieldLessPayload(StructuredContent):
+ """A registered structure class declaring no field — a payload that demands nothing."""
+
+
class InputFormUnmappablePayload(StructuredContent):
"""A structure class whose field has no single blueprint shape — reflection must stay absent, never guess."""
@@ -470,12 +474,25 @@ structure = "InputFormConstrainedPayload"
description = "PROBE_desc_concept_Unmappable: class-backed by a class reflection cannot map"
structure = "InputFormUnmappablePayload"
+[concept.FieldLess]
+description = "PROBE_desc_concept_FieldLess: class-backed by a class declaring no field"
+structure = "InputFormFieldLessPayload"
+
[concept.Gadget]
description = "PROBE_desc_concept_Gadget"
[concept.Gadget.structure]
name = { type = "text", description = "PROBE_desc_field_gadget_name", required = true }
+[concept.EmptyStruct]
+description = "PROBE_desc_concept_EmptyStruct: an authored structure table holding no field"
+
+[concept.EmptyStruct.structure]
+
+[concept.RefinesEmpty]
+description = "PROBE_desc_concept_RefinesEmpty: refines the empty-structure base and adds nothing"
+refines = "EmptyStruct"
+
[pipe.remaining_natives]
type = "PipeCompose"
description = "The native concepts the probe bundle does not exercise as direct inputs"
@@ -483,15 +500,23 @@ inputs = { tai_in = "TextAndImages", search_result_in = "SearchResult", dynamic_
output = "Text"
template = "$tai_in $search_result_in $dynamic_in $anything_in $json_in"
+[pipe.empty_structures]
+type = "PipeCompose"
+description = "Concepts whose authored structure table is empty, directly and through a refines link"
+inputs = { empty_in = "EmptyStruct", refining_in = "RefinesEmpty" }
+output = "Text"
+template = "$empty_in $refining_in"
+
[pipe.edges]
type = "PipeLLM"
description = "Fixed-count-of-one multiplicity and class-backed reflection"
-inputs = { one = "Gadget[1]", constrained = "Constrained", unmappable = "Unmappable" }
+inputs = { one = "Gadget[1]", constrained = "Constrained", unmappable = "Unmappable", field_less = "FieldLess" }
output = "Text"
prompt = \"\"\"
@one
@constrained
@unmappable
+@field_less
\"\"\"
"""
@@ -504,6 +529,7 @@ class TestKindAssignmentTable:
registry = get_class_registry()
registry.register_class(InputFormConstrainedPayload)
registry.register_class(InputFormUnmappablePayload)
+ registry.register_class(InputFormFieldLessPayload)
result = await validate_bundle(mthds_contents=[_KIND_TABLE_MTHDS])
return build_input_form(result.pipes)
finally:
@@ -541,6 +567,26 @@ class TestKindAssignmentTable:
assert one.required is True
assert one.gating is True
+ async def test_an_authored_but_empty_structure_table_is_an_object_with_no_fields(self, load_empty_library: Callable[[], str]) -> None:
+ """The engine branches on `structure is not None` (`ConceptFactory`), so an empty `[concept.X.structure]`
+ table is backed by a field-less structured model whose schema is `{"type": "object", "properties": {}}`.
+ The descriptor states that same fact: testing truthiness instead would report the concept as `prose`
+ with a `native.Text` refinement link nobody authored, contradicting the schema beside it.
+ """
+ input_form = await self._derive_kind_table(load_empty_library)
+ empties = input_form["input_form_kinds.empty_structures"]
+
+ empty = _field_by_name(empties, "empty_in")
+ assert empty.kind == FieldKind.OBJECT
+ assert empty.fields == []
+ assert empty.refines is None, "Nothing was authored to refine, and nothing is invented"
+ assert empty.model_dump()["fields"] == [], "An empty `fields` is applicable, so the wire keeps it"
+
+ refining = _field_by_name(empties, "refining_in")
+ assert refining.kind == FieldKind.OBJECT, "The dict structure sits one link up the chain, and still decides"
+ assert refining.fields == []
+ assert refining.refines == ["input_form_kinds.EmptyStruct"], "The authored chain, with nothing appended to it"
+
async def test_custom_class_reflects_to_object_with_constraints(self, load_empty_library: Callable[[], str]) -> None:
"""A hand-written structure class is reflected field by field, with the constraints the engine states."""
input_form = await self._derive_kind_table(load_empty_library)
@@ -589,6 +635,22 @@ class TestKindAssignmentTable:
assert tags.required is False, "A default_factory makes the field not required"
assert tags.default_value is None, "A default_factory has no reportable value — no default_value is fabricated"
+ async def test_a_field_less_class_is_an_object_with_no_fields(self, load_empty_library: Callable[[], str]) -> None:
+ """`reflect_structure_class` answers `None` for two different things, and only one is opaque.
+
+ A class declaring no field states a payload that demands nothing — the class-backed twin of an
+ empty authored structure table — so the form reports `object` with an empty `fields` list. A
+ field reflection could not map stays `unknown`, which the sibling case below pins.
+ """
+ input_form = await self._derive_kind_table(load_empty_library)
+ field_less = _field_by_name(input_form["input_form_kinds.edges"], "field_less")
+
+ assert field_less.kind == FieldKind.OBJECT
+ assert field_less.fields == []
+ assert field_less.concept_ref == "input_form_kinds.FieldLess"
+ assert field_less.required is True
+ assert field_less.gating is True
+
async def test_unmappable_class_falls_back_to_unknown(self, load_empty_library: Callable[[], str]) -> None:
"""Reflection is faithful-or-absent: a class with an unmappable field yields `unknown`, with identity kept."""
input_form = await self._derive_kind_table(load_empty_library)
diff --git a/tests/integration/pipelex/pipeline/test_vacuous_presence_lint.py b/tests/integration/pipelex/pipeline/test_vacuous_presence_lint.py
new file mode 100644
index 000000000..1e1058216
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_vacuous_presence_lint.py
@@ -0,0 +1,291 @@
+"""The vacuous-presence lint on the protocol `validate` path, over real bundles.
+
+The unit decision table (`tests/unit/pipelex/pipeline/test_vacuous_presence_warnings.py`) pins the
+rule over hand-built descriptors. These pin the half the unit table cannot see: that a bundle an
+author actually writes derives the descriptor the lint fires on, that the entry-pipe scope really
+does follow the declared `main_pipe`, and that a warning never touches the verdict.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from pydantic import Field
+
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pipelex.interpreter_hub import clear_current_library
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.system.registries.class_registry_access import get_class_registry
+from pipelex.validation_error_types import HintLintErrorType, PipeValidationErrorType
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+ from pipelex.base_exceptions import ValidationErrorItem
+
+_ENTRY_PIPE_MTHDS = """
+domain = "vacuous_entry"
+description = "Entry pipe demanding an all-optional structure, with a sibling that does the same"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+depth = { type = "integer", description = "How deep to go" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+
+[pipe.helper]
+type = "PipeLLM"
+description = "A sibling with the very same input shape, reached by nothing"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Help with $opts"
+"""
+
+_OPTIONAL_SLOT_MTHDS = """
+domain = "vacuous_optional"
+description = "The same shape with the slot marked optional"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe, tolerating an absent slot"
+inputs = { opts = "RunOptions?" }
+output = "Text"
+prompt = "Run{% if opts %} with $opts{% endif %}"
+"""
+
+_REQUIRED_FIELD_MTHDS = """
+domain = "vacuous_required"
+description = "The same shape with one required field"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use", required = true }
+depth = { type = "integer", description = "How deep to go" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+"""
+
+_NO_MAIN_PIPE_MTHDS = """
+domain = "vacuous_no_main"
+description = "The warnable shape in a bundle that declares no main_pipe"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "A pipe no bundle declares as its entry point"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+"""
+
+_EMPTY_STRUCTURE_MTHDS = """
+domain = "vacuous_empty"
+description = "Entry pipe demanding a concept whose authored structure table holds no field"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+
+[concept.RunOptions.structure]
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+"""
+
+_CLASS_BACKED_MTHDS = """
+domain = "vacuous_class"
+description = "Entry pipe demanding a class-backed concept whose fields all carry defaults"
+main_pipe = "run"
+
+[concept.Settings]
+description = "Settings backed by a hand-written class"
+structure = "VacuousAllDefaultedPayload"
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { settings = "Settings" }
+output = "Text"
+prompt = "Run with $settings"
+"""
+
+_FIELD_LESS_CLASS_MTHDS = """
+domain = "vacuous_field_less"
+description = "Entry pipe demanding a class-backed concept whose class declares no field"
+main_pipe = "run"
+
+[concept.Settings]
+description = "Settings backed by a class with no field"
+structure = "VacuousFieldLessPayload"
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { settings = "Settings" }
+output = "Text"
+prompt = "Run with $settings"
+"""
+
+_HINTED_MTHDS = """
+domain = "vacuous_hinted"
+description = "The warnable shape beside a warnable hint"
+main_pipe = "run"
+
+[concept.RunOptions]
+description = "Options for the run"
+hints = { emphasis = "strong" }
+
+[concept.RunOptions.structure]
+tone = { type = "text", description = "The tone to use" }
+
+[pipe.run]
+type = "PipeLLM"
+description = "The entry pipe"
+inputs = { opts = "RunOptions" }
+output = "Text"
+prompt = "Run with $opts"
+"""
+
+
+class VacuousAllDefaultedPayload(StructuredContent):
+ """A hand-written structure class whose every field carries a default — all-optional by reflection."""
+
+ tone: str = Field(default="neutral", description="The tone to use")
+ depth: int | None = Field(default=None, description="How deep to go")
+
+
+class VacuousFieldLessPayload(StructuredContent):
+ """A hand-written structure class declaring no field at all — the empty object satisfies it."""
+
+
+def _vacuous(warnings: list[ValidationErrorItem]) -> list[ValidationErrorItem]:
+ return [warning for warning in warnings if warning.error_type == PipeValidationErrorType.INPUT_PRESENCE_VACUOUS]
+
+
[email protected](loop_scope="class")
+class TestVacuousPresenceLint:
+ async def _warnings(self, *, mthds: str, load_empty_library: Callable[[], str]) -> list[ValidationErrorItem]:
+ load_empty_library()
+ try:
+ report = await PipelexMTHDSProtocol().validate(mthds_contents=[mthds])
+ assert report.is_runnable is True, "An advisory warning must never touch the verdict"
+ return report.warnings
+ finally:
+ clear_current_library()
+
+ async def test_entry_pipe_warns_and_the_report_stays_valid_and_runnable(self, load_empty_library: Callable[[], str]) -> None:
+ warnings = await self._warnings(mthds=_ENTRY_PIPE_MTHDS, load_empty_library=load_empty_library)
+
+ vacuous = _vacuous(warnings)
+ assert len(vacuous) == 1, "Only the declared main_pipe is linted, not its identically-shaped sibling"
+ assert vacuous[0].pipe_code == "run"
+ assert vacuous[0].domain_code == "vacuous_entry"
+ assert vacuous[0].variable_names == ["opts"]
+ assert "vacuous_entry.RunOptions" in vacuous[0].message
+
+ async def test_the_same_shape_on_a_non_entry_pipe_is_silent(self, load_empty_library: Callable[[], str]) -> None:
+ """`helper` declares the very same input as `run`, in the same bundle. Only `run` is warned about."""
+ warnings = await self._warnings(mthds=_ENTRY_PIPE_MTHDS, load_empty_library=load_empty_library)
+
+ assert [warning.pipe_code for warning in _vacuous(warnings)] == ["run"]
+
+ async def test_an_optional_slot_is_silent(self, load_empty_library: Callable[[], str]) -> None:
+ warnings = await self._warnings(mthds=_OPTIONAL_SLOT_MTHDS, load_empty_library=load_empty_library)
+
+ assert _vacuous(warnings) == []
+
+ async def test_one_required_field_silences_the_lint(self, load_empty_library: Callable[[], str]) -> None:
+ warnings = await self._warnings(mthds=_REQUIRED_FIELD_MTHDS, load_empty_library=load_empty_library)
+
+ assert _vacuous(warnings) == []
+
+ async def test_a_bundle_with_no_main_pipe_is_not_linted(self, load_empty_library: Callable[[], str]) -> None:
+ warnings = await self._warnings(mthds=_NO_MAIN_PIPE_MTHDS, load_empty_library=load_empty_library)
+
+ assert _vacuous(warnings) == []
+
+ async def test_an_empty_structure_table_warns_with_the_field_less_wording(self, load_empty_library: Callable[[], str]) -> None:
+ """The design's second row: a concept declaring no field at all, which the empty object satisfies.
+
+ It is reachable because the deriver branches on `structure is not None` the way `ConceptFactory`
+ does — the truthiness test it used to run reported such a concept as `prose`, which this lint
+ never looks at, so the wording below was unreachable from any bundle an author can write.
+ """
+ warnings = await self._warnings(mthds=_EMPTY_STRUCTURE_MTHDS, load_empty_library=load_empty_library)
+
+ vacuous = _vacuous(warnings)
+ assert len(vacuous) == 1
+ assert vacuous[0].variable_names == ["opts"]
+ assert "declares no field at all" in vacuous[0].message
+ assert "give 'vacuous_empty.RunOptions' a required field" in vacuous[0].message
+
+ async def test_a_class_backed_concept_with_all_defaulted_fields_warns(self, load_empty_library: Callable[[], str]) -> None:
+ """The lint reads the descriptor, so class-backed reflection is covered for free: a pydantic
+ class whose every field carries a default demands nothing, exactly as an all-optional
+ authored structure does.
+ """
+ get_class_registry().register_class(VacuousAllDefaultedPayload)
+ warnings = await self._warnings(mthds=_CLASS_BACKED_MTHDS, load_empty_library=load_empty_library)
+
+ vacuous = _vacuous(warnings)
+ assert len(vacuous) == 1
+ assert vacuous[0].variable_names == ["settings"]
+ assert "vacuous_class.Settings" in vacuous[0].message
+
+ async def test_a_field_less_class_backed_concept_warns_with_the_field_less_wording(self, load_empty_library: Callable[[], str]) -> None:
+ """A registered class declaring no field demands nothing, exactly as an empty structure table does.
+
+ The descriptor used to call such a concept `unknown` — the kind reserved for a payload it
+ genuinely cannot read — which the object-only guard then silenced. Zero fields is a reading,
+ not a failure to read, so the form says `object` and the lint has something honest to say.
+ """
+ get_class_registry().register_class(VacuousFieldLessPayload)
+ warnings = await self._warnings(mthds=_FIELD_LESS_CLASS_MTHDS, load_empty_library=load_empty_library)
+
+ vacuous = _vacuous(warnings)
+ assert len(vacuous) == 1
+ assert vacuous[0].variable_names == ["settings"]
+ assert "declares no field at all" in vacuous[0].message
+ assert "give 'vacuous_field_less.Settings' a required field" in vacuous[0].message
+
+ async def test_the_hint_lint_still_rides_beside_it(self, load_empty_library: Callable[[], str]) -> None:
+ warnings = await self._warnings(mthds=_HINTED_MTHDS, load_empty_library=load_empty_library)
+
+ assert [warning.error_type for warning in warnings] == [
+ PipeValidationErrorType.INPUT_PRESENCE_VACUOUS,
+ HintLintErrorType.HINT_UNKNOWN_KEY,
+ ]
diff --git a/tests/unit/pipelex/pipeline/test_hint_warnings.py b/tests/unit/pipelex/pipeline/test_hint_warnings.py
index 623629077..8091e8a3e 100644
--- a/tests/unit/pipelex/pipeline/test_hint_warnings.py
+++ b/tests/unit/pipelex/pipeline/test_hint_warnings.py
@@ -11,7 +11,7 @@ from pipelex.libraries.library_crate import LibraryCrate
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipeBlueprintUnion
from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
-from pipelex.pipeline.hint_warnings import build_hint_warnings
+from pipelex.pipeline.hint_warnings import MAX_AUTHORED_TOKEN_LENGTH, MAX_HINT_FINDINGS_PER_SITE, build_hint_warnings
from pipelex.validation_error_types import HintLintErrorType
@@ -143,6 +143,60 @@ class TestHintLintFindings:
assert warning.pipe_code == "write"
assert warning.variable_names == ["amount"]
+ # Payload bounds. Authored hint content is interpolated raw into `message`, and one finding
+ # fires per unknown key — so a site naming many keys, or one very long value, could inflate
+ # the warning payload of a channel an author invokes casually. Both are bounded.
+ def test_undefined_keys_beyond_the_cap_collapse_into_one_tail(self):
+ hints = {f"key_{index:02d}": "value" for index in range(MAX_HINT_FINDINGS_PER_SITE + 4)}
+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints=hints)}))
+
+ assert len(warnings) == MAX_HINT_FINDINGS_PER_SITE + 1
+ assert all(warning.error_type == HintLintErrorType.HINT_UNKNOWN_KEY for warning in warnings)
+ assert warnings[-1].message.startswith("...and 4 more hint key(s) on concept 'docs.Essay'")
+
+ def test_exactly_the_cap_reports_every_key_with_no_tail(self):
+ hints = {f"key_{index:02d}": "value" for index in range(MAX_HINT_FINDINGS_PER_SITE)}
+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints=hints)}))
+
+ assert len(warnings) == MAX_HINT_FINDINGS_PER_SITE
+ assert not any("more hint key(s)" in warning.message for warning in warnings)
+
+ def test_the_cap_is_per_site_not_per_crate(self):
+ hints = {f"key_{index:02d}": "value" for index in range(MAX_HINT_FINDINGS_PER_SITE)}
+ warnings = _lint(
+ _crate(
+ {
+ "docs.Essay": ConceptBlueprint(description="an essay", hints=hints),
+ "docs.Memo": ConceptBlueprint(description="a memo", hints=hints),
+ }
+ )
+ )
+ assert len(warnings) == 2 * MAX_HINT_FINDINGS_PER_SITE
+
+ def test_a_long_authored_key_is_elided_in_the_message(self):
+ long_key = "k" * (MAX_AUTHORED_TOKEN_LENGTH + 50)
+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={long_key: "value"})}))
+
+ assert len(warnings) == 1
+ assert long_key not in warnings[0].message
+ assert f"'{'k' * MAX_AUTHORED_TOKEN_LENGTH}...'" in warnings[0].message
+
+ def test_a_long_authored_intent_value_is_elided_in_the_message(self):
+ long_word = "w" * (MAX_AUTHORED_TOKEN_LENGTH + 50)
+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={"intent": long_word})}))
+
+ assert len(warnings) == 1
+ assert warnings[0].error_type == HintLintErrorType.HINT_UNKNOWN_INTENT
+ assert long_word not in warnings[0].message
+ assert f"'{'w' * MAX_AUTHORED_TOKEN_LENGTH}...'" in warnings[0].message
+
+ def test_a_token_at_the_length_limit_is_quoted_whole(self):
+ exact_key = "k" * MAX_AUTHORED_TOKEN_LENGTH
+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={exact_key: "value"})}))
+
+ assert f"'{exact_key}'" in warnings[0].message
+ assert "..." not in warnings[0].message
+
class TestHintLintSilence:
def test_applicable_hints_produce_no_warning(self):
diff --git a/tests/unit/pipelex/pipeline/test_optionality_warnings.py b/tests/unit/pipelex/pipeline/test_optionality_warnings.py
new file mode 100644
index 000000000..b98f02ee2
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_optionality_warnings.py
@@ -0,0 +1,39 @@
+"""The useless-`!` lint's item shape, over hand-built taint analyses.
+
+`build_optionality_warnings` is pure over the controllers' analyses, so the projection it performs —
+aggregating observations per (pipe, variable) and stamping a locator on each item — needs no library
+window. The cross-flow aggregation itself is pinned over real flows in
+`tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py`; what is pinned here is
+the half that walk cannot vary cheaply: how a qualified pipe ref becomes `domain_code` + `pipe_code`.
+"""
+
+from pipelex.pipe_controllers.absence_taint import ForceConsumptionInfo, SequenceTaintAnalysis
+from pipelex.pipeline.optionality_warnings import build_optionality_warnings
+from pipelex.validation_error_types import PipeValidationErrorType
+
+
+def _redundant_analysis(*, pipe_ref: str) -> SequenceTaintAnalysis:
+ """One observation of a `!` on a guaranteed slot — the shape the lint warns about."""
+ return SequenceTaintAnalysis(
+ liftable_steps=(),
+ output_taint=None,
+ force_consumptions=(ForceConsumptionInfo(within_pipe_ref=f"{pipe_ref}_flow", pipe_ref=pipe_ref, variable_name="a_out", is_asserting=False),),
+ )
+
+
+class TestOptionalityWarningLocator:
+ def test_a_single_segment_domain_splits_at_its_only_dot(self):
+ warnings = build_optionality_warnings([_redundant_analysis(pipe_ref="scoring.compute")])
+
+ assert len(warnings) == 1
+ assert warnings[0].error_type == PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ assert warnings[0].domain_code == "scoring"
+ assert warnings[0].pipe_code == "compute"
+
+ def test_a_hierarchical_domain_keeps_its_full_path_in_the_locator(self):
+ """A domain is a dotted path, so the ref splits at its LAST dot, not its first."""
+ warnings = build_optionality_warnings([_redundant_analysis(pipe_ref="legal.contracts.compute")])
+
+ assert len(warnings) == 1
+ assert warnings[0].domain_code == "legal.contracts"
+ assert warnings[0].pipe_code == "compute"
diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
index 3050adfb7..4a9045ef9 100644
--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
@@ -60,7 +60,9 @@ class TestRunnerValidatePlumbing:
# without a real loaded library. Their output shaping is pinned in test_validation_report.py
# and the integration test_protocol_validate.py — this module asserts only the plumbing.
mocker.patch("pipelex.pipeline.validate_in_process.build_pipe_io_contracts", return_value={})
+ mocker.patch("pipelex.pipeline.validate_in_process.qualify_current_library_crate")
mocker.patch("pipelex.pipeline.validate_in_process.build_input_form", return_value={})
+ mocker.patch("pipelex.pipeline.validate_in_process.build_advisory_warnings", return_value=[])
mocker.patch("pipelex.pipeline.validate_in_process.select_primary_blueprint")
mocker.patch("pipelex.pipeline.validate_in_process.best_effort_graph_spec", new=mocker.AsyncMock(return_value=None))
mocker.patch("pipelex.pipeline.validate_in_process.build_validation_report")
diff --git a/tests/unit/pipelex/pipeline/test_vacuous_presence_warnings.py b/tests/unit/pipelex/pipeline/test_vacuous_presence_warnings.py
new file mode 100644
index 000000000..97d6e7190
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_vacuous_presence_warnings.py
@@ -0,0 +1,201 @@
+"""The vacuous-presence lint's decision table, over hand-built input-form descriptors.
+
+One case per row of the design's rule table (`wip/full-optional/design.md` §3): a gating slot whose
+concept declares no required field warns; everything else is silent, and each silence is asserted
+here rather than assumed. The descriptors are built by hand — the lint is pure over them, so the
+table needs no library window and no crate.
+"""
+
+import pytest
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.pipeline.input_form import FieldKind, InputFormField, PipeInputFormDescriptor
+from pipelex.pipeline.vacuous_presence_warnings import build_vacuous_presence_warnings
+
+ENTRY_PIPE_REF = "demo.run"
+OPTIONS_CONCEPT_REF = "demo.RunOptions"
+
+
+def _nested(*, name: str, required: bool) -> InputFormField:
+ """A structure field inside an object node (no slot facts: no presence, no gating)."""
+ return InputFormField(kind=FieldKind.TEXT, name=name, required=required)
+
+
+def _object_slot(
+ *,
+ name: str = "opts",
+ nested_fields: list[InputFormField] | None = None,
+ presence: PresenceMarker = PresenceMarker.PLAIN,
+ required: bool = True,
+ gating: bool | None = True,
+ concept_ref: str | None = OPTIONS_CONCEPT_REF,
+) -> InputFormField:
+ """A top-level object slot, defaulting to the all-optional shape the lint fires on."""
+ return InputFormField(
+ kind=FieldKind.OBJECT,
+ name=name,
+ concept_ref=concept_ref,
+ required=required,
+ presence=presence,
+ gating=gating,
+ fields=[_nested(name="tone", required=False)] if nested_fields is None else nested_fields,
+ )
+
+
+def _object_item() -> InputFormField:
+ """The all-optional object as a list's `item` node: a concept node, so no slot facts."""
+ return InputFormField(
+ kind=FieldKind.OBJECT,
+ name="opts",
+ concept_ref=OPTIONS_CONCEPT_REF,
+ required=True,
+ fields=[_nested(name="tone", required=False)],
+ )
+
+
+def _lint(*, slots: list[InputFormField], pipe_ref: str = ENTRY_PIPE_REF, entry_pipe_refs: list[str] | None = None) -> list[ValidationErrorItem]:
+ return build_vacuous_presence_warnings(
+ input_form={pipe_ref: PipeInputFormDescriptor(fields=slots)},
+ entry_pipe_refs=entry_pipe_refs if entry_pipe_refs is not None else [ENTRY_PIPE_REF],
+ )
+
+
+class TestVacuousPresenceWarnings:
+ # ---- Fires ------------------------------------------------------------------------------
+
+ def test_all_optional_object_warns(self):
+ warnings = _lint(slots=[_object_slot()])
+ assert len(warnings) == 1
+ assert "declares no required field" in warnings[0].message
+ assert "an empty object satisfies it" in warnings[0].message
+
+ def test_field_less_object_warns_with_the_variant_wording(self):
+ warnings = _lint(slots=[_object_slot(nested_fields=[])])
+ assert len(warnings) == 1
+ message = warnings[0].message
+ assert "declares no field at all" in message
+ assert "an empty object satisfies it" in message
+ assert f"give '{OPTIONS_CONCEPT_REF}' a required field" in message
+
+ def test_plain_input_message_names_the_absent_marker_and_both_remedies(self):
+ message = _lint(slots=[_object_slot()])[0].message
+ assert f"Input 'opts' of pipe '{ENTRY_PIPE_REF}' must be supplied (declared without '?')" in message
+ assert f'`opts = "{OPTIONS_CONCEPT_REF}?"`' in message
+ assert f"make at least one field of '{OPTIONS_CONCEPT_REF}' required" in message
+
+ def test_force_input_warns_and_names_the_marker(self):
+ warnings = _lint(slots=[_object_slot(presence=PresenceMarker.FORCE)])
+ assert len(warnings) == 1
+ assert "declared with a force marker '!'" in warnings[0].message
+
+ def test_item_shape_carries_the_pipe_locator_and_no_concept_code(self):
+ warning = _lint(slots=[_object_slot()])[0]
+ assert warning.category == ValidationErrorCategory.PIPE_VALIDATION
+ assert warning.error_type == "input_presence_vacuous"
+ assert warning.pipe_code == "run"
+ assert warning.domain_code == "demo"
+ assert warning.variable_names == ["opts"]
+ assert warning.concept_code is None
+
+ def test_a_hierarchical_domain_keeps_its_full_path_in_the_locator(self):
+ """A domain is a dotted path, so the ref splits at its LAST dot, not its first."""
+ warning = _lint(slots=[_object_slot()], pipe_ref="legal.contracts.run", entry_pipe_refs=["legal.contracts.run"])[0]
+
+ assert warning.domain_code == "legal.contracts"
+ assert warning.pipe_code == "run"
+
+ # ---- Silent -----------------------------------------------------------------------------
+
+ def test_one_required_field_is_silent(self):
+ slot = _object_slot(nested_fields=[_nested(name="tone", required=False), _nested(name="topic", required=True)])
+ assert _lint(slots=[slot]) == []
+
+ def test_optional_presence_is_silent(self):
+ assert _lint(slots=[_object_slot(required=False, presence=PresenceMarker.OPTIONAL, gating=False)]) == []
+
+ def test_a_non_gating_object_slot_is_silent_even_when_required(self):
+ """The lint keys on `gating` — the descriptor's stated "block Run until this has content" —
+ never on `required`. The two coincide on every object node the deriver builds today, so this
+ is the only case that can tell the two reads apart, and it is the rule the design states.
+ """
+ assert _lint(slots=[_object_slot(required=True, gating=False)]) == []
+
+ def test_variable_multiplicity_list_is_silent(self):
+ """`Concept[]` never gates by the descriptor's own rule — `[]` is its legitimate value."""
+ slot = InputFormField(
+ kind=FieldKind.LIST,
+ name="opts",
+ concept_ref=OPTIONS_CONCEPT_REF,
+ required=True,
+ presence=PresenceMarker.PLAIN,
+ gating=False,
+ item=_object_item(),
+ )
+ assert _lint(slots=[slot]) == []
+
+ def test_fixed_count_list_is_silent(self):
+ """`Concept[N]` gates, but the vacuity question is per item — deferred (design §7)."""
+ slot = InputFormField(
+ kind=FieldKind.LIST,
+ name="opts",
+ concept_ref=OPTIONS_CONCEPT_REF,
+ required=True,
+ presence=PresenceMarker.PLAIN,
+ gating=True,
+ item=_object_item(),
+ item_count=2,
+ )
+ assert _lint(slots=[slot]) == []
+
+ @pytest.mark.parametrize(
+ "slot",
+ [
+ InputFormField(kind=FieldKind.TEXT, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ InputFormField(kind=FieldKind.PROSE, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ InputFormField(kind=FieldKind.NUMBER, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True, integer=False),
+ InputFormField(kind=FieldKind.BOOLEAN, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ InputFormField(kind=FieldKind.DATE, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True, datetime_flag=False),
+ InputFormField(kind=FieldKind.ENUM, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True, choices=["a", "b"]),
+ InputFormField(kind=FieldKind.DOCUMENT, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ InputFormField(kind=FieldKind.IMAGE, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ InputFormField(kind=FieldKind.UNKNOWN, name="opts", required=True, presence=PresenceMarker.PLAIN, gating=True),
+ ],
+ ids=["text", "prose", "number", "boolean", "date", "enum", "document", "image", "unknown"],
+ )
+ def test_non_object_kinds_are_silent(self, slot: InputFormField):
+ assert _lint(slots=[slot]) == []
+
+ def test_a_non_entry_pipe_with_the_warning_shape_is_silent(self):
+ assert _lint(slots=[_object_slot()], pipe_ref="demo.helper") == []
+
+ def test_no_entry_pipes_means_no_lint(self):
+ assert _lint(slots=[_object_slot()], entry_pipe_refs=[]) == []
+
+ def test_an_entry_ref_absent_from_the_input_form_is_silent(self):
+ assert build_vacuous_presence_warnings(input_form={}, entry_pipe_refs=[ENTRY_PIPE_REF]) == []
+
+ def test_a_concept_less_object_node_is_silent(self):
+ """With no `concept_ref` there is no concept to name, hence no honest message to state."""
+ assert _lint(slots=[_object_slot(concept_ref=None)]) == []
+
+ # ---- Ordering ---------------------------------------------------------------------------
+
+ def test_output_is_by_entry_pipe_ref_then_authored_slot_order(self):
+ input_form = {
+ "demo.zeta": PipeInputFormDescriptor(fields=[_object_slot(name="zulu"), _object_slot(name="alpha")]),
+ "demo.alpha": PipeInputFormDescriptor(fields=[_object_slot(name="yankee")]),
+ }
+ warnings = build_vacuous_presence_warnings(input_form=input_form, entry_pipe_refs=["demo.zeta", "demo.alpha"])
+ assert [(warning.pipe_code, warning.variable_names) for warning in warnings] == [
+ ("alpha", ["yankee"]),
+ ("zeta", ["zulu"]),
+ ("zeta", ["alpha"]),
+ ]
+
+ def test_a_repeated_entry_ref_warns_once(self):
+ warnings = build_vacuous_presence_warnings(
+ input_form={ENTRY_PIPE_REF: PipeInputFormDescriptor(fields=[_object_slot()])},
+ entry_pipe_refs=[ENTRY_PIPE_REF, ENTRY_PIPE_REF],
+ )
+ assert len(warnings) == 1
diff --git a/wip/S2-DONE.md b/wip/S2-DONE.md
new file mode 100644
index 000000000..2554ab1e7
--- /dev/null
+++ b/wip/S2-DONE.md
@@ -0,0 +1,107 @@
+# S2 — Enrich: implementation tracker
+
+Seeded from [`wip/enrich/design.md`](wip/enrich/design.md) §7 (the design stays authoritative for rationale; this file tracks live progress). Milestone branch: `feature/Enrich`.
+
+## Decisions ratified (Phase 0, 2026-08-23, by Louis)
+
+1. **E3 — reject the pair.** A structure field declaring both `required = true` and a `default_value` is a validation error (breaking; mthds spec sentence via inbox; the sole fixture instance moves to `rejected/`).
+2. **E5/E9 — replace, not add.** Input contract `presence: "plain" | "optional" | "force"` **replaces** `optional`; `multiplicity` goes three-valued (`single`/`variable`/`fixed`) with `item_count` exactly when `fixed`, on input and output contracts. Output keeps its two-valued `optional`. Breaking protocol change, spec-first, rides the release cascade.
+3. **Reflected defaults are authored facts.** A pydantic default on a reflected class field reports `required: false` + its `default_value` in the descriptor; `field_info.is_required()` is the single source of truth.
+
+## Phase 0 — ratify and sweep
+
+- [x] Decisions §6 confirmed by Louis (see above)
+- [x] Sweep at head: hopeful extra keys in structure-field tables across fixtures, corpus entries, and cookbook-adjacent test data (E7 fallout list)
+- [x] Sweep at head: `required = true` + `default_value` pairs across the same surfaces (E3 fallout list)
+- [x] Inventory captures that pin emitted schema bytes (codegen/validate parity corpora, conformance captures, characterization tests) so Phase 2 re-baselines are deliberate
+- [x] Record the fixture-fallout list for Phases 1–2 below
+
+### Phase 0 findings
+
+- **Structure-field sweep (2026-08-23, at head of `feature/Enrich`):** parsed every `.mthds`/concept-bearing `.toml` under this worktree, `pipelex-cookbook`, and `pipelex-starter-python`. The ONLY unknown-key carrier is the probe bundle's `constrained_count` (`tests/data/input_semantics/probe_bundle.mthds:61` — extras `minimum`, `maximum`, `examples`, `unit`), and the ONLY `required`+`default_value` pair is the probe bundle's `titled_default` (`probe_bundle.mthds:30`). No fallout anywhere else; both fields are handled by the design's own plan (extras: E7 flip keeps them as deliberate rejected-case material; `titled_default` moves to a `rejected/` fixture in Phase 4).
+- **Schema-byte capture inventory (very thorough sweep):** NOTHING under `tests/` pins schema bytes — every schema assertion is key-presence or single-value, so Phase 2's render changes are test-green without re-baselining (no snapshot framework exists in the repo). The only committed full-schema payloads are the S1 audit captures under `wip/input-semantics/probe/` (hop3 raw schemas, hop4 renders, hop5 contracts), re-baselined by one command: `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`. Hand edits Phase 2 owes: `docs/tools/cli/build/output.md:161-239` (its example `--format schema` output shows the class-name `title`, no top-level `description`, and a `MyType[5]` array with no `minItems`/`maxItems` — falsified by all three enrichments). Digest surfaces checked (migration fingerprints, crate fingerprints, codegen stamps): none hashes rendered schema. Conformance (sibling repo) pins nothing schema-byte-wise; it becomes relevant only at Phase 3. Natural home for new seam unit tests: `tests/unit/pipelex/core/concepts/test_concept_representation_generator.py`; for integration assertions: `tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py`.
+
+## Phase 1 — loudness (E7, E8)
+
+- [x] E7: `extra="forbid"` on `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`) — field-table *keys* strict; hint *content* stays lenient (unknown hint keys still warn + preserve)
+- [x] E8: builder writes `default_value`, not `default` (`pipelex/builder/operations/concept_ops.py`)
+- [x] E8: write-then-validate round-trip test for builder-authored defaults (`tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py` — two existing assertions had pinned the buggy `default` key and were fixed too)
+- [x] Regenerate `mthds_schema.json` — `ConceptStructureBlueprint` now carries `additionalProperties: false` (schema is generated + gitignored; downstream copies sync at release per the filed inbox item)
+- [x] Apply Phase 0 fixture fallout: probe bundle's `constrained_count` lost its hopeful extras (its description string kept byte-identical — it is hashed by the fingerprint pins); the extras live on in the new `tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid`
+- [x] Unit tests: forbid rejection + hint leniency (`tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py`)
+- [x] H2 fingerprint invariant check: `test_fingerprint_pins.py` green with UNCHANGED pins
+- [x] Changelog (Unreleased): E7 breaking (Changed) + E8 fix (Fixed)
+- [x] Deliver + remove inbox item `../wip/inbox/2026-08-21-pipelex-builder-default-key-dropped.md` (deleted; fix, round trip, and forbid all delivered)
+
+**Checkpoint 1** — authoring loop honest, nothing wire-visible changed yet.
+
+- [x] Checkpoint 1: tracker updated, `make agent-check` green, targeted tests green (concepts + builder + fingerprint pins + input-form integration)
+
+### Checkpoint 1 state (for cold start)
+
+Decisions all ratified (§ above). Phase 1 delivered E7+E8 entirely inside: `concept_structure_blueprint.py` (forbid), `concept_ops.py` (key fix), probe bundle + new rejected fixture, three test modules touched. Note for Phase 4: removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `tests/unit/pipelex/libraries/test_fingerprint_pins.py` — that is a legitimate fixture-content change, not a model leak; the pins must be recomputed then, against the test docstring's usual advice, or the pin test moved onto a stable fixture. The check-mthds PostToolUse hook flags the probe bundle with a stale bundled schema — `plxt lint` with the regenerated `derived/mthds_schema.json` is the authority and passes.
+
+## Phase 2 — schema enrichment (E6, E1-title, E4)
+
+- [x] E6: `_render_schema_representation` (`pipelex/core/concepts/concept.py`) injects the concept's authored description as top-level `description` (no-op for generated classes; authored fact for class-backed; pinned native blueprint description for native direct inputs)
+- [x] E6: docstrings on native content classes lacking one (`TextContent`, `ImageContent`, `DocumentContent`, `PageContent`, `NumberContent`, `HtmlContent`, `YesNoContent`) — pinned description text verbatim; the pinned-consistency test (`tests/unit/pipelex/codegen/test_native_expansion.py`) compares factory descriptions, not docstrings, so no interference
+- [x] E1: top-level `title` becomes the concept ref at the same render seam (nested identity stays descriptor-only; no `$defs` renames)
+- [x] E4: `render_concept_representation` takes real multiplicity (not a boolean) — threaded through `render_stuff_spec`; new helpers `is_multiple_multiplicity` / `fixed_item_count` in `variable_multiplicity.py`; `StuffSpec.is_multiple()` delegates; `runner_code.py` local `_is_multiple` deleted in favor of the shared helper
+- [x] E4: array wrap emits `minItems`/`maxItems` = N when fixed; variable `[]` gets neither bound; `[1]` stays single (no wrap, no bounds)
+- [x] E4: contract memo key normalized to `(concept_ref, is_multiple, fixed_count)` (avoids the `hash(True) == hash(1)` collision between `Concept[]` and `Concept[1]`)
+- [x] Guard: `DocumentContent.url` field-description wording untouched (class gained only a docstring)
+- [x] Probe bundle + trace harness: no extension needed — the existing fixtures already exercise class-backed (`probe_refined.classbacked`), native-direct (`probe_native_inputs`), and fixed-count (`probe_markers.two = Gadget[2]`) inputs; all three enrichments verified present in the regenerated captures
+- [x] Re-baseline the Phase 0-inventoried schema-byte captures: `wip/input-semantics/probe/` regenerated; `docs/tools/cli/build/output.md` schema examples hand-updated (concept-ref title, top-level description, `minItems`/`maxItems`)
+- [x] Unit tests at the render seams: four new tests in `TestSchemaRepresentationWithMultiple` (title/description injection, array identity on items, fixed-count bounds, `[1]` stays single) + `tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py` for the two helpers
+- [x] Changelog (Unreleased): additive schema enrichments
+
+**Checkpoint 2** — the "zero client changes" half complete and measurable.
+
+- [x] Checkpoint 2: tracker updated, checks green
+
+### Checkpoint 2 state (for cold start)
+
+Phase 2 delivered entirely inside: `concept.py` (render seam: multiplicity param + title/description injection + array bounds), `variable_multiplicity.py` (two new helpers), `stuff_spec.py` (delegation + pass-through), `runner_code.py` (shared helper), `pipe_io_contracts.py` (normalized memo key), seven native content classes (docstrings), plus tests, probe re-baseline, and the docs example. Signature change is breaking for direct callers of `render_concept_representation` (`is_multiple` → `multiplicity`) — all in-repo callers and tests updated. Phase 3 recon (from the paused-note, still valid): `PresenceMarker` in `variable_multiplicity.py` is exactly the contract's `presence` vocabulary; contract models to replace are `pipe_io_contracts.py` (`IOMultiplicity`, `PipeInputContract`, `PipeOutputContract`). Note for Phase 4 (unchanged): removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `test_fingerprint_pins.py` — recompute the pins then.
+
+## Phase 3 — contract reshaping (E5, E9) — protocol change, spec-first
+
+- [x] Spec: `../docs/specs/pipelex-mthds-protocol.md` — `pipe_io_contracts` row, "Optional IO contracts and liftable pipes" section, Verified-by line, and the abridged `ValidReport` example all updated to `presence` / three-valued `multiplicity` + `item_count`
+- [x] Spec: one sentence documenting `json_schema` as pydantic-canonical, single-choice enums as `const` (E10's documentation half) — appended to the `pipe_io_contracts` row
+- [x] Conformance: assertions reshaped in `conformance/tests/pipelex_api/test_validate_optionals.py` — the gate is shape-detected (`presence` absent → skip), so it arms automatically when `pipelex-api` re-pins at the cascade; the fixed-count arm stays pinned in pipelex's own suite (the shared optionals fixture has no `[N]` slot, deliberately not extended)
+- [x] `make check-spec-links` in `conformance/` — green (note: `make agent-check` there also surfaced PRE-EXISTING vendored-corpus drift on `vocabulary.toml` from H2, covered by the filed release-time sync inbox item — not this branch's to fix)
+- [x] Engine: `PipeInputContract.presence` replaces `optional` (reuses `PresenceMarker` — same wire values as the descriptor); input + output gain three-valued `IOMultiplicity` (+`FIXED`) and `item_count` via the new `make_io_multiplicity` projection; output `optional` unchanged
+- [x] Emission threads real multiplicity (retired `IOMultiplicity`'s fixed-reports-as-variable ruling)
+- [x] Tests on the contract fields: `tests/integration/pipelex/pipeline/test_pipe_io_contracts.py` reshaped + new `make_two` fixed-count pipe pinning `fixed`/`item_count=2` on input and output plus the bounded array schema
+- [x] Changelog (Unreleased): breaking protocol reshape
+- [x] Probe hop5 capture re-baselined (same regen command); verified `opt/many/two/forced` report exactly (`optional`,`single`) / (`plain`,`variable`) / (`plain`,`fixed`,2) / (`force`,`single`)
+
+**Checkpoint 3** — the protocol change contained in one reviewable unit.
+
+- [x] Checkpoint 3: tracker updated, checks green (`make check` exit 0; the full suite surfaced ONE stale assertion — `test_trace_input_semantics_cmd.py` still pinned the pre-reshape `inputs.hint.optional` — fixed to `presence`/`multiplicity`; full-suite green rides Phase 4's final gate)
+
+## Phase 4 — semantics and close (E3, reflected defaults)
+
+- [x] E3: model validator on `ConceptStructureBlueprint` rejecting `required = true` + `default_value` (message names both remedies) + unit seam `test_concept_structure_blueprint_required_default.py`
+- [x] E3: generator's accidental branch replaced by an explicit raising invariant (`ConceptStructureGeneratorError`) + unit seam `test_structure_generator_required_default_invariant.py`
+- [x] E3: probe bundle's `titled_default` moved to `rejected/required_with_default.mthds_invalid`; pair-sweep fallout applied (builder fixture `test_data.py` had authored the pair — `age` keeps `required`, drops the default); `test_input_form.py` now pins `motto` (`required: false` beside its default); fingerprint pins legitimately recomputed (fixture-content change, recorded in the pin module's docstring)
+- [x] Reflected defaults: `_with_reflected_constraints` reads `field_info.is_required()` + `field_info.default` (a `None` default is the optionality artifact, never reported); kind-table row via the new `retries` field on `InputFormConstrainedPayload`
+- [x] Descriptor spec touch-up: the "may carry both" sentence retired (`default_value` row now states the rejection), the "Facts over emission accidents" bullet notes the founding case resolved, the Verified-by line follows; the D2 conformance skeleton's fixture + assertions moved with it (`required = true` dropped from its `title` field) — `make check-spec-links` green
+- [x] Survival table updated with before/after closure rows (E3, E4, E5, E6/E1, E7, E9) against regenerated `wip/input-semantics/probe/` captures (`titled_default` gone from all hops)
+- [x] Findings addendum §F: per-entry closure evidence table
+- [x] Roadmap Track S closure bullet: in-engine close now, hosted-wire half at the cascade
+- [x] Changelog (Unreleased): E3 breaking + reflected-defaults ruling (Changed)
+- [x] Cross-repo inbox filings (§8): `2026-08-23-mthds-structure-field-validation-sentences.md`, `2026-08-23-pipelex-js-mirror-schema-enrichments-and-contract-reshape.md`, `2026-08-23-mthds-js-protocol-types-contract-reshape.md`
+- [x] In-repo docs swept: `inline-structures.md` gains the `required` bullet + the pair rule; `under-the-hood/input-form-descriptor.md` constraint paragraph updated (E7 made the "parser drops unknown constraint keys" claim false) + reflected-defaults sentence
+- [x] Final: `make agent-check` + full `make agent-test` green (suite exit 0)
+
+## PR #1149 review loop
+
+- [x] PR created (`feature/Enrich` → `dev`), CI fully green on first push
+- [x] Bot reviews (Greptile + codex): both converged on ONE finding — `item_count: null` for non-fixed multiplicity "violates the contract". REJECTED after verification: the protocol spec, its wire example, and `conformance/tests/pipelex_api/test_validate_optionals.py` all pin `item_count: null` off the fixed arm for `pipe_io_contracts` (the omit-when-absent convention belongs to the input-form descriptor; the two artifacts deliberately differ). Replied with evidence, resolved both threads; the misleading docstring wording disambiguated
+- [x] gstack `/review @TODOS.md` (fresh context): verdict SHIP, no P1. Clear wins applied: spec-layer E3 validator on `ConceptStructureSpec` (same two-remedies message; an authoring agent no longer validates green then dies on its own TOML) + spec-level test; stale `default_value` docstring in `input_form.py` fixed; inline duplicate of `fixed_item_count` in `derive_slot` replaced by the helper; parser-level tests wiring both new `rejected/` fixtures (`test_parser_rejected_structure_fields.py`); `force` presence pinned on the wire contract (`brief = "Text!"`); `Text[1]`→single contract projection + memo-key collision pinned (`make_from_one`); reflected `default_factory` (no fabricated default) and falsy default (`False` survives the None guard) pinned; wire-level `item_count`-always-present pinned in the trace test; changelog extended with the spec-layer half
+- [x] Deferred (review findings short of clear wins): `wip/enrich/deferred.md` — non-serializable reflected default, `_peel_multiplicity` `[1]`-as-list divergence (pre-existing), `_with_reflected_constraints` naming, double multiplicity normalization, mostly-inert `rejected/` corpus audit. Skipped outright: 0/negative-count helper rows (unreachable from bundles)
+- [x] Cross-repo: `../wip/inbox/2026-08-23-mthds-form-contract-reshape.md` filed — `mthds-form` still gates the Run button on the retired input `optional` and lacks the `fixed` multiplicity arm; no reshape item covered it
+
+## Out of scope (per design §9)
+
+Language ceiling (S1 §B) syntax, app-side fixes (M1), corpus widening, `const`→`enum` render rewrite, descriptor wire-model round-trip alias (D4).
diff --git a/wip/full-optional/README.md b/wip/full-optional/README.md
new file mode 100644
index 000000000..978bec144
--- /dev/null
+++ b/wip/full-optional/README.md
@@ -0,0 +1,8 @@
+# Full-optional track — a required input whose concept demands nothing
+
+The track behind the **vacuous presence lint**: an advisory `warnings` item, emitted at validate time, when an entry pipe's gating input names a concept whose structure declares no required field — so an empty object satisfies the declaration and no form, gate or caller can tell what "supplied" means.
+
+- [`design.md`](design.md) — the settled design: the rule, its decision table, the decisions (entry-pipe scope, descriptor substrate, one composition point for every advisory warning), the wire shape and message, the blast radius, what is deliberately out of scope, and the cross-repo follow-ups to file at close.
+- [`../../TODOS.md`](../../TODOS.md) — the implementation tracker, at the repo root while the work is live.
+
+Origin: [`wip/inbox/2026-08-25-pipelex-warn-required-input-all-optional-concept.md`](../../../wip/inbox/2026-08-25-pipelex-warn-required-input-all-optional-concept.md) (workspace inbox, filed from `mthds-form`), itself the author-side half of the form kernel's 2026-08-24 readiness-versus-gate disagreement.
diff --git a/wip/full-optional/deferred.md b/wip/full-optional/deferred.md
new file mode 100644
index 000000000..f1ff69514
--- /dev/null
+++ b/wip/full-optional/deferred.md
@@ -0,0 +1,49 @@
+# Vacuous presence lint — deferred items
+
+Things the vacuous-presence work found and deliberately did not do. Each is a decision, not an oversight; the reasoning is here so a later session does not have to re-derive it.
+
+## The builder's `validate_all` still carries no `warnings` key
+
+Every other whole-bundle validate channel now assembles its `warnings` through `pipelex/pipeline/advisory_warnings.py`. One does not: `validate_all` in `pipelex/builder/operations/validate_ops.py`, which returns `{success, is_valid, validated_pipes, total_pipes}` and has never carried advisories at all. Its three siblings in the same module do, and the agent-CLI twin `validate_all_core` does — so the whole-library advisory lints are dropped on exactly this one path.
+
+The cause is structural rather than an omission at the call site. `validate_all` delegates to `BundleValidator.acquire_and_validate`, which opens a library, sweeps it, and **tears it down before returning**. The advisory collector must run inside that window (the taint walk resolves child pipes through the hub, the descriptors read the class registry, the crate is read off the current library), so there is nowhere in `validate_all`'s body left to call it from. Closing the gap means reshaping `acquire_and_validate` — inlining its lifecycle the way `validate_all_core` already does, or giving it a hook that runs inside the window — which is a change to a method shared by several callers and squarely outside a lint's blast radius.
+
+This was already written up during the PR #1026 review (`wip/pr-1026-review-notes.md`), where the same conclusion was reached with the same remedy. The composition point makes the fix *cheaper* than it was — the body of the change is now one `collect_advisory_warnings(...)` call rather than a fourth copy of a pattern — but it does not make it in scope.
+
+**If it is picked up:** mirror `validate_all_core`'s inline lifecycle, compute the warnings before teardown, and take the decision the review note raised — `warnings` alone (minimal), or full alignment with the agent-CLI twin (`pending_signatures` / `is_runnable` too), which would also mean rewriting the deliberate "no `pending_signatures` here by design" comment in that function.
+
+## Transitive vacuity and fixed-count lists
+
+Both are stated in the design (`design.md` §7) rather than here, because they are boundaries of the *rule* rather than of the implementation: a required field that is itself an all-optional object (`{"opts": {}}`) does not warn, and neither does `Concept[N]` of an all-optional concept. One level deep is where the form kernel's trap actually bit, and the transitive notion's edges are arguable (a required text admits `""`, a required list admits `[]`). If it comes back, the natural formulation is "no path from the slot to a scalar or file field passes only through required fields", stated on the descriptor.
+
+## `gating` and `required` cannot be told apart by any derived descriptor
+
+The lint keys on `gating`, which the design argues for on the grounds that the renderer keys on the same fact. That argument stands, but it buys nothing observable today: `InputFormDeriver.derive_slot` computes `gating = required and not (node.kind.is_list and node.item_count is None)`, so on an `object` node — the only kind the lint looks at — `gating` is exactly `required`. The distinction is only visible on a hand-built descriptor, which is where `test_a_non_gating_object_slot_is_silent_even_when_required` pins it.
+
+Nothing to do about it. It is recorded because a future reader may otherwise "simplify" the lint to read `required` and find every test still green — the unit case is the only thing standing in the way, and it is worth knowing that is on purpose.
+
+## The hint lint sweeps the whole accumulated crate, and that is now visible on more channels
+
+`build_hint_warnings` runs over the current library's *accumulated* crate — the validated bundle plus every bundle loaded beside it from `library_dirs`. The vacuous-presence lint is narrower on the bundle channels: there its entry refs come from `result.blueprints`, the validated batch alone, so it never comments on a library you merely depend on. On `validate all` it is not narrower — that channel takes its entry refs from `collect_current_library_entry_pipe_refs()`, which reads the same accumulated blueprints, so a bundle loaded only to satisfy a dependency is linted there too. That is the intended reading of `validate all` (the whole library is the batch), but it means the asymmetry below is a property of the bundle channels rather than of the lint.
+
+That asymmetry is the hint lint's own pre-existing scope decision, unchanged here. What changed is who sees it: the lint used to reach only the protocol validation report, and now rides every advisory-bearing validate channel — the whole-bundle and library-wide ones; the bare single-pipe surfaces and the builder's `validate_all` still carry none (a `--pipe` slice of `validate bundle` does carry them — it validates the whole bundle and only narrows the dry run). So `pipelex validate bundle mine.mthds -L shared/` can report hint findings that belong to `shared/`, which an author cannot act on from where they are standing.
+
+Left alone deliberately. Narrowing the hint lint to the validated batch is a change to that lint's contract, with its own question behind it (a library author does want the findings, on their own validate run), and folding it into a PR about a different lint would hide the decision. If it turns out to be noisy in practice, the fix is to scope `build_hint_warnings` by the batch's domains the way the vacuous lint is scoped by its blueprints — the composition point already holds both ingredients, so it is a small change once the decision is made.
+
+## `load_empty_library` accumulates one library per call, and every test module lives with it
+
+The shared `load_empty_library` fixture (`tests/conftest.py`) is `scope="class"`, but the closure it hands out reassigns `library_id` on every call and its teardown tears down only the last one. A test class calling it once per test therefore leaves one library per test on the manager until the class finishes. This was raised against the vacuous-presence integration module, and it is real — but it is a property of the fixture, not of that module: it is used by most test modules in the suite, several of which call it more than a dozen times in one class.
+
+Left alone deliberately. Fixing it in one module means that module stops matching every neighbour that shares the fixture, which is the worse outcome for a reader; fixing it properly means changing a fixture the whole suite depends on, which is not a lint's business and wants its own run of the full suite to justify. What is at stake is leaked manager state rather than memory alone: the discarded ids stay in the process-global `LibraryManager`'s bookkeeping until the class ends, so a blanket `teardown()` walks them and tears each one down. That is harmless — every library owns its own class registry, so tearing down a stale one touches nothing live — and no assertion in the suite can see it, but it is cleanup that is deferred, not cleanup that does not exist.
+
+**If it is picked up:** make `_load` tear down the library it is replacing before opening the next one (the `prev_library_id` capture already guards against resurrecting a torn-down binding), then run the full suite — the modules calling it a dozen-plus times per class are where a wrong teardown order would surface.
+
+## A `@model_validator` can reject `{}` that the descriptor calls satisfiable
+
+Raised in review: a class-backed concept whose pydantic model defaults every field but carries an `@model_validator` demanding at least one value has no required field by reflection, so the lint fires and the message's "an empty object satisfies it" clause is untrue for it — `model_validate({})` would raise.
+
+The premise is right. The remedy is not, in either shape it was offered. Restricting the lint to authored inline structures would delete its class-backed coverage, which is a documented capability with its own tests, to guard a shape nothing in this repo or the cookbook uses. Proving the model accepts `{}` means calling `model_validate({})` from inside a lint — running author-supplied validator code, with its side effects and its exceptions, during validation.
+
+What settles it is whose blind spot this is. `InputFormDeriver` reads `field_info.is_required()` and never consults validators, and that reading is load-bearing well beyond the lint: the input form is rendered from the same descriptor, so the form offers an empty object for this concept whether or not the lint says anything. The lint is reporting what the form will actually do. The author who acts on either remedy — making a field required, or marking the input `?` — ends up with a better method in that scenario too. Only the one clause is imprecise, and rewording it to hedge would cost every ordinary reader clarity to serve a case none of them are in.
+
+**If it is picked up:** it belongs on the descriptor rather than the lint — a `constraints` note when a structure class declares a model validator, which the form kernel could surface too. That is a change to the wire contract in `docs/specs/mthds-input-form-descriptor.md` and wants the form-kernel side in the conversation.
diff --git a/wip/full-optional/design.md b/wip/full-optional/design.md
new file mode 100644
index 000000000..04d195ea2
--- /dev/null
+++ b/wip/full-optional/design.md
@@ -0,0 +1,146 @@
+# Vacuous presence lint — design
+
+**Status:** design settled on 2026-08-25 and implemented as designed on the same day, with §9's three decisions ratified rather than revised. The implementation landed on `feature/Full-optional` as PR #1152, opened against `dev`; the lint itself is `24520d69f` (with the pre-existing descriptor bug it exposed) through `f536e7c9e`, and the rounds after those are review triage recorded in the tracker's progress log. What is left is follow-up rather than design: the items in §8 and the entries in [`deferred.md`](deferred.md). Tracker: [`TODOS.md`](../../TODOS.md) at the repo root, which carries the running log and the deviations. Origin: a cross-repo request filed from the form-kernel side, queued in the workspace inbox as `2026-08-25-pipelex-warn-required-input-all-optional-concept.md` (not linked — it lives outside this repo).
+
+## 1. The problem
+
+A method input declared without `?` (presence `plain`, or `!`) whose concept declares only optional fields is a declaration that can enforce nothing. The concept's schema admits `{}`, so the only thing "the caller must supply this" can mean is "the caller must supply an empty object". Validation accepts it silently today.
+
+Every consumer that has to *materialise* such an input is left inventing a meaning. The form kernel `@pipelex/mthds-form` hit this on 2026-08-24: readiness was vacuously satisfied (a struct that demands nothing is "filled"), the gate rejected the absent property (`must have required property 'opts'`), and the Run button was live on a form the API would refuse. The kernel closed it on its side (a required struct with no required children now counts as missing until touched), but the end user still faces a required section in which every field is optional — and no consumer can tell the method author that the declaration is ambiguous. Only validation can, and validation lives here.
+
+## 2. Verdict on the inbox idea: confirmed, with three amendments
+
+The idea is right and the channel is right: an advisory item on the validation report's `warnings` array — the seam built for exactly this class of finding — that never flips `is_valid`. Three things in the request were left to us to decide, and each changes the shape of the lint:
+
+1. **Scope it to entry pipes, not every pipe.** The inbox hedged on this ("whether to warn on every pipe or only entry-point signatures"). Linting every pipe would flag a legitimate and common design: an extraction pipe whose output is an all-optional structure ("record whatever the document states"), consumed by a downstream pipe as a plain input. That downstream slot is present by dataflow — the producer always yields *a* value — and its emptiness is the producer's honest output shape, so neither remedy the lint offers applies. The smell exists only at the boundary where a *caller* (a human, a form, an API client) has to conjure the value. That boundary is the bundle's declared `main_pipe`. See D2.
+2. **Judge the concept through the input-form descriptor, not through a third crate walker.** The descriptor already answers "what does this slot demand" for the form: presence, `gating`, and the concept's merged structure with per-field `required` — across refinement chains, class-backed concepts (pydantic `is_required()`), and pinned natives. Re-deriving that in the lint would be a second (with `hint_warnings`, a third) walker over the same facts, and the two existing walkers are already known to diverge (`wip/engine-hints/deferred.md`). Linting the descriptor means the lint judges exactly what the form kernel will see. See D1.
+3. **Give the warnings one composition point.** The report's `warnings` are assembled site by site today, and the sites disagree: the protocol path emits the optionality and hint lints, the agent CLI, the builder ops and the bare CLI emit the optionality lint alone. One more copy of the pattern for this lint would make the disagreement worse. One function builds every advisory warning, and every advisory-bearing channel calls it — which is every whole-bundle validate channel; the builder's `validate_all` and the bare CLI's single-pipe `validate` deliberately surface none. This closes the deferral recorded in `wip/engine-hints/deferred.md` (first bullet) and `wip/input-semantics/deferred-report-artifacts-on-cli-channels.md` (§1), and therefore takes on the one prerequisite those notes attach to it. See D6.
+
+## 3. The rule
+
+For each **entry pipe** of the validated batch, for each **top-level** field of its input-form descriptor:
+
+> Warn when the field is **gating** (`gating: true` — the run cannot start until the caller provides content) and its node is an **`object` that declares no required field** (`kind: "object"` with no entry in `fields` carrying `required: true`; an empty `fields` list counts).
+
+Everything else is silent, and each silence is deliberate:
+
+| Descriptor node | Verdict | Why |
+|---|---|---|
+| `object`, at least one `required: true` field | silent | Content is definable: the caller must fill that field. |
+| `object`, all fields optional | **warn** | The empty object satisfies the declaration. This is the case. |
+| `object`, no fields at all | **warn** (variant wording) | The degenerate all-optional case: only `{}` fits. |
+| `object` under presence `?` (`gating: false`) | silent | The author has already said the value may be absent — the ambiguity is resolved in the right direction. |
+| `list`, variable multiplicity (`Concept[]`) | silent | Never gates by the descriptor's own rule: `[]` is its legitimate value. Item vacuity is a different question (§7). |
+| `list`, fixed count (`Concept[N]`) | silent in this version | Gates, but the vacuity question is per item; deferred (§7). |
+| `text`, `prose`, `number`, `boolean`, `date`, `enum`, `document`, `image` | silent | A scalar or file demands a value; emptiness there is the form's `isFilled` concern, not a declaration defect. |
+| `unknown` (`Dynamic`, `Anything`, `Json`, `Composite`, a cross-package or unresolvable concept) | silent | No authored fact to judge; the honest answer is no verdict. |
+
+The predicate reads `gating`, not `presence`, on purpose. `gating` is the descriptor's *stated* fact that a renderer must block Run until this slot has content, and the lint is precisely "you asked for a gate but content is undefinable here". Stating the lint on the same fact the renderer keys on means the two cannot disagree, and it makes the variable-list exclusion fall out of the descriptor's rule rather than being restated. Both `plain` and `!` gate, so both warn; the message names the marker that was written.
+
+Nested structures are judged **one level deep**. A required field that is itself an all-optional object (`{"opts": {}}`) does not warn in this version — see §7 for why the boundary is drawn here.
+
+## 4. Decisions
+
+### D1 — Substrate: the input-form descriptor
+
+The lint is a pure function over `dict[str, PipeInputFormDescriptor]` (the output of `build_input_form`) plus the set of entry pipe refs. It never touches the crate, the class registry or the pipes.
+
+Why: the descriptor is the reference derivation of what a slot demands (workspace spec `docs/specs/mthds-input-form-descriptor.md`) and it is what the form kernel consumes. Judging the same artifact guarantees the lint and the kernel's readiness rule agree by construction. It also gives class-backed concepts and pinned natives for free — a hand-written `StructuredContent` subclass whose fields all carry defaults is reflected as all-optional by `_with_reflected_constraints`, exactly as the S2 ruling says it should be.
+
+Consequence: on channels that do not build the descriptor today (the CLI and builder channels), the composition point builds it internally for the lint. That is a crate walk per validate, inside the window the sites already hold open — and it is *not* the deferred question of emitting the descriptor on the CLI envelope (`deferred-report-artifacts-on-cli-channels.md` §2), which stays open: computing an artifact for a lint and putting it on the wire are different decisions.
+
+Rejected: a crate walker beside `_HintLinter`, reading `ConceptBlueprint.structure` and merging along `refines`. It would duplicate `InputFormDeriver._merged_structure`, `_first_class_structure` and the class-backed reflection, and would be the third judgment of the same facts.
+
+### D2 — Scope: the batch's entry pipes
+
+An entry pipe is the domain-qualified `main_pipe` of every bundle blueprint in the validated batch. A bundle with no `main_pipe` contributes no entry pipe; a batch with none is not linted.
+
+Why: §2 item 1 — the smell is a caller-boundary smell, and `main_pipe` is where a method meets its caller. This is also what the hosted app and the starters render a form for.
+
+Where the entry refs come from, per channel: the protocol path, the agent-CLI `validate bundle`, the builder `validate_bundle` / `validate_bundle_content` and the bare CLI's `validate bundle` all hold `ValidateBundleResult.blueprints`, so they qualify each bundle's `main_pipe` with `PipeFactory.make_pipe_ref_with_domain`, the same spelling `select_primary_blueprint` uses. The library-wide `validate all` — on the bare CLI and the agent CLI alike — holds no blueprints in hand, but the library manager retains the accumulated blueprints of the acquired library (it rebuilds the crate from them), so a small accessor on `LibraryManagerAbstract` exposes them; the plan's first test on that channel verifies the accumulation actually holds on the `acquire_library` path before relying on it.
+
+Rejected: (a) every pipe — flags the extraction-output pattern, trains authors to ignore the channel; (b) call-graph roots (pipes no other loaded pipe depends on) — needs no plumbing, but flags every reusable pipe of a helper library validated on its own, and `pipe_dependencies()` returns bare codes, so cross-domain matching would be approximate.
+
+### D3 — Presence: `plain` and `!` alike
+
+Both markers gate, both warn. The message names the marker that was written so the remedy reads against the author's own text. At an entry pipe a `!` is unusual (there is no upstream slot to assert), but it is legal and it gates identically.
+
+### D4 — Depth: one level
+
+The predicate looks at the demanded object's direct fields only. See §7 for the transitive case and why it is deferred rather than folded in.
+
+### D5 — Identity and wire shape
+
+A new member of `PipeValidationErrorType`, the pipe enum, since the item locates a pipe input: **`INPUT_PRESENCE_VACUOUS = "input_presence_vacuous"`**. It joins the closed registry automatically (`VALIDATION_ERROR_TYPES` is a union of the enums), the exhaustive `match` blocks on the enum's properties gain the member, and the corpus vocabulary generator lists it as advisory-excluded beside `optional_force_redundant`, with the same reason (an entry contract keyed on `expected_error` has nowhere to put a warning on a valid entry).
+
+The item: `category: pipe_validation`, `error_type: input_presence_vacuous`, `pipe_code` bare, `domain_code` the pipe's domain, `variable_names: [<slot>]`, `message`. No `concept_code`: the protocol's locator table defines `concept_code` on a `pipe_validation` item as the reference that did not resolve, spelled as the author wrote it, and this item has a resolved, descriptor-qualified concept — carrying it there would misuse the locator. The concept is named in the message by its qualified ref, and a consumer that needs it structurally reads `input_form[pipe_ref]`, where the same slot carries `concept_ref`.
+
+Rejected name: `optional_presence_vacuous`, which would keep the `optional_*` family prefix of the other presence-marker diagnostics. The prefix names the optionals feature, but a reader of the wire sees "optional presence" on an input that is precisely not optional. `input_presence_vacuous` is unambiguous on its own.
+
+### D6 — One composition point for every advisory warning
+
+A new module `pipelex/pipeline/advisory_warnings.py` owns the assembly:
+
+- `build_advisory_warnings(*, taint_analyses, input_form, entry_pipe_refs, qualified_crate)` — pure over precomputed ingredients; concatenates the families in a fixed order (optionality, presence vacuity, hints), each family in its own deterministic order. The protocol path calls this with the ingredients it already computes.
+- `collect_advisory_warnings(*, pipes, entry_pipe_refs)` — gathers the ingredients inside the open validation window (the taint walk, the descriptor, the current library's crate qualified once) and calls the pure builder. The CLI and builder channels call this.
+
+Every site that assembles `warnings` today switches to one of the two, and the bare CLI's yellow echo renders whatever the builder returns. The invalid arm and the bare single-pipe surfaces stay warning-less, as the protocol spec states; a `--pipe` slice of `validate bundle` is not a single-pipe surface in that sense — it validates the whole bundle and narrows only the dry run, so it keeps the bundle-wide array.
+
+This brings the hint lints onto the CLI and builder channels, which is the engine-hints deferral. Its stated prerequisite is taken on here: hint messages interpolate authored content raw and unbounded, one item per unknown key, so before that lint reaches a channel an author invokes casually, the lint elides long tokens and caps findings per site (a short "and N more" tail). This is small and it is the honest price of a single composition point.
+
+Rejected: a flag on the composition point selecting which families a channel carries. It would preserve the disagreement the composition point exists to remove.
+
+### D7 — Message wording
+
+All-optional structure, plain input:
+
+> Input 'opts' of pipe 'demo.run' must be supplied (declared without '?'), but concept 'demo.RunOptions' declares no required field — an empty object satisfies it, so a caller cannot tell what to fill in. Mark the input optional (`opts = "demo.RunOptions?"`) if the pipe can run without it, or make at least one field of 'demo.RunOptions' required.
+
+`!` input: the parenthesis reads "(declared with a force marker '!')". Field-less structure: "declares no field at all — an empty object satisfies it", the same clause the all-optional variant uses (the two are distinguished by their first half). Two earlier drafts said more than the descriptor knows: "only an empty object fits it" is false under pydantic's default `extra="ignore"`, and "any object satisfies it and none of it is read" is false under a class setting `extra="forbid"` (rejects) or `extra="allow"` (retains). The descriptor records `fields` only, never the model's extra policy, so `{}` satisfying the concept is the strongest claim the lint can actually make, and the second remedy reads "or give 'demo.RunOptions' a required field". The concept is always the descriptor's qualified `concept_ref`. The message carries no authored free text (no descriptions), so it needs no eliding.
+
+## 5. Blast radius
+
+Runtime:
+
+- `pipelex/validation_error_types.py` — the new member and its comment; every exhaustive `match` property over the type union.
+- `pipelex/pipeline/vacuous_presence_warnings.py` — new: the pure lint over descriptors.
+- `pipelex/pipeline/advisory_warnings.py` — new: the composition point (D6).
+- `pipelex/pipeline/hint_warnings.py` — token eliding and the per-site cap (D6's prerequisite).
+- `pipelex/libraries/library_manager_abstract.py`, `library_manager.py` — the accumulated-blueprints accessor (D2).
+- `pipelex/pipeline/validate_in_process.py`, every site in `pipelex/cli/agent_cli/commands/validate/_validate_core.py` and `pipelex/builder/operations/validate_ops.py`, `pipelex/cli/commands/validate/_validate_core.py` — switch to the composition point.
+- `pipelex/pipeline/validation_report.py`, `pipelex/base_exceptions.py` — docstrings that name `build_optionality_warnings` as the warnings source.
+- `pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py` + regenerated `pipelex/test_extras/mthds_corpus/vocabulary.toml` — the advisory exclusion (D5).
+
+Docs in this repo: `docs/building-methods/pipes/understanding-optionality.md` (the warnings bullet becomes a list of the advisory lints), `docs/building-methods/concepts/inline-structures.md` (a short note: an all-optional structure as a required method input triggers the lint), `docs/under-the-hood/input-form-descriptor.md` (the gating rule now has a lint stated on it), `docs/tools/cli/agent-cli.md` (the advisory note lists all three families and drops "not wired into this CLI's array"), `docs/under-the-hood/error-model.md` and `docs/contribute/mthds-test-corpus.md` (the advisory-only members are now several), `CHANGELOG.md` under `[Unreleased]`.
+
+Tests: a unit decision table over hand-built descriptors; protocol integration cases (entry pipe warns, the same shape on a sub-pipe does not, class-backed all-defaulted structure warns, no `main_pipe` means no lint, `?` silences); an agent-CLI `validate bundle` envelope case and a `validate all` case; the hint cap; the corpus vocabulary gate re-run.
+
+## 6. Interactions worth knowing before implementing
+
+- **`build_input_form` must run inside the validation window** (class-backed reflection reads the class registry). Every site the composition point serves already holds the window open; `validate_in_process` builds it before its `finally`, and the plan keeps it there.
+- **`qualify_crate` runs twice per protocol validate** today (`build_input_form` and the hint lint each qualify the accumulated crate). The collector qualifies once and hands the result to the hint lint; whether `build_input_form` also accepts a pre-qualified crate is opportunistic — do it only if it falls out cleanly, it is a recorded deferral, not this work's goal.
+- **Pinned native objects** (`Page`, `TextAndImages`, `SearchResult`) all declare required fields, so they never fire. The lint reads facts, not identities, so if a native were ever pinned all-optional it would fire — and the message's second remedy would be impossible for the author. Acceptable: the first remedy still holds, and a native pinned that way is the language's bug to fix.
+- **`ConceptStructureBlueprint.required` defaults to `False`**, so a structure authored with the long form and no `required = true` anywhere is all-optional. The shorthand `field = "description"` is a required text field, so a structure with any shorthand field never fires. Worth stating in the docs note, since it is the difference between the two spellings an author is most likely to miss.
+
+## 7. Out of scope, and why the line is here
+
+- **Transitive vacuity** (`{"opts": {}}` — a required field that is itself an all-optional object). Deferred, not rejected. One level is where the form kernel's trap bit, and the transitive notion's edges are fuzzy: a required text admits `""`, a required list admits `[]`, and a lint whose boundary is arguable is a lint that gets ignored. If it comes back, the natural formulation is "no path from the slot to a scalar or file field passes only through required fields", stated on the descriptor.
+- **Fixed-count lists** (`Concept[N]` of an all-optional concept). Gates, admits `[{}, {}]`. Same per-item question as above; deferred with it.
+- **Sub-pipes a caller might run directly** through the API's `pipe_ref` selector. Not linted (D2). If that becomes a real path for form rendering, the entry set can be widened without changing the rule.
+- **Single-pipe validate surfaces.** Stay warning-less, as the protocol spec states.
+- **The `mthds-form` side.** The kernel's fix stands on its own; nothing here changes the descriptor or the wire.
+
+## 8. Cross-repo follow-ups to file at close
+
+Each is an `wip/inbox/` item filed from this repo when the implementation lands, not a widening of this diff:
+
+- **`workspace`** — `docs/specs/pipelex-mthds-protocol.md`: the advisory-warnings section gains the new occupant; the "one further value" sentence under the optionality table and the registry prose become plural. `conformance/`: a valid-arm row `valid_input_presence_vacuous` in `validate-error-qa` with its fixture, and `tests/pipelex_api/test_validate_warnings.py` / `tests/pipelex_agent/test_validate_optionals.py` extended (gated on the release that carries the lint). `make check-spec-links` after both.
+- **`pipelex-js`** — `packages/runtime/src/bundle/categorize.ts` transcribes `PipeValidationErrorType` member for member and its parity check compares against the reference enum; the new member has to be added there.
+- **`pipelex-starter-js`** — `docs/input-form.md`'s "shape to avoid" paragraph can point at the lint once a release carries it.
+- **Corpus consumers** (`conformance`, `mthds-ui`, `vscode-pipelex`) re-vendor `vocabulary.toml` through the sync plugin at the next release; nothing to file, the drift gates say so.
+
+## 9. The decisions that were ratified before implementation
+
+1. Entry-pipe scope (D2) rather than every pipe — the one that changes what authors see most.
+2. The wire name `input_presence_vacuous` (D5).
+3. Bringing the hint lints onto the CLI and builder channels through the composition point, with the cap (D6) — the only item that widens beyond the request; the alternative is the flag D6 rejects.