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.
Engine intent hints (H2) (#1148)
Louis Choqueldc238ff4f4f4
diff --git a/.badges/tests.json b/.badges/tests.jsonindex b32304c29..bc6fb4d5c 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "10757",+ "message": "10858","color": "blue","cacheSeconds": 300}diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 584842ff7..02b34c752 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@### Added+- **MTHDS intent hints land in the engine (H2).** A `hints` table — flat string-to-string, one defined key `intent` with the closed vocabulary `prose` / `label` / `rating` / `quantity` — can now be authored at three sites: on a concept, on a structure field, and on a pipe input slot via the expanded form `name = { concept = "...", hints = { ... } }` (the slot table is closed: unknown keys are rejected, and a hint-free table collapses to the plain string form). Hints are strictly non-normative: they travel through the library crate (a concept's effective hints are assembled during normalization along the refinement chain, nearer declaration winning; field and slot hints travel as authored) and surface on the input-form descriptor, where every node's `hints` slot carries its final site-over-concept merge and an applicable `intent` feeds the node's `kind` — while execution, validation verdicts, and pipe contracts never read them, and a method authoring no hints keeps its crate fingerprint byte for byte. Validation gains an advisory lint (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent` on the report's `warnings` array — warn only, never reject, well-formed unknown content preserved). Documented in `docs/building-methods/concepts/intent-hints.md` and `docs/under-the-hood/input-form-descriptor.md`.+- **The validation report carries an input-form descriptor per pipe.** `PipelexValidationReport.input_form` maps every `pipe_ref` in `pipe_io_contracts` to an ordered list of field descriptors — the MTHDS input-form descriptor (workspace spec `docs/specs/mthds-input-form-descriptor.md`) — derived by `build_input_form` from the loaded pipes and the authored blueprints, never from the emitted JSON Schema. A renderer gets the field kind by concept chain, the namespaced `concept_ref` and `refines` list on every concept node, the three-valued `presence`, a stated `gating` fact, fixed `[N]` counts, authored defaults beside `required`, and one-member `choices` lists, with `unknown` as the honest escape hatch. Class-backed concepts are reflected through the new `reflect_structure_class`, constraints included. Breaking: `build_validation_report` now requires `input_form`, so every backend assembles it or fails loudly. The `trace-input-semantics` harness captures the descriptors as `hop5_input_form.json`. Documented in `docs/under-the-hood/input-form-descriptor.md`.- **`pipelex-dev trace-input-semantics`, a capture harness for the input-schema emission chain.** Given one or more `.mthds` bundles, it dumps one artifact per hop of the chain that turns authored structure syntax into the `json_schema` on `pipe_io_contracts` — parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract — plus a manifest with each input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. A committed probe bundle at `tests/data/input_semantics/probe_bundle.mthds` exercises every construct the language accepts, with deliberately-invalid fixtures under `tests/data/input_semantics/rejected/` pinning what it refuses. Documented in `docs/contribute/trace-input-semantics.md`.diff --git a/TODOS.md b/TODOS.mdindex df6911400..5078564eb 100644--- a/TODOS.md+++ b/TODOS.md@@ -1,111 +1,113 @@-# D2 — Input-form descriptor: reference derivation + report carriage+# Engine intent hints (H2) — implementation tracker-Implements `/Users/lchoquel/repos/Pipelex/wip/inbox/2026-08-22-pipelex-d2-input-form-descriptor-derivation.md` on the stacked branch `feature/Input-semantics-D2` (program branch `feature/Input-semantics`; no PR to `dev`, per the program's branch ruling).+Working tracker for `wip/engine-hints/design.md` on branch `feature/Engine-hints`. Read the design doc first — it holds the rationale, the contract, and the file/line anchors; this file only tracks execution. Checkpoint protocol: at each checkpoint, update the design doc with decisions taken and deviations, verify cold-start readiness, and tick the checkpoint box here.-**Contract:** `docs/specs/mthds-input-form-descriptor.md` (workspace root) — every section. **Gate:** the skip-gated skeletons in `conformance/tests/pipelex_api/test_validate_input_form.py` de-gated and green against the booted sibling `pipelex-api`, plus the per-kind assignment coverage. The two live absent-by-default tests must keep passing untouched. The de-gating itself rides the `pipelex-api` inbox item (Phase 6) because the sibling boots a **pinned PyPI runtime** — this repo's deliverable is the derivation, the report carriage, the pinned assignment table, and the follow-up filings.+## Resume state (for a cold start)-## Settled design decisions (read before implementing)+Phases 1 and 2 are landed and green through Checkpoint A (`make agent-check`, `make check`, `make test` all pass). Decisions taken so far that the design doc does not spell out:-- **Derivation input = loaded pipes + the qualified (NOT normalized) crate.** The slot key space and slot list come from the loaded pipes (`result.pipes` → `pipe.inputs.root` `StuffSpec`s), guaranteeing key-set equality with `pipe_io_contracts` by construction (same iteration, including `PipeSignature` placeholders and controller-inferred inputs). Concept facts (description, `refines`, structure fields) come from a crate built as `qualify_crate(LibraryCrateFactory.make_from_blueprints(result.blueprints))` — **not** `normalize_crate`, because normalization flattens in-crate refinement and drops the `refines` links the descriptor must report as a chain (`crate_normalization.py` step 3 vs spec's `refines` slot). Never read the emitted JSON Schema (the whole point — the E1/E2/E3/E4 losses live downstream of the blueprint).-- **Fact sources per node:** authored concepts → their `ConceptBlueprint.structure` (`ConceptStructureBlueprint` retains `default_value`, `choices`, `required`, descriptions, `concept_ref`/`item_concept_ref` — everything the schema loses); natives → `materialize_native_concept` pinned blueprints; class-backed concepts (`structure = "ClassName"`) → class-registry reflection (generalize the faithful-or-absent approach of `codegen/native_expansion.reflect_native_structure`), falling back to `kind: "unknown"` when unmappable. A pipe slot whose concept is absent from the crate (e.g. loaded from `library_dirs`) still gets a descriptor: slot facts from the loaded `StuffSpec`, concept payload via natives/reflection/`unknown`.-- **Slot facts from `StuffSpec`:** `presence: PresenceMarker` is already the spec's exact three-valued wire vocabulary (`plain`/`optional`/`force`) — reuse it. `multiplicity: VariableMultiplicity | None` keeps the fixed `[N]` int (E4's fact) — `None` → single node, `True` → `list` (no `item_count`), int → `list` with `item_count`.-- **Derived booleans (in the deriver, per spec):** top-level `required = presence != optional`; `gating = required and not (kind == "list" and item_count is None)`. Fixed-count lists gate. Nested fields carry neither `presence` nor `gating`.-- **E3 honesty:** a field authored `required = true` **and** `default_value` reports both — read from the blueprint, so the hop-2 accident never enters. `default_value` emitted only when authored (never the emission's `null`-for-optional artifact).-- **E10:** `choices` always a list on the wire, even one member.-- **Report carriage:** `PipelexValidationReport.input_form: dict[str, PipeInputFormDescriptor]` as a **required** field, `build_validation_report(..., input_form=...)` as a **required** kwarg. No default — the pipelex-server worker path must fail loudly at its next pipelex bump (shared-assembly rule: populated everywhere or nowhere), fixed by its own inbox item. The report always carries it; absence-by-default on the HTTP wire is the route's pop (the `rendered_markdown` precedent), which is `pipelex-api`'s item.-- **Wire absence of inapplicable slots:** the valid arm is dumped **without** `exclude_none`, so a flat model with `None`s would leak `"presence": null` everywhere. Give the field model a None-dropping `@model_serializer` (no slot legitimately carries JSON `null`: TOML cannot author a null default). Flat recursive model + per-kind validators, not a discriminated union — simpler, and D4 owns the TS types.-- **`title`: omitted in D2** (slot exists on the model; renderer falls back to `name` — never the mangled class name). H2 refines.-- **`description` for a flattened scalar:** the concept's authored description, else the payload field's. This is the E6 fix on the descriptor side: class-backed and native concepts get their blueprint/pinned description.-- **Cycle guard:** track the concept-ref path while recursing objects/lists; on revisit emit `unknown` (json_schema's `$ref`s keep the payload contract; the descriptor stays finite).-- **`refines` chain:** walk authored links immediate-parent-first to the end, qualified. A string-described / description-only concept reports `kind: "prose"` with `refines: ["native.Text"]` — this engine's stated fact (it generates a `TextContent` subclass and its `json_schema` is `{text}`), not shape invention.-- **Kind assignment table** (pinned by tests in Phase 3; chain-membership decides, never shape sniffing):- - chain bottoms at / is `native.Text` (incl. string-promoted concepts) → `prose`; `native.Html` → `prose`; `native.Number` → `number` (`integer: false`); `native.YesNo` → `boolean`; `native.Date` → `date` (`datetime: false`); `native.Time` → `text` + `format: "time"`; `native.Document` → `document`; `native.Image` → `image`; `native.Page`, `native.TextAndImages`, `native.SearchResult` → `object` (pinned-blueprint fields); `native.Dynamic`, `native.Anything`, `native.JSON`, `native.Composite` → `unknown`.- - structured concept → `object` (fields in declared order, recursing); nested field types: `text`→`text`, `integer`→`number`(`integer: true`), `number`→`number`, `boolean`→`boolean`, `date`→`date`(`datetime: false`), `datetime`→`date`(`datetime: true`), `time`→`text`+`format:"time"`, `choices` present → `enum` (choices win over `type`, matching the generator), `concept`→ recurse (with `concept_ref` — the E1 fact), `list`→`list` (item from `item_type`/`item_concept_ref`; inner `list` item → `unknown`), `dict`→`unknown`.- - multi-field custom concept never flattens; flattening applies only via the native-chain rules above.-- **No new error class** — the derivation is total (`unknown` is the escape hatch); no `gei`/`gep` needed.-- **Keyword-only rule:** new functions keyword-only; if `build_input_form(pipes, ...)` keeps a positional subject, record the grant (`make sgr`) BEFORE running `make agent-check` (the auto-fixer silently keyword-onlys ungranted subjects).-- Rich ready-made fixture for tests: `tests/data/input_semantics/probe_bundle.mthds` (chains, class-backed, natives, defaults, single choice, `[N]`, `!`, `?`).+- **Sorted-hints emission solved at the model, not the encoder:** the shared `normalize_empty_hints` validator on all three models sorts hints keys, so every dump (fingerprints, codegen crate encoding, wire) is canonical without any encoder walking.+- **Effective hints in normalization:** `_RefinementResolution.effective_hints` is position-specific — the cache write-back walks `reversed(path)` accumulating each visited ref's own hints over what lies below it (`merge_hints`), so a memoized mid-chain resolution carries ITS position's hints (guard test mutation-verified: the naive shared write-back reds exactly that test). `_flatten_refinement` stamps `merge_hints([base_resolution.effective_hints, value.hints])` on BOTH arms — flattened and refines-keeping — and also on chains whose base has no structure to materialize.+- Hinted fixtures: `tests/data/input_semantics/hinted_bundle.mthds` (all three sites, chain override + inheritance, unknown-key preservation, collapsing slot, marked slot); normalization fixtures in `tests/unit/pipelex/libraries/test_crate_normalization_hints.py`.-## Session state (updated 2026-08-22 at close-out — resume here after /compact or cold start)+- **`PipeBlueprint.inputs` is `Mapping[str, str | InputSlotBlueprint] | None`, not `dict`** — value-covariant, so the many `dict[str, str]` construction sites (specs, tests) stay legal without casts. Rationale is a docstring on the field.+- **Two access paths for consumers:** grammar-only consumers read the projection `PipeBlueprint.inputs_concept_specs` (or `slot_concept_spec(value)` per value); hints-aware consumers read `inputs` itself. Sites swept to the projection: `contract_match` (hints don't affect contract identity), `crate_normalization._collect_referenced_natives`, `pipe_factory` (both the concept-existence loop and the `InputStuffSpecsFactory` call — the design's "factory accepts the union" became a call-site projection, same invariant: runtime `StuffSpec` never sees hints), `pipe_llm_factory` + `pipe_img_gen_factory` template analyzers, `pipe_structure_blueprint`, `pipelex_bundle_blueprint._collect_local_refs_from_pipe`, `trace_input_semantics_cmd` (framing manifest carries the concept string; hints surface at hop 5), and all builder `*_spec.from_blueprint` sites (spec layer stays `dict[str, str]`; hints dropped there — builder emission is the known out-of-scope follow-up).+- **Hints travel untouched through:** `crate_qualification` (new `_qualify_slot_value` qualifies the table arm's `concept`, hints pass through) and `bundle_elaborator` (copies `inputs` as-is, so PipeLLM→sequence elaboration keeps slot hints on the draft step and the wrapping sequence).+- **Subject grants recorded** for `merge_hints`, `applicable_intent`, `is_intent_word_known`, `intent_word_applies`, `slot_concept_spec`, `_qualify_slot_value` (in `subject_grants.toml`).+- The pinned fingerprints live in `tests/unit/pipelex/libraries/test_fingerprint_pins.py`, computed on the probe bundle BEFORE the fields landed — keep `tests/data/input_semantics/probe_bundle.mthds` hint-free forever; hinted fixtures go in sibling files.-**All phases done.** What landed where:+Next actions, in order: finish Phase 1's remaining fixtures/tests (unchecked boxes below), then Phase 2's effective-hints merge in normalization.-- `pipelex/pipeline/input_form.py` — wire models, `build_input_form`, `InputFormDeriver`; `pipelex/codegen/native_expansion.py` — `reflect_structure_class`; `pipelex/pipeline/validation_report.py` + `validate_in_process.py` — the required `input_form` carriage.-- Tests: `tests/integration/pipelex/pipeline/test_input_form.py` (probe bundle + kind-table bundle), `tests/unit/pipelex/pipeline/test_input_form_models.py`, `tests/unit/pipelex/pipeline/test_input_form_deriver.py`, plus the carriage sweep and the trace-harness test.-- Docs: `docs/under-the-hood/input-form-descriptor.md` (nav'd), `docs/contribute/trace-input-semantics.md` (the `hop5_input_form.json` capture), the `## [Unreleased]` changelog entry.-- Sibling repos: `conformance/` branch `feature/Input-form-kind-table` (per-kind skeletons, skip-gated); workspace root `dev` (the spec's two new `> Verified by:` lines).-- Inbox: `../wip/inbox/2026-08-22-pipelex-api-validate-views-input-form.md` (the `views` opt-in + OpenAPI + the de-gating of the whole conformance module once the pin moves — this closes D2's gate) and `../wip/inbox/2026-08-22-pipelex-server-worker-input-form-carriage.md` (`temporal/`: carry `input_form` on `DryValidateResult`; rides the D3 pin cascade, fails loudly until then by design).+## Phase 1 — Language surface-**Waiting on:** a `pipelex` release carrying the derivation, then the two inbox items. Nothing else in this repo.+### Shared hints module-Decisions taken while implementing (beyond the settled list above):+- [x] Create `pipelex/language/intent_hints.py`: `INTENT_HINT_KEY = "intent"`, the closed vocabulary (`prose`, `label`, `rating`, `quantity`), pinned per standard version like the native concept definitions.+- [x] Implement `merge_hints(layers)` — key-by-key, later (nearer) layer wins, empty result is `None`. This is the ONE precedence implementation; normalizer and deriver both call it.+- [x] Implement the applicability predicates (text-valued / number-valued site judgment per the spec's Applicability section; description-only concepts are text-valued; plural sites judged per item) and `applicable_intent(hints, *, site) -> str | None`.+- [x] Unit tests for the module: merge precedence, empty-merge → `None`, applicability over each site shape, `applicable_intent` returns only known-and-applicable words.-- **Signature is `build_input_form(pipes, *, blueprints)`**, not `crate=`: the deriver builds the qualified crate itself (`qualify_crate(LibraryCrateFactory.make_from_blueprints(...))`) so both assembly paths hand it the same thing they already hold. The `pipes` subject is granted in `subject_grants.toml`. The deriver class is public (`InputFormDeriver`, with `derive_slot` and `derive_concept`) so its escape hatches can be unit-tested on a hand-built crate without private access.-- **Inheritance of structure along a chain.** A refining concept with no structure of its own (`SpecialEntity refines BaseEntity`) is an `object` whose fields are the merged authored structures along its chain, base fields first, a refining concept overriding its parents' — because the validator requires `fields` on `object` and the test pins `object` for exactly this case. Precedence per node: merged dict structure → `object`; else the first `structure = "ClassName"` on the chain (self first) → class-backed; else a chain bottoming at a native → that native's kind with the concept's own `concept_ref`/description/`refines`; else prose promotion (`refines` = chain + `["native.Text"]`).-- **Class-backed reflection** goes through a new public `reflect_structure_class(*, structure_class)` in `pipelex/codegen/native_expansion.py` (the native probe now delegates to it). A native class name maps by identity (`TextContent` → the `native.Text` rules); any other registered `BaseModel` is reflected into blueprint form and rendered as `object`; unregistered or unmappable → `unknown`. A concept absent from the crate (a `library_dirs` load) takes the same path with the class named by its code.-- **Constraint slots come only from reflected classes.** The blueprint parser drops unknown keys (E7), so an authored `minimum = 0` never reaches the deriver; a registered class's `Field(gt=, ge=, lt=, le=, min_length=, max_length=, pattern=)` does, read from `FieldInfo.metadata` and stamped on `number` (bounds) and `text` (length/pattern) nodes only.-- **`[1]` is a single node.** The parser keeps `multiplicity = 1`, but `StuffSpec.is_multiple()` is `count > 1`, so the runtime takes one value, not a one-element list — the descriptor says the same (no `item`, no `item_count`, `gating: true`).-- **The cycle guard is unreachable from a bundle**: the library loader rejects concept cycles (`Cycle detected in concept references`) before `build_input_form` runs. It stays, because the derivation must be total on any crate handed to it, and is pinned at the deriver level.-- **Remaining natives as inputs** (`TextAndImages`, `SearchResult`, `Dynamic`, `Anything`, `JSON`) are exercised through a `PipeCompose`, because a PipeLLM's dry run treats a `Dynamic` input as an image. `Composite` is not a pipe input and has no row.-- **Nested concept fields** take the blueprint field's `description` and `required` over the concept's (the author described the field); a flattened scalar at the top level keeps the concept's description (E6).-- **Item nodes** reuse the parent field's `name` and report `required: true` (a list element is a value); nested `list` nodes copy the element's `concept_ref`/`refines` per the spec.-- **Enum comparisons** go through properties (`PresenceMarker.is_optional`, a new `FieldKind.is_list`) per the house match/case rule; the scalar-type mapping is one exhaustive `match` in `_scalar_field`.-- `make agent-check`'s keyword-only auto-fixer silently rewrote an internal helper's positional parameter mid-session — the helper was replaced by a keyword-only one; nothing else was touched by it.+### Pinned-fingerprint regression (land BEFORE the model changes)-## Phase 1 — Wire models + derivation (`pipelex/pipeline/input_form.py`)+- [x] Compute the normalized fingerprint of a committed hint-free fixture bundle against the unchanged models, hardcode the hex in a regression test, and commit it first — the suite must prove existing digests do not move when the fields land.-- [x] TDD red: derivation + model tests written (see Session state above; paths differ slightly from the original sketch — integration tests live in `tests/integration/pipelex/pipeline/test_input_form.py`, model tests in `tests/unit/pipelex/pipeline/test_input_form_models.py`): key set equals `build_pipe_io_contracts`'s; authored slot order preserved; presence three-valued (`!` ≠ plain — E5); `required`/`gating` incl. the divergence (plain scalar `gating: true` vs plain `Concept[]` `required: true, gating: false`) and `?` (`required: false, gating: false`); `[N]` → `item_count` + `gating: true` (E4); empty-inputs pipe → `{ "fields": [] }`; namespaced `concept_ref` on every concept node incl. nested (E1); `refines` chain walked to the end, absent when nothing refined (E2); E3 both-facts; single-member `choices` list (E10); serialization drops inapplicable slots (no `null`s in `model_dump(mode="json")`).-- [x] Models: `FieldKind` StrEnum (closed union), recursive `InputFormField` (common slots + per-kind slots + reserved `examples`/`hints`), `PipeInputFormDescriptor` (`fields: list[InputFormField]`), all snake_case wire names per the spec's common-slots table (MTHDS-owned artifact — no `pipelex_` prefixes), None-dropping serializer, per-kind validators (`datetime` required on `date`, `choices` on `enum`, `fields` on `object`, `item` on `list`, `integer` on `number`).-- [x] Deriver: `build_input_form(pipes, *, blueprints) -> dict[str, PipeInputFormDescriptor]` — one public function per the spec's shared-assembly rule; internals per the decisions above.-- [x] Green + `make agent-check`.+### The three parse sites-## Phase 2 — Report carriage (both in-repo assembly points)+- [x] `ConceptBlueprint` (`pipelex/core/concepts/concept_blueprint.py`): add `hints: dict[str, str] | None = None` (`extra="forbid"` already in force — strict shape for free).+- [x] `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`): add the same field. Do NOT change the extras policy — the E7 `extra="forbid"` fix stays in S2's strictness sweep (design Part 1b).+- [x] New `InputSlotBlueprint(BaseModel)` with `extra="forbid"` and exactly two fields: `concept: str` (full existing slot grammar) and `hints: dict[str, str] | None = None`.+- [x] Widen `PipeBlueprint.inputs` to `dict[str, str | InputSlotBlueprint] | None` (`pipelex/pipe_machinery/pipe_blueprint.py`); check the union assembly in `pipelex/mthds_parsing/pipelex_bundle_blueprint.py` propagates to every `Pipe*Blueprint` subclass.+- [x] Extend `generic_validate_inputs` (`pipe_blueprint.py`) to validate the table arm's `concept` with the same ref+multiplicity+presence grammar as the string arm — one grammar, two spellings.+- [x] Implement the parse-time collapse rule at model validation: a slot table with absent or empty `hints` collapses to its plain string, so hint-free bundles produce byte-identical blueprints by construction.+- [x] Empty-table removal on concept/field models too (validator normalizing `hints = {}` to `None`) so the crate never holds an empty hints table.-- [x] `PipelexValidationReport.input_form` (required field, docstringed per house style) + required `input_form` kwarg on `build_validation_report`.-- [x] `validate_in_process.py`: build the qualified crate and call `build_input_form` inside the library window, right beside `build_pipe_io_contracts` (the descriptor must be assembled before teardown for the same class-registry reason).-- [x] Sweep other report producers/consumers in-repo: `tests/unit/pipelex/pipeline/test_validation_report.py`, `test_runner_validate_plumbing.py`, `test_direct_bundle_validator.py`, `test_protocol_validate.py`, the agent-CLI validate envelope, `format_validate_markdown` — update constructions; nothing renders the descriptor in Markdown (it is a structured view, not text).-- [x] Integration assertion in `test_protocol_validate.py` (or a sibling): the in-process report carries `input_form` keyed like `pipe_io_contracts`.+### Serialization — fingerprint neutrality-**CP1 — DONE (commit "D2 CP1: input-form descriptor derivation + report carriage"):** models + derivation + carriage, `make agent-check` and the pipeline/codegen suites green. Decisions recorded in the session state above.+- [x] Add a `@model_serializer(mode="wrap")` to `ConceptBlueprint`, `ConceptStructureBlueprint`, and `InputSlotBlueprint` that drops only the `hints` key when `None` (pattern: `InputFormField.serialize_without_inapplicable_slots`, `pipelex/pipeline/input_form.py`). Deliberately NOT a blanket `exclude_none` — see design Part 2.+- [x] Check `pipelex/codegen/crate_encoding.py`'s TOML emission orders hints entries sorted by key; fix if not (JSON side is covered by `sort_keys=True` in both fingerprint functions). RESOLVED at the model instead: the shared `normalize_empty_hints` validator sorts hints keys on all three models, so every dump (fingerprints, codegen, wire) is canonical with no encoder walking.-## Phase 3 — Pin the full kind-assignment table (pipelex tests)+### Fixtures and tests-- [x] Extend the unit tests with the complete per-native ruling (every `NativeConceptCode` as a direct input → its kind above), string-promoted concept → `prose` + `refines: ["native.Text"]`, class-backed reflection (e.g. `structure = "TextContent"` → flattened `prose` carrying the concept description — E6) and the unmappable → `unknown` fallback, nested `dict`/inner-list → `unknown`, `datetime`/`time` formats, cycle guard.-- [x] Pin whatever the parser does for `[1]` (an `is_multiple()` edge) in one test, reporting it as authored.-- [x] Constraint slots: populate from reflected `FieldInfo` metadata where the engine states them (`Gt`/`Ge`/`Lt`/`Le`/`MinLen`/`MaxLen`/pattern → `exclusive_minimum` etc.); test on a registered class with a constrained field (the `ImageContent.width` precedent).+- [x] Update `tests/data/input_semantics/rejected/per_input_description.mthds_invalid` commentary: it remains a valid rejection, but the rationale shifts to "unknown slot-table key"; verify the failure now surfaces as the slot-table extras error.+- [x] Add accepted-fixture siblings: `{ concept = "…" }` (collapses to string form) and `{ concept = "…", hints = { intent = "prose" } }`.+- [x] Parse unit tests (homes: `tests/unit/pipelex/core/concepts/concept_blueprint/`, `tests/unit/pipelex/mthds_parsing/`): each site accepts a valid flat table; non-table `hints`, non-string values, and nested tables fail as structural errors at all three sites; unknown slot-table keys fail; the collapse rule; grammar preserved through the table arm (multiplicity + markers on `concept`).+- [x] Serialization unit test: the serialized JSON of a hint-free concept/field/pipe contains no `hints` key at any depth.+- [x] Re-run unchanged: `test_fingerprint_determinism`, `test_normalization_is_idempotent`, the round-trip integration suite, and the pinned-fingerprint regression — all green with the fields in place.-**CP2 — DONE (commit "D2 CP2: pin the kind-assignment table and reflected constraint slots"):** assignment table pinned; `make agent-check` + full `make agent-test` green.+## Phase 2 — Crate travel-## Phase 4 — Conformance: per-kind coverage (sibling repo `conformance/`, own commit there)+- [x] `crate_qualification._qualify_io_ref` (`pipelex/libraries/crate_qualification.py`): handle the table arm — qualify the table's `concept` through `_render_ref_with_markers`, pass `hints` through untouched.+- [x] `crate_normalization._collect_referenced_natives` (`pipelex/libraries/crate_normalization.py`): read the table arm's `concept`.+- [x] `InputStuffSpecsFactory.make_from_blueprint` (`pipelex/core/pipes/inputs/input_stuff_specs_factory.py`): accept the union, extract the `concept` string ONLY. `StuffSpec` must NOT grow a hints field — runtime models stay hint-free (structural non-normativity).+- [x] Effective hints in normalization: extend `_RefinementResolution` with `effective_hints: dict[str, str] | None`; accumulate along the child→base walk in `_resolve_refinement` via the shared `merge_hints` (nearer declaration wins). Applies to both the flattened arm and the `refines`-keeping (native-backed) arm; pinned natives contribute nothing. Empty merge leaves no member.+- [x] Memoization guard: a cached mid-chain resolution must carry the hints of ITS position in the chain, not the querying concept's — add a test that exposes this.+- [x] Structure-field and slot hints carried as authored through qualification and normalization (no merge at crate level — the site-over-concept merge is the deriver's).+- [x] Normalization unit tests (`tests/unit/pipelex/libraries/test_crate_normalization.py`): chain merge on both arms, memoized mid-chain hints, empty merge, idempotency extended to a hinted fixture (re-normalizing is a no-op).+- [x] Integration: round-trip suite green with a hinted fixture; a hinted crate's fingerprint differs from its hint-free twin.-- [x] Add per-kind skeleton tests to `conformance/tests/pipelex_api/test_validate_input_form.py`, skip-gated with the same `SKELETON_REASON` (the sibling boots a pinned PyPI runtime that predates the derivation): one bundle exercising the assignment table end to end (prose/document/image/number/boolean/single-member-enum/object-with-nested-concept_ref/list-with-`[N]`-item_count/date/unknown-dict), asserting kinds, `refines` membership, `presence`, E3 both-facts, and no-`null` inapplicable slots.-- [x] Do NOT touch the two live absent-by-default tests.-- [x] `make check-spec-links` in `conformance/` (new tests join the already-linked module; verify nothing drifted). Follow that repo's branch/PR convention for the commit.+## Checkpoint A — crate layer done-**CP3 — DONE:** `conformance/` branch `feature/Input-form-kind-table` (commit "Pin the kind-assignment table skeletons in the input-form descriptor module", `make agent-check` green there) plus the spec's two new `> Verified by:` lines under *Field kinds* and *Structured multiplicity*, committed on the workspace root's `dev` ("Link the field-kinds and structured-multiplicity sections to their conformance skeletons"). The kind-table bundle was derived locally on this branch before the assertions were written, so the skeletons state what the deriver already produces.+- [x] Hints parse at three sites, travel qualified and normalized, hint-free crates provably keep their digests. Update `wip/engine-hints/design.md` with decisions and deviations; verify cold-start readiness; commit.-## Phase 5 — Docs + changelog (this repo)+## Phase 3 — Advisory lint-- [x] New docs page documenting the descriptor derivation: where it lives, the fact sources, the kind-assignment table, the gating rule, pointer to the workspace spec as the contract. Link it from the docs nav where natural (MkDocs conventions: blank line before lists).-- [x] `docs/contribute/trace-input-semantics.md` + harness: add the descriptor as a trace artifact (a hop beside `hop5_pipe_io_contracts.json`) so a mangled authored fact localizes into the new projection too — small, per the keep-useful-harnesses rule.-- [x] `CHANGELOG.md` under `## [Unreleased]`: bold-label condensed entry (breaking: `build_validation_report` requires `input_form`; the report gains the field).+- [x] New `pipelex/pipeline/hint_warnings.py` with `build_hint_warnings(...)`: sweep the qualified crate's three sites, emit one advisory `ValidationErrorItem` per finding (unknown hint key, unknown `intent` word, applicable word on inapplicable site), each naming its site (concept code / field name / pipe code + slot name). Warn only — never reject; well-formed unknown content is preserved.+- [x] Advisory enum: new `HintLintErrorType` (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`) joined into the `ValidationErrorType` alias (`pipelex/validation_error_types.py`). Open question 1: if the render layer's required properties make a shared enum cheaper, decide here with the code in view — the wire strings are the contract, the enum layout is not. RESOLVED open question 1: separate enum, no render-layer properties needed.+- [x] Wire into `pipelex/pipeline/validate_in_process.py` beside `build_optionality_warnings`. Done via `build_current_library_hint_warnings()` (empty sweep when no library/crate — the mocked-plumbing and fallback paths). The bare-CLI / agent-CLI / builder-ops warning channels are a deferred follow-up (see `wip/engine-hints/deferred.md`).+- [x] Regenerate the two gates: error-identity snapshot (`make gei`) and error-reference docs pages (`make gep`). Outcome: no diff from either — `HintLintErrorType` members are enum values, not `PipelexError` subclasses; the corpus vocabulary DID regenerate (three excluded `error.hint_*` tags).+- [x] Lint unit tests (beside `test_validation_errors.py`): each warning fires with site attribution; a warned bundle is still valid; warned content survives into crate and descriptor. Home: `tests/unit/pipelex/pipeline/test_hint_warnings.py` + a warned-bundle-still-valid integration test in `test_protocol_validate.py`. Descriptor-survival half lands with Phase 4.-## Phase 6 — File the two cross-repo follow-ups (workspace `wip/inbox/`, from here `../wip/inbox/`)+## Phase 4 — Descriptor population-- [x] `YYYY-MM-DD-pipelex-api-validate-views-input-form.md` (use `_TEMPLATE.md`): add `views: list[str]` beside `render` with identical lenient mechanics (`validate.py:31/:59` precedent), resolve-then-attach-or-pop `input_form` on the valid arm only, regenerate the committed OpenAPI, bump the `pipelex` pin once released, then **de-gate the whole conformance module** (this closes D2's gate). Carry the evidence pointers (spec section, skeleton file/lines, this branch's derivation site).-- [x] `YYYY-MM-DD-pipelex-server-worker-input-form-carriage.md`: carry `input_form` on `DryValidateResult` inside the library window (`act_dry_validate.py:52`) and hand it to `build_validation_report` (`temporal_bundle_validator.py:107`); state plainly that the next pipelex bump fails loudly on the missing kwarg by design (shared-assembly rule) — rides D3's cascade. Name the member (`temporal/`) in the body.+- [x] Narrow `InputFormField.hints` from `dict[str, Any]` to `dict[str, str]` (`pipelex/pipeline/input_form.py`) — flatness is contract.+- [x] Plumb slot hints from the qualified crate: `build_input_form` keeps the qualified crate's `pipes` too; per slot name, the blueprint's `inputs` value is a string (no hints) or a slot table (hints). Open question 3: per-call `derive_slot` argument vs pipe-ref-keyed lookup — taste call, decide here; the invariant is that `StuffSpec` stays hint-free. Fallback path (no crate) derives with no hints. RESOLVED open question 3: per-call `derive_slot(slot_hints=...)` argument — the `build_input_form` loop has blueprint and StuffSpec in hand; the deriver stays stateless over pipes.+- [x] Concept nodes (`_blueprint_node`, `derive_concept`): stamp the concept's effective hints — deriver computes the chain merge via its existing `_refines_chain` walk calling the shared `merge_hints`. String-shorthand, natives, and class-backed concepts stamp nothing.+- [x] Structure fields (`_structure_field`): `merge_hints([referenced concept's effective hints (concept-typed and concept-item fields only), field.hints])`, stamped via `model_copy(update=…)`.+- [x] Input slots (`derive_slot`): `merge_hints([slot concept's effective hints, slot hints])`, stamped in the final `model_copy(update=…)` beside `presence`/`required`/`gating`.+- [x] Plural slots and list fields: merged hints stamped on the `list` node AND its `item` descriptor (the `concept_ref` duplication precedent).+- [x] Intent feeds kind — never competes: via `applicable_intent(...)`, on text-valued nodes `intent = "prose"` → `kind: "prose"`, `intent = "label"` → `kind: "text"`; absent/inapplicable/unknown intent leaves the no-hint default; `rating`/`quantity` never change `kind` and ride the slot; inapplicable words change nothing in `kind` but still ride the slot as preserved content. Implemented as one terminal `_with_effective_hints` stamp per node (inner layers carry hints without flipping), so the flip always reads the FINAL merge against the no-hint kind; `_node_site_kind` mirrors the lint's structural judgment (time-formatted text and Html-backed nodes are not text-valued).+- [x] Extend the probe bundle under `tests/data/input_semantics/` with hinted fixtures. Done as the SIBLING `hinted_bundle.mthds` (probe_bundle stays hint-free forever — its fingerprints are pinned).+- [x] Deriver unit + integration tests (`tests/integration/pipelex/pipeline/test_input_form.py` kind table): site-over-concept and chain precedence visible on the wire; `prose`/`label` flip `kind` on text-valued nodes only; `rating`/`quantity` untouched-kind + slot ride; list/item duplication; hint-free descriptor output byte-identical to today.-## Phase 7 — Close out+## Checkpoint B — round trip end to end-- [x] Full `make agent-check` + `make agent-test` (the full suite — new test modules only get seen there).-- [x] Commit remaining work on `feature/Input-semantics-D2` with the CP structure above; no PR to `dev` (program ruling) — the PR is stacked on `feature/Input-semantics`.-- [x] Final checkpoint note in this file: what landed where, decisions taken, what the two inbox items are waiting on.-- [x] PR #1146 review round (stacked on `feature/Input-semantics`): greptile's one finding (library-dir concepts degraded to `unknown`) led to deriving over the library's accumulated crate instead of the bundle blueprints — `build_input_form(pipes)` no longer takes `blueprints`; the gstack pre-landing review's two clear wins (description-only and refining library-dir concepts) are covered by the same change and its test; its two decision-first items are deferred in `wip/input-semantics/deferred-descriptor-reflection-and-roundtrip.md`. cubic and Codex were out of quota for this PR.-- [x] `make check` + serial `make test` before the PR: one order-dependent failure in a `pipe_func` workdir test, unrelated to D2 (passes alone and under `agent-test`); deferred to `wip/input-semantics/deferred-serial-make-test-flake.md`.+- [x] Authored hints visible in `hop5_input_form.json` via the trace harness (`pipelex-dev trace-input-semantics`) on the hinted corpus method. Same checkpoint protocol as A: update the design doc, verify cold-start readiness, commit.-## Deliberately out of scope (do not widen the diff)+## Phase 5 — Schema, corpus, docs, close-- The `pipelex-api` route change (`views`) — Phase 6 item 1.-- The `pipelex-server/temporal/` worker carriage — Phase 6 item 2.-- Any S2 emission fix (E1–E10 in the schema chain): the descriptor reports authored intent from the blueprint, so none are prerequisites.-- The kernel swap (M1), SDK types (D4), hints (H1/H2), `@pipelex/runtime` parity (E1-track).+- [x] Regenerate `derived/mthds_schema.json` (`make gms`), verify with `make cms`; if Taplo's `anyOf` disambiguation misbehaves on the slot union, hand-patch via the `_patch_construct_schema` precedent in `pipelex/language/mthds_schema_generator.py`. *(All three hint sites present in the schema; `cms` green, no hand-patch needed.)*+- [x] Corpus entry authoring hints at all three sites (`pipelex/test_extras/mthds_corpus/`); re-run `make generate-corpus-vocabulary`. This entry is the "one real method" the gate's round-trip proof runs on. *(`feature_intent_hints_reading_circle`: concept + structure-field + expanded-slot hints; `feature.intent_hints` tag added; corpus suites green.)*+- [x] Check the builder writer (`pipelex/builder/operations/concept_ops.py`): if preserving hints on rewrite is a one-liner, do it; otherwise file the follow-up (it sits beside the known E8 spelling bug in the same writer). *(Not a one-liner — `ConceptSpec`/`ConceptStructureSpec` lack the field entirely; follow-up filed in `wip/engine-hints/deferred.md`.)*+- [x] Docs: `docs/under-the-hood/input-form-descriptor.md` — the stated no-hint kind rules (promote heuristics to specified rules), hints slot no longer reserved-only, drop the now-false "parser drops unknown keys" framing where it touches hints; document the three authoring sites and the lint in the language-facing blueprint docs.+- [x] Changelog: record the feature under `## [Unreleased]`.+- [x] Full gates: `make agent-check` + `make agent-test` green. *(Both green on the settled Phase 5 tree; the pre-existing `test_transported_run_generates_concept_structures` order-dependent flake did not recur — noted in `wip/flaky-test-transported-run-structures.md`.)*+- [x] Milestone close per workspace protocol:+ - [x] Roadmap checkpoint in `../wip/devx/input-form-roadmap.md` with SHAs, including the gate-wording reconciliation (open question 2: engine-provable gate = wire-descriptor visibility; rendered-control half completes with M1/H3). *(Applied with commit subjects rather than SHAs — the branch squash-merges, so branch SHAs die; H2 marked ✅ in the dependency graph. Workspace-repo edits left uncommitted for review.)*+ - [x] Workspace descriptor spec (`../docs/specs/mthds-input-form-descriptor.md`): reserved-hint-slot section from "reserved" to "populated"; kind-assignment section reflects the stated no-hint rules.+ - [x] Conformance repo: hint-slot arm as a skip-gated skeleton (D2's de-gating pattern, arming at the release that ships H2); `make check-spec-links` in `conformance/`. *(`TestInputFormHintSlot`, 4 skip-gated tests; both conformance gates green.)*+ - [x] Inbox items (`../wip/inbox/`): the `mthds`-site "Specification Status" conformance-assertion update, and the `mthds-corpus-sync` / `mthds-schema-sync` runs that ride the next release.+ - [x] H3 handoff note. *(`../wip/inbox/2026-08-23-mthds-form-h3-render-intent-hints.md`.)*++## Out of scope (do not do here)++E7 `extra="forbid"` on `ConceptStructureBlueprint` (S2); per-slot semantic keys (`description`, defaults, examples); hints on class-backed structures and natives; the crate spec's general absent-members-not-null canonicalization and step-5 materialization; kernel rendering (H3) and consumer wire-descriptor swap (M1).diff --git a/docs/building-methods/concepts/intent-hints.md b/docs/building-methods/concepts/intent-hints.mdnew file mode 100644index 000000000..632218721--- /dev/null+++ b/docs/building-methods/concepts/intent-hints.md@@ -0,0 +1,75 @@+# Intent Hints++Intent hints let a method author state, in the method itself, how a value is *meant to be presented* — that a text is flowing prose rather than a short label, that a number is a subjective rating rather than a measured quantity. They are part of the MTHDS standard (spec: `intent-hints.md` in the MTHDS spec) and they are strictly **non-normative**: hints never change what a pipe accepts, produces, or validates. They travel through the library crate and surface on the input-form descriptor, where a form renderer can honor them.++## Authoring++A `hints` table is a flat table of string keys to string values. This version of the standard defines one key, `intent`, with a closed vocabulary:++| `intent` | Applies to | Declares |+|---|---|---|+| `prose` | text-valued sites | Flowing natural language, written and read as running text. |+| `label` | text-valued sites | A short designation — a name, a title; a few words on one line. |+| `rating` | number-valued sites | A subjective score on a scale — a judgment, not a measurement. |+| `quantity` | number-valued sites | An amount — a count or a measured magnitude. |++Hints attach at three sites:++**On a concept:**++```toml+[concept.Essay]+description = "A short essay"+hints = { intent = "prose" }+```++**On a structure field:**++```toml+[concept.Review.structure]+headline = { type = "text", description = "the headline", hints = { intent = "label" } }+stars = { type = "integer", description = "the stars", hints = { intent = "rating" } }+```++**On a pipe input slot**, using the expanded slot form — `concept` carries exactly the grammar the plain string form does, markers included:++```toml+[pipe.write_review]+type = "PipeLLM"+description = "Write a review"+inputs = { topic = { concept = "Text", hints = { intent = "prose" } }, refs = { concept = "Reference[]", hints = { intent = "label" } } }+output = "Review"+prompt = "Write a review of @topic"+```++A slot table with no `hints` is the same slot as the plain string: `x = { concept = "Text" }` and `x = "Text"` parse to identical blueprints and hash identically in the crate.++## Shape is strict, content is lenient++The *shape* of a `hints` table is enforced: it must be a flat string-to-string table, and the expanded slot form admits only `concept` and `hints` — anything else (a non-table `hints`, a number value, a nested table, an unknown slot-table key like `description`) is a structural validation error.++The *content* is lenient: an unknown hint key or an unknown `intent` word parses, is preserved through the crate and onto the descriptor, and is only **warned** about. Validation emits advisory warnings (never errors) for three findings, each naming its site: an unknown hint key (`hint_unknown_key`), an unknown `intent` word (`hint_unknown_intent`), and a known word on a site it does not apply to (`hint_inapplicable_intent`) — for example `rating` on a text field. This is what lets the vocabulary grow between standard versions without breaking older validators.++## Precedence and inheritance++Effective hints merge **key by key**, and a nearer declaration wins:++- Along a refinement chain, a refining concept's hints override its base's, key by key; keys the refiner does not set are inherited. A hint can be overridden but never cleared.+- At a site, the site's hints (a field's, a slot's) win over the concept's effective hints, key by key.++```toml+[concept.Badge]+description = "A badge"+hints = { intent = "label" }++[concept.SpecialBadge]+description = "A special badge"+refines = "Badge"+hints = { intent = "prose" } # overrides the inherited label+```++## Where hints surface++Hints ride the library crate (a concept's effective hints are assembled during normalization; field and slot hints travel as authored) and land on the [input-form descriptor](../../under-the-hood/input-form-descriptor.md): every node's `hints` slot carries its final effective merge, and an applicable `intent` word feeds the node's `kind` — `prose` and `label` select between the `prose` and `text` kinds on text-valued nodes; `rating` and `quantity` ride the slot for the renderer without changing `kind`. On a plural site (a `Concept[]` slot, a list field), applicability is judged per item, and the merged hints appear on both the `list` node and its `item`.++Because hints are non-normative, the runtime never reads them: execution, validation verdicts, and pipe contracts are identical with and without them — and a method that authors no hints keeps its crate fingerprint, byte for byte.diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.mdindex 1c6aeda7a..28b582c92 100644--- a/docs/under-the-hood/input-form-descriptor.md+++ b/docs/under-the-hood/input-form-descriptor.md@@ -33,6 +33,8 @@ Kinds are decided by chain membership and declared types — never by sniffing aThe crate the deriver reads is the current library's accumulated one, which holds the validated bundle and every `library_dirs` bundle loaded beside it — so a concept from a library dir, or a local concept refining one, follows the same rules as a local concept. A concept absent from that crate altogether is `unknown`.+The table and rules above ARE the no-hint kind assignment — stated rules, not heuristics: with no applicable intent hint, a node's kind is exactly what they produce. An applicable authored `intent` (spec: MTHDS `intent-hints.md`) *feeds* that assignment, never competes with it: on a **text-valued** node — one whose site is a `text` field, a `native.Text`-chained or description-only concept, judged per item on plural sites — an effective `intent = "prose"` yields `kind: "prose"` and `intent = "label"` yields `kind: "text"`; an absent, unknown, or inapplicable intent leaves the no-hint kind untouched. On a **number-valued** node, `rating` and `quantity` never change `kind` (both are `number`; the union has no finer kind) — they ride the `hints` slot for the renderer to honor. A time-formatted `text` node and an `Html`-backed `prose` node are *not* text-valued sites, so no intent word applies to them.+| Native concept | Kind ||---|---|| `Text`, `Html` | `prose` |@@ -47,7 +49,11 @@ The crate the deriver reads is the current library's accumulated one, which holdNested structure fields map by their declared type: `text` → `text`; `integer` → `number` with `integer: true`; `number` → `number`; `boolean` → `boolean`; `date` → `date`; `datetime` → `date` with `datetime: true`; `time` → `text` with `format: "time"`; a field with `choices` → `enum` (choices win over `type`, matching the structure generator); `concept` → the concept's node, carrying its namespaced `concept_ref`; `list` → `list` whose `item` comes from `item_type` / `item_concept_ref` (a nested list's inner item is inexpressible and reports `unknown`); `dict` → `unknown`. The shorthand `field = "description"` form is a required `text`. Nested fields take the blueprint field's description and `required` over the concept's; a scalar flattened at the top level keeps the concept's description.-Constraint slots (`minimum`, `exclusive_minimum`, `min_length`, `pattern`, …) come only from reflected classes: the blueprint parser drops keys it does not know, so an authored `minimum = 0` never reaches the deriver, whereas a registered class's `Field(gt=0, max_length=8, pattern=...)` is read from the pydantic field metadata and stamped on the matching `number` or `text` node.+Constraint slots (`minimum`, `exclusive_minimum`, `min_length`, `pattern`, …) come only from reflected classes: the blueprint parser drops *constraint* keys it does not know, so an authored `minimum = 0` never reaches the deriver, whereas a registered class's `Field(gt=0, max_length=8, pattern=...)` is read from the pydantic field metadata and stamped on the matching `number` or `text` node. (Authored `hints` are the exception — they are a parsed blueprint field, not a dropped unknown; see below.)++## Hints++Every node carries an optional `hints` slot: the node's **effective** MTHDS intent hints — the key-by-key merge of the concept's refinement chain (nearer declaration winning) with the site's own hints (a field's or a slot's, the site layer winning). Everything well-formed rides it, unknown keys and words included (the advisory validation lint has already warned about them; the descriptor preserves them for consumers that know more than this version does). On a plural node the merged hints appear on the `list` node *and* its `item` — the `concept_ref` duplication precedent: applicability is judged per item, and a renderer reading either node finds the same answer. A node with no effective hints has no `hints` member, so hint-free methods produce byte-identical descriptors to before hints existed. The slot is flat `string → string` by contract.## Required, presence and gating@@ -59,4 +65,4 @@ Inapplicable slots are absent, never JSON `null`: the report's valid arm is dump## Seeing it-`pipelex-dev trace-input-semantics` captures the descriptors as `hop5_input_form.json` beside `hop5_pipe_io_contracts.json`, so an authored fact can be checked on both projections at once — see [Tracing Input Semantics](../contribute/trace-input-semantics.md). The assignment table is pinned by `tests/integration/pipelex/pipeline/test_input_form.py` over the committed probe bundle, the wire models by `tests/unit/pipelex/pipeline/test_input_form_models.py`, and the escape hatches the library loader keeps unreachable (concept cycles, unregistered classes) by `tests/unit/pipelex/pipeline/test_input_form_deriver.py`.+`pipelex-dev trace-input-semantics` captures the descriptors as `hop5_input_form.json` beside `hop5_pipe_io_contracts.json`, so an authored fact can be checked on both projections at once — see [Tracing Input Semantics](../contribute/trace-input-semantics.md). The assignment table is pinned by `tests/integration/pipelex/pipeline/test_input_form.py` over the committed probe bundle (and the hints behavior over its hinted sibling, `hinted_bundle.mthds`), the wire models by `tests/unit/pipelex/pipeline/test_input_form_models.py`, the hint merges and kind-feeding by `tests/unit/pipelex/pipeline/test_input_form_hints.py`, and the escape hatches the library loader keeps unreachable (concept cycles, unregistered classes) by `tests/unit/pipelex/pipeline/test_input_form_deriver.py`.diff --git a/mkdocs.yml b/mkdocs.ymlindex 92272891b..52879c64b 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -246,6 +246,7 @@ plugins:- building-methods/concepts/python-classes.md: "Python Classes"- building-methods/concepts/native-concepts.md: "Native Concepts"- building-methods/concepts/refining-concepts.md: "Refining Concepts"+ - building-methods/concepts/intent-hints.md: "Intent Hints"- building-methods/pipes/index.md: "Design and Run Methods Overview"- building-methods/libraries.md: "Libraries"- building-methods/packages.md: "Packages"diff --git a/pipelex/builder/pipe/pipe_batch_spec.py b/pipelex/builder/pipe/pipe_batch_spec.pyindex 320a00a9b..5ebb7226f 100644--- a/pipelex/builder/pipe/pipe_batch_spec.py+++ b/pipelex/builder/pipe/pipe_batch_spec.py@@ -91,7 +91,7 @@ class PipeBatchSpec(PipeSpec):base_blueprint = super().to_blueprint()return PipeBatchBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,branch_pipe_code=self.branch_pipe_code,input_list_name=self.input_list_name,diff --git a/pipelex/builder/pipe/pipe_compose_spec.py b/pipelex/builder/pipe/pipe_compose_spec.pyindex 82ae017a4..a1e0dda84 100644--- a/pipelex/builder/pipe/pipe_compose_spec.py+++ b/pipelex/builder/pipe/pipe_compose_spec.py@@ -218,7 +218,7 @@ class PipeComposeSpec(PipeSpec):return PipeComposeBlueprint.model_validate({"description": base_blueprint.description,- "inputs": base_blueprint.inputs,+ "inputs": base_blueprint.inputs_concept_specs,"output": base_blueprint.output,"construct": self.construct_spec,}@@ -239,7 +239,7 @@ class PipeComposeSpec(PipeSpec):return PipeComposeBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,template=template_blueprint,)diff --git a/pipelex/builder/pipe/pipe_condition_spec.py b/pipelex/builder/pipe/pipe_condition_spec.pyindex ea682a2ac..91345ec72 100644--- a/pipelex/builder/pipe/pipe_condition_spec.py+++ b/pipelex/builder/pipe/pipe_condition_spec.py@@ -82,7 +82,7 @@ class PipeConditionSpec(PipeSpec):base_blueprint = super().to_blueprint()return PipeConditionBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,type=self.type,pipe_category=self.pipe_category,diff --git a/pipelex/builder/pipe/pipe_extract_spec.py b/pipelex/builder/pipe/pipe_extract_spec.pyindex 1f9752820..c14b52aad 100644--- a/pipelex/builder/pipe/pipe_extract_spec.py+++ b/pipelex/builder/pipe/pipe_extract_spec.py@@ -96,7 +96,7 @@ class PipeExtractSpec(PipeSpec):return PipeExtractBlueprint(source=None,description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,model=self.model,max_page_images=self.max_page_images,diff --git a/pipelex/builder/pipe/pipe_func_spec.py b/pipelex/builder/pipe/pipe_func_spec.pyindex dfddab4aa..ff07f5ac6 100644--- a/pipelex/builder/pipe/pipe_func_spec.py+++ b/pipelex/builder/pipe/pipe_func_spec.py@@ -38,7 +38,7 @@ class PipeFuncSpec(PipeSpec):base_blueprint = super().to_blueprint()return PipeFuncBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,function_name=self.function_name,)diff --git a/pipelex/builder/pipe/pipe_img_gen_spec.py b/pipelex/builder/pipe/pipe_img_gen_spec.pyindex 88dd16e65..86ee0a30b 100644--- a/pipelex/builder/pipe/pipe_img_gen_spec.py+++ b/pipelex/builder/pipe/pipe_img_gen_spec.py@@ -70,7 +70,7 @@ class PipeImgGenSpec(PipeSpec):return PipeImgGenBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,prompt=self.prompt,model=self.model,diff --git a/pipelex/builder/pipe/pipe_llm_spec.py b/pipelex/builder/pipe/pipe_llm_spec.pyindex 8e222c22a..59cf9a7eb 100644--- a/pipelex/builder/pipe/pipe_llm_spec.py+++ b/pipelex/builder/pipe/pipe_llm_spec.py@@ -129,7 +129,7 @@ So, don't have to write a bullet-list of all the attributes definitions yourselfreturn PipeLLMBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,system_prompt=self.system_prompt,prompt=self.prompt,diff --git a/pipelex/builder/pipe/pipe_parallel_spec.py b/pipelex/builder/pipe/pipe_parallel_spec.pyindex 8cbbc2c79..fb6d0e5fa 100644--- a/pipelex/builder/pipe/pipe_parallel_spec.py+++ b/pipelex/builder/pipe/pipe_parallel_spec.py@@ -77,7 +77,7 @@ class PipeParallelSpec(PipeSpec):core_branches = [branch.to_blueprint() for branch in self.branches]return PipeParallelBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,type=self.type,pipe_category=self.pipe_category,diff --git a/pipelex/builder/pipe/pipe_search_spec.py b/pipelex/builder/pipe/pipe_search_spec.pyindex 6ce5aa49b..1faa06b34 100644--- a/pipelex/builder/pipe/pipe_search_spec.py+++ b/pipelex/builder/pipe/pipe_search_spec.py@@ -126,7 +126,7 @@ class PipeSearchSpec(PipeSpec):return PipeSearchBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,prompt=self.prompt,model=self.model,diff --git a/pipelex/builder/pipe/pipe_sequence_spec.py b/pipelex/builder/pipe/pipe_sequence_spec.pyindex 88369efea..1825339f5 100644--- a/pipelex/builder/pipe/pipe_sequence_spec.py+++ b/pipelex/builder/pipe/pipe_sequence_spec.py@@ -63,7 +63,7 @@ class PipeSequenceSpec(PipeSpec):core_steps = [step.to_blueprint() for step in self.steps]return PipeSequenceBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,steps=core_steps,)diff --git a/pipelex/builder/pipe/pipe_structure_spec.py b/pipelex/builder/pipe/pipe_structure_spec.pyindex 1e852b12a..94cd1c178 100644--- a/pipelex/builder/pipe/pipe_structure_spec.py+++ b/pipelex/builder/pipe/pipe_structure_spec.py@@ -57,7 +57,7 @@ class PipeStructureSpec(PipeSpec):return PipeStructureBlueprint(description=base_blueprint.description,- inputs=base_blueprint.inputs,+ inputs=base_blueprint.inputs_concept_specs,output=base_blueprint.output,model=self.model,)diff --git a/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py b/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.pyindex 915688767..8eac782c3 100644--- a/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py+++ b/pipelex/cli/dev_cli/commands/generate_corpus_vocabulary_cmd.py@@ -21,7 +21,13 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.pipe_machinery.pipe_blueprint import PipeCategory, PipeTypefrom pipelex.runtime_hub import get_consolefrom pipelex.test_extras.mthds_corpus.vocabulary import ValidationLayer, vocabulary_path-from pipelex.validation_error_types import VALIDATION_ERROR_TYPES, PipeFactoryErrorType, PipeValidationErrorType, ValidationErrorType+from pipelex.validation_error_types import (+ VALIDATION_ERROR_TYPES,+ HintLintErrorType,+ PipeFactoryErrorType,+ PipeValidationErrorType,+ ValidationErrorType,+)_ACRONYM_BOUNDARY_RE = re.compile(r"(?<=[A-Z0-9])(?=[A-Z][a-z])")_WORD_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")@@ -43,6 +49,13 @@ _HEADER = """# The MTHDS Test Corpus tag vocabulary — the closed set an entry'# cross-repo contract, `docs/specs/mthds-test-corpus.md` in the Pipelex workspace repo."""+_ADVISORY_HINT_LINT_EXCLUSION = (+ "Advisory-only: the intent-hints lint rides the validation report's `warnings` array and never makes a "+ "verdict invalid (hints are non-normative; well-formed unknown content is preserved). Same shape problem "+ "as `optional_force_redundant`: an entry contract keyed on `expected_error` has nowhere to put a warning "+ "on a valid entry. Revisit if the manifest ever grows a warnings axis."+)+# A code is excluded when no standalone focused entry could meaningfully exercise it. Exclusions# are visible decisions, one reason each: an excluded tag stays in the vocabulary and stays usable# by an entry, it is simply not required to have a focused entry of its own. Keying this map by@@ -92,6 +105,11 @@ _FEATURE_TAGS: dict[str, str] = {"Bare caller values — a string, a number, a dict, a list — interpreted top-down against the entry ""pipe's declared signature, so a caller need not wrap each one in its concept envelope."),+ "intent_hints": (+ "An `intent` hint authored in a `hints` table — on a concept, a structure field, or an expanded "+ "input slot — carrying non-normative presentation intent (`prose`, `label`, `rating`, `quantity`) "+ "that renderers may honor and every other consumer safely ignores."+ ),"multi_file_library": ("A method split across several `.mthds` files in one directory and merged additively behind a ""`bundle.mthds` entry point, so a pipe can be forward-declared as a signature in one file and "@@ -140,6 +158,9 @@ _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."),+ HintLintErrorType.HINT_UNKNOWN_KEY: _ADVISORY_HINT_LINT_EXCLUSION,+ HintLintErrorType.HINT_UNKNOWN_INTENT: _ADVISORY_HINT_LINT_EXCLUSION,+ HintLintErrorType.HINT_INAPPLICABLE_INTENT: _ADVISORY_HINT_LINT_EXCLUSION,PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR: ("The generic fallback for a validation failure that matched no specific code. Reaching it on purpose ""would mean authoring a bundle that breaks in a way the categorizer does not recognize — which is a "diff --git a/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py b/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.pyindex dfa650908..283800b9f 100644--- a/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py+++ b/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py@@ -245,7 +245,9 @@ def _build_wire_framing(*, blueprints: list[PipelexBundleBlueprint], pipes: listfor pipe_code, pipe_blueprint in blueprint.pipe.items():if not pipe_blueprint.inputs:continue- for var_name, authored in pipe_blueprint.inputs.items():+ # The framing manifest tracks the slot grammar (ref + markers), so an expanded-form slot+ # contributes its `concept` string; its hints surface at hop 5 (the input-form descriptor).+ for var_name, authored in (pipe_blueprint.inputs_concept_specs or {}).items():authored_specs[f"{blueprint.domain}.{pipe_code}.{var_name}"] = authoredframing: list[dict[str, Any]] = []diff --git a/pipelex/core/concepts/concept_blueprint.py b/pipelex/core/concepts/concept_blueprint.pyindex a67efda34..2ba1c9bd8 100644--- a/pipelex/core/concepts/concept_blueprint.py+++ b/pipelex/core/concepts/concept_blueprint.py@@ -1,7 +1,7 @@import keywordfrom typing import Any, cast-from pydantic import BaseModel, ConfigDict, field_validator, model_validator+from pydantic import BaseModel, ConfigDict, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validatorfrom pipelex.core.concepts.concept_structure_blueprint import RESERVED_FIELD_NAMES, ConceptStructureBlueprintfrom pipelex.core.concepts.validation import is_concept_ref_or_code_valid@@ -18,6 +18,29 @@ class ConceptBlueprint(BaseModel):structure: str | dict[str, ConceptStructureBlueprintType] | None = None# TODO: restore possibility of multiple refilesrefines: str | None = None+ hints: dict[str, str] | None = None+ """MTHDS intent hints (spec: intent-hints.md) — non-normative presentation intent. Shape is+ strict (flat string->string table), content is lenient (unknown entries preserved, advisory+ lint warns). An empty table is equivalent to no hints and normalizes to absence."""++ @field_validator("hints", mode="after")+ @classmethod+ def normalize_empty_hints(cls, hints: dict[str, str] | None) -> dict[str, str] | None:+ # Sorted here so every serialization is canonical (spec: hints entries emitted sorted by+ # key); hint key order is not semantic, unlike structure-field order.+ return dict(sorted(hints.items())) if hints else None++ @model_serializer(mode="wrap")+ def serialize_without_absent_hints(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:+ """Absent hints are an absent member — never `null` (spec rule; keeps hint-free crate+ fingerprints byte-identical to before hints existed). Deliberately NOT a blanket+ `exclude_none`: the crate spec's general absent-members canonicalization is a separate+ forward contract whose adoption would migrate every existing fingerprint.+ """+ dumped: dict[str, Any] = handler(self)+ if dumped.get("hints") is None:+ dumped.pop("hints", None)+ return dumped@field_validator("refines", mode="before")@classmethoddiff --git a/pipelex/core/concepts/concept_structure_blueprint.py b/pipelex/core/concepts/concept_structure_blueprint.pyindex be634f5cd..8b36b58fc 100644--- a/pipelex/core/concepts/concept_structure_blueprint.py+++ b/pipelex/core/concepts/concept_structure_blueprint.py@@ -2,7 +2,7 @@ from datetime import date, datetime, timefrom enum import StrEnumfrom typing import Any, Self-from pydantic import BaseModel, Field, field_validator, model_validator+from pydantic import BaseModel, Field, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validatorfrom pipelex.core.concepts.validation import is_concept_ref_or_code_validfrom pipelex.system.pipe_run_param_key import PipeRunParamKey@@ -62,6 +62,27 @@ class ConceptStructureBlueprint(BaseModel):choices: list[str] | None = Field(default=None)default_value: Any | None = Nonerequired: bool = Field(default=False)+ hints: dict[str, str] | None = None+ """MTHDS intent hints (spec: intent-hints.md) — non-normative presentation intent for this+ field as a site. Carried as authored through the crate; the site-over-concept merge is the+ consumer's. An empty table is equivalent to no hints and normalizes to absence."""++ @field_validator("hints", mode="after")+ @classmethod+ def normalize_empty_hints(cls, hints: dict[str, str] | None) -> dict[str, str] | None:+ # Sorted here so every serialization is canonical (spec: hints entries emitted sorted by+ # key); hint key order is not semantic, unlike structure-field order.+ return dict(sorted(hints.items())) if hints else None++ @model_serializer(mode="wrap")+ def serialize_without_absent_hints(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:+ """Absent hints are an absent member — never `null` (spec rule; keeps hint-free crate+ fingerprints byte-identical to before hints existed).+ """+ dumped: dict[str, Any] = handler(self)+ if dumped.get("hints") is None:+ dumped.pop("hints", None)+ return dumped@field_validator("concept_ref", mode="before")@classmethoddiff --git a/pipelex/language/intent_hints.py b/pipelex/language/intent_hints.pynew file mode 100644index 000000000..e3cd90552--- /dev/null+++ b/pipelex/language/intent_hints.py@@ -0,0 +1,95 @@+"""Intent hints — the language-standard knowledge shared by every hints consumer.++Single owner of the MTHDS intent-hints vocabulary (spec: `mthds/docs/spec/intent-hints.md`), the+one precedence implementation (`merge_hints`), and the applicability judgment. The refinement-chain+walks stay where they are (crate normalization, the input-form deriver); they all call the merge+defined here so the standard's key-by-key precedence has exactly one implementation.++Hints are non-normative: nothing in this module participates in any verdict or execution decision.+"""++from collections.abc import Sequence+from enum import StrEnum++INTENT_HINT_KEY = "intent"+"""The one hint key this version of the standard defines."""++KNOWN_HINT_KEYS = frozenset({INTENT_HINT_KEY})+"""Keys defined by the pinned standard version; anything else is preserved-but-warned content."""+++class IntentWord(StrEnum):+ """The closed `intent` vocabulary, pinned per standard version like the native concept definitions."""++ PROSE = "prose"+ LABEL = "label"+ RATING = "rating"+ QUANTITY = "quantity"+++class HintSiteValueKind(StrEnum):+ """What a site's value is, for applicability judgment.++ Callers classify their site with their own structural knowledge (field types; refinement chains+ reaching `native.Text` / `native.Number`; description-only concepts are text-valued; plural+ sites judged per item) and hand the classification here.+ """++ TEXT_VALUED = "text_valued"+ NUMBER_VALUED = "number_valued"+ OTHER = "other"+++def merge_hints(layers: Sequence[dict[str, str] | None]) -> dict[str, str] | None:+ """Merge hint layers key by key, ordered farthest to nearest — a later layer wins.++ The one precedence implementation: the refinement chain (base before refiner) and the+ site-over-concept merge (concept layer before site layer) both express their order here.+ An empty result is `None` — absent hints are an absent member, never an empty table.+ """+ merged: dict[str, str] = {}+ for layer in layers:+ if layer:+ merged.update(layer)+ # Sorted here too: merged results are installed via model_copy(update=...), which bypasses the+ # blueprint validators that sort authored tables, yet still reach canonical serialization.+ return dict(sorted(merged.items())) or None+++def is_intent_word_known(word: str) -> bool:+ return word in set(IntentWord)+++def intent_word_applies(word: IntentWord, *, site_kind: HintSiteValueKind) -> bool:+ """Whether an intent word applies to a site of the given value kind.++ Exhaustive over the vocabulary, so a new word cannot land without an explicit applicability+ decision here (unknown raw words are filtered out by `is_intent_word_known` upstream).+ """+ match word:+ case IntentWord.PROSE | IntentWord.LABEL:+ applicable_kind = HintSiteValueKind.TEXT_VALUED+ case IntentWord.RATING | IntentWord.QUANTITY:+ applicable_kind = HintSiteValueKind.NUMBER_VALUED+ match site_kind:+ case HintSiteValueKind.TEXT_VALUED | HintSiteValueKind.NUMBER_VALUED:+ return site_kind is applicable_kind+ case HintSiteValueKind.OTHER:+ return False+++def applicable_intent(hints: dict[str, str] | None, *, site_kind: HintSiteValueKind) -> IntentWord | None:+ """The effective `intent` word, only when it is known AND applicable to the site.++ The deriver's and the lint's shared question: absent, unknown, and inapplicable intents all+ answer `None`, leaving the consumer on its own semantic-layer defaults.+ """+ if not hints:+ return None+ word = hints.get(INTENT_HINT_KEY)+ if word is None or not is_intent_word_known(word):+ return None+ intent = IntentWord(word)+ if not intent_word_applies(intent, site_kind=site_kind):+ return None+ return intentdiff --git a/pipelex/libraries/contract_match.py b/pipelex/libraries/contract_match.pyindex bbaa0c94b..0070f0245 100644--- a/pipelex/libraries/contract_match.py+++ b/pipelex/libraries/contract_match.py@@ -69,8 +69,10 @@ def contracts_match(*, existing: PipeBlueprint, incoming: PipeBlueprint, domain_``inputs`` and an empty ``inputs`` are treated alike. Input *names* must match exactly — they arevariable names, not concepts."""- existing_inputs = {name: _canonical_concept_spec(spec, domain_code=domain_code) for name, spec in (existing.inputs or {}).items()}- incoming_inputs = {name: _canonical_concept_spec(spec, domain_code=domain_code) for name, spec in (incoming.inputs or {}).items()}+ # Hints are non-normative, so contract identity reads the concept-spec projection: a hinted slot+ # and its hint-free twin denote the same contract (`x = { concept = "S" }` ≡ `x = "S"`).+ existing_inputs = {name: _canonical_concept_spec(spec, domain_code=domain_code) for name, spec in (existing.inputs_concept_specs or {}).items()}+ incoming_inputs = {name: _canonical_concept_spec(spec, domain_code=domain_code) for name, spec in (incoming.inputs_concept_specs or {}).items()}if existing_inputs != incoming_inputs:return Falsereturn _canonical_concept_spec(existing.output, domain_code=domain_code) == _canonical_concept_spec(incoming.output, domain_code=domain_code)diff --git a/pipelex/libraries/crate_normalization.py b/pipelex/libraries/crate_normalization.pyindex b55cf62e5..f3a47dd4d 100644--- a/pipelex/libraries/crate_normalization.py+++ b/pipelex/libraries/crate_normalization.py@@ -42,6 +42,7 @@ from pipelex.core.concepts.helpers import normalize_structure_blueprintfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicityfrom pipelex.core.qualified_ref import QualifiedRef+from pipelex.language.intent_hints import merge_hintsfrom pipelex.libraries.crate_qualification import qualify_cratefrom pipelex.libraries.exceptions import CrateNormalizationErrorfrom pipelex.libraries.library_crate import LibraryCrate@@ -53,6 +54,11 @@ _ConceptEntry = ConceptBlueprint | strclass _RefinementResolution(NamedTuple):is_native_backed: booleffective_structure: dict[str, ConceptStructureBlueprint] | None+ effective_hints: dict[str, str] | None = None+ """The resolved ref's OWN effective hints — its authored hints merged over its bases', nearer+ winning (spec: intent-hints.md, Precedence and Inheritance). Position-specific: a cached+ mid-chain resolution carries the hints of ITS position, unlike `effective_structure`, which+ every ref above the structure-carrying base legitimately shares."""def normalize_crate(crate: LibraryCrate, *, mthds_version: str) -> LibraryCrate:@@ -130,10 +136,18 @@ def _flatten_refinement(concepts: dict[str, _ConceptEntry]) -> None:if not isinstance(value, ConceptBlueprint) or not value.refines or isinstance(value.structure, dict):continueresolution = _resolve_refinement(value.refines, concepts=concepts, cache=resolution_cache)- if resolution.is_native_backed:- continue- if resolution.effective_structure:- concepts[concept_ref] = value.model_copy(update={"refines": None, "structure": dict(resolution.effective_structure)})+ updates: dict[str, object] = {}+ # Effective hints are assembled here, where the chain is walked and nowhere later — on the+ # flattened and the refines-keeping arm alike, so a consumer reads a concept's hints without+ # walking anything (spec: library-crate.md step 3). An empty merge leaves no member.+ effective_hints = merge_hints([resolution.effective_hints, value.hints])+ if effective_hints != value.hints:+ updates["hints"] = effective_hints+ if not resolution.is_native_backed and resolution.effective_structure:+ updates["refines"] = None+ updates["structure"] = dict(resolution.effective_structure)+ if updates:+ concepts[concept_ref] = value.model_copy(update=updates)def _resolve_refinement(@@ -184,9 +198,16 @@ def _resolve_refinement(else:resolution = cache[current_ref]+ # Write back one entry per visited ref. `effective_structure` is genuinely shared (every ref+ # above the structure-carrying base has that same effective structure), but hints accumulate:+ # each position's entry merges its own authored hints over everything below it, nearer winning.+ accumulated_hints = resolution.effective_hintsfor visited_ref in reversed(path):- cache[visited_ref] = resolution- return resolution+ visited_value = concepts.get(visited_ref)+ own_hints = visited_value.hints if isinstance(visited_value, ConceptBlueprint) else None+ accumulated_hints = merge_hints([accumulated_hints, own_hints])+ cache[visited_ref] = resolution._replace(effective_hints=accumulated_hints)+ return cache[concept_ref]def _native_effective_structure(native_ref: str) -> dict[str, ConceptStructureBlueprint] | None:@@ -232,7 +253,7 @@ def _collect_referenced_natives(*, concepts: dict[str, _ConceptEntry], pipes: di_add_native_ref(referenced=referenced, concept_ref_or_code=field.concept_ref)_add_native_ref(referenced=referenced, concept_ref_or_code=field.item_concept_ref)for blueprint in pipes.values():- for io_ref in [*(blueprint.inputs or {}).values(), blueprint.output]:+ for io_ref in [*(blueprint.inputs_concept_specs or {}).values(), blueprint.output]:_add_native_ref(referenced=referenced, concept_ref_or_code=_io_ref_concept(io_ref))return referenceddiff --git a/pipelex/libraries/crate_qualification.py b/pipelex/libraries/crate_qualification.pyindex ab65f9c4e..639dce54e 100644--- a/pipelex/libraries/crate_qualification.py+++ b/pipelex/libraries/crate_qualification.py@@ -35,7 +35,7 @@ makes that contradiction unrepresentable and costs the callers nothing — bothcrate to read the envelope from, and `normalize_crate` builds a fresh one anyway."""-from typing import NamedTuple+from typing import TYPE_CHECKING, NamedTuplefrom pipelex.core.concepts.concept_blueprint import ConceptBlueprint, ConceptStructureBlueprintTypefrom pipelex.core.concepts.concept_factory import ConceptFactory@@ -51,6 +51,9 @@ from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcomefrom pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprintfrom pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint+if TYPE_CHECKING:+ from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint+_ConceptEntry = ConceptBlueprint | str@@ -135,10 +138,19 @@ def _qualify_concept_ref(concept_ref_or_code: str, *, domain: str) -> str:# --------------------------------------------------------------------------------------------------+def _qualify_slot_value(slot_value: "str | InputSlotBlueprint", *, domain: str) -> "str | InputSlotBlueprint":+ """Qualify a slot's concept through the same marker-preserving rewrite in both arms; a table+ arm's hints pass through untouched (a hints table contains no refs).+ """+ if isinstance(slot_value, str):+ return _qualify_io_ref(slot_value, domain=domain)+ return slot_value.model_copy(update={"concept": _qualify_io_ref(slot_value.concept, domain=domain)})++def _qualify_pipe_blueprint(blueprint: PipeBlueprintUnion, *, owner_domain: str) -> PipeBlueprintUnion:updates: dict[str, object] = {}if blueprint.inputs:- updates["inputs"] = {name: _qualify_io_ref(ref, domain=owner_domain) for name, ref in blueprint.inputs.items()}+ updates["inputs"] = {name: _qualify_slot_value(value, domain=owner_domain) for name, value in blueprint.inputs.items()}if blueprint.output:updates["output"] = _qualify_io_ref(blueprint.output, domain=owner_domain)diff --git a/pipelex/libraries/library_crate_factory.py b/pipelex/libraries/library_crate_factory.pyindex 3d388f8e6..b69b216d0 100644--- a/pipelex/libraries/library_crate_factory.py+++ b/pipelex/libraries/library_crate_factory.py@@ -218,7 +218,8 @@ class LibraryCrateFactory:def _contract_mismatch_msg(pipe_ref: str, *, existing: PipeDeclaration, incoming: PipeDeclaration) -> str:return (f"Pipe '{pipe_ref}' is declared with mismatched contracts: "- f"'{existing.source or 'unknown'}' has inputs={existing.blueprint.inputs or {}}, output='{existing.blueprint.output}' "- f"while '{incoming.source or 'unknown'}' has inputs={incoming.blueprint.inputs or {}}, output='{incoming.blueprint.output}'. "+ f"'{existing.source or 'unknown'}' has inputs={existing.blueprint.inputs_concept_specs or {}}, output='{existing.blueprint.output}' "+ f"while '{incoming.source or 'unknown'}' has inputs={incoming.blueprint.inputs_concept_specs or {}}, "+ f"output='{incoming.blueprint.output}'. ""A forward declaration (PipeSignature) and the matching declaration must agree on inputs and output.")diff --git a/pipelex/mthds_parsing/pipelex_bundle_blueprint.py b/pipelex/mthds_parsing/pipelex_bundle_blueprint.pyindex ccf08802b..3fcea60fd 100644--- a/pipelex/mthds_parsing/pipelex_bundle_blueprint.py+++ b/pipelex/mthds_parsing/pipelex_bundle_blueprint.py@@ -282,7 +282,7 @@ class PipelexBundleBlueprint(BaseModel):# Check inputsif pipe_blueprint.inputs:- for input_name, input_concept_spec in pipe_blueprint.inputs.items():+ for input_name, input_concept_spec in (pipe_blueprint.inputs_concept_specs or {}).items():local_ref = parse_concept_with_multiplicity(input_concept_spec).concept_ref_or_codelocal_refs.append((local_ref, f"pipe.{pipe_code}.inputs.{input_name}"))diff --git a/pipelex/pipe_machinery/pipe_blueprint.py b/pipelex/pipe_machinery/pipe_blueprint.pyindex ebdf534e3..396a5ff84 100644--- a/pipelex/pipe_machinery/pipe_blueprint.py+++ b/pipelex/pipe_machinery/pipe_blueprint.py@@ -1,9 +1,10 @@import refrom abc import ABC+from collections.abc import Mappingfrom enum import StrEnumfrom typing import Any, Self, cast, final-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator+from pydantic import BaseModel, ConfigDict, Field, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validatorfrom pipelex.core.concepts.exceptions import ConceptStringErrorfrom pipelex.core.concepts.validation import validate_concept_ref_or_code@@ -176,6 +177,46 @@ def valid_pipe_type_tags() -> list[str]:return [*PipeType.value_list(), PIPE_SIGNATURE_TYPE_TAG]+class InputSlotBlueprint(BaseModel):+ """The expanded input-slot form: `name = { concept = "…", hints = { … } }` (spec: intent-hints.md).++ `concept` carries the full slot grammar of the string form (ref, optional multiplicity, optional+ presence marker). The form is deliberately closed (`extra="forbid"` implements the spec's+ "unknown slot-table keys MUST be rejected") so future per-slot semantic keys land here without a+ second syntax. A slot table carrying no hints collapses to its plain string at parse time (see+ `PipeBlueprint.collapse_hint_free_slot_tables`), so a slot value that IS a table carries+ non-empty hints — hint-free bundles produce byte-identical blueprints to the string form.+ """++ model_config = ConfigDict(extra="forbid")++ concept: str+ hints: dict[str, str] | None = None++ @field_validator("hints", mode="after")+ @classmethod+ def normalize_empty_hints(cls, hints: dict[str, str] | None) -> dict[str, str] | None:+ # Sorted here so every serialization is canonical (spec: hints entries emitted sorted by+ # key); hint key order is not semantic, unlike structure-field order.+ return dict(sorted(hints.items())) if hints else None++ @model_serializer(mode="wrap")+ def serialize_without_absent_hints(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:+ """Absent hints are an absent member — never `null` (spec rule). Unreachable for a+ hint-free slot in practice (the parse-time collapse leaves it a plain string), kept so any+ directly-constructed instance still serializes canonically.+ """+ dumped: dict[str, Any] = handler(self)+ if dumped.get("hints") is None:+ dumped.pop("hints", None)+ return dumped+++def slot_concept_spec(slot_value: "str | InputSlotBlueprint") -> str:+ """The concept spec string of an input-slot value (markers included), whichever arm authored it."""+ return slot_value if isinstance(slot_value, str) else slot_value.concept++class PipeBlueprint(ABC, BaseModel):model_config = ConfigDict(extra="forbid")@@ -183,9 +224,23 @@ class PipeBlueprint(ABC, BaseModel):pipe_category: Any = Field(exclude=True) # Technical field for Union discrimination, not user-facingtype: Any # TODO: Find a better way to handle this.description: str- inputs: dict[str, str] | None = None+ inputs: Mapping[str, str | InputSlotBlueprint] | None = None+ """`Mapping` (not `dict`) deliberately: value-covariant, so the dominant hint-free callers keep+ passing plain `dict[str, str]` without a cast. Values are strings except for slots authored in+ the expanded form WITH hints (see the collapse rule below)."""output: str+ @field_validator("inputs", mode="after")+ @classmethod+ def collapse_hint_free_slot_tables(cls, inputs: Mapping[str, str | InputSlotBlueprint] | None) -> Mapping[str, str | InputSlotBlueprint] | None:+ """Parse-time collapse rule: `x = { concept = "S" }` and `x = { concept = "S", hints = {} }`+ are the same slot as `x = "S"` and become that string (the spec says they hash identically).+ Invariant bought downstream: a slot value that is a table carries non-empty hints.+ """+ if not inputs:+ return inputs+ return {name: value.concept if isinstance(value, InputSlotBlueprint) and not value.hints else value for name, value in inputs.items()}+@propertydef nb_inputs(self) -> int:return len(self.inputs) if self.inputs else 0@@ -194,6 +249,18 @@ class PipeBlueprint(ABC, BaseModel):def input_names(self) -> list[str]:return list(self.inputs.keys()) if self.inputs else []+ @property+ def inputs_concept_specs(self) -> dict[str, str] | None:+ """Slot name -> concept spec string (markers included), whichever arm authored each slot.++ The projection for consumers that read the slot grammar and nothing else — template+ analyzers, contract matching, the runtime spec factory. Hints-aware consumers (crate+ qualification, the input-form deriver) read `inputs` itself.+ """+ if self.inputs is None:+ return None+ return {name: slot_concept_spec(value) for name, value in self.inputs.items()}+@propertydef is_signature(self) -> bool:# Identity by class, not by enum field: the base is never a signature; `PipeSignatureBlueprint`@@ -281,9 +348,13 @@ class PipeBlueprint(ABC, BaseModel):@finaldef generic_validate_inputs(self):if self.inputs:- for input_name, concept_spec in self.inputs.items():+ for input_name, slot_value in self.inputs.items():validate_input_name(input_name)+ # One grammar, two spellings: the expanded slot form's `concept` value is validated+ # with the same ref+multiplicity+presence grammar as the plain string form.+ concept_spec = slot_concept_spec(slot_value)+# Validate the concept spec format: optional multiplicity brackets then optional# presence marker. Pattern allows: ConceptName, domain.ConceptName, ConceptName[],# ConceptName[N], ConceptName?, ConceptName!diff --git a/pipelex/pipe_machinery/pipe_factory.py b/pipelex/pipe_machinery/pipe_factory.pyindex 33e4264c1..acd815ac8 100644--- a/pipelex/pipe_machinery/pipe_factory.py+++ b/pipelex/pipe_machinery/pipe_factory.py@@ -60,7 +60,7 @@ class PipeFactory(Generic[PipeAbstractType]):# TODO: This test should move to the PipelexBlueprint validation.# Validate that the specified concepts are declared in the bundle, or are natives concepts.if blueprint.inputs is not None:- for input_name, input_concept_ref_or_code in blueprint.inputs.items():+ for input_name, input_concept_ref_or_code in (blueprint.inputs_concept_specs or {}).items():stripped_input_concept_ref_or_code = strip_markers_from_concept_ref_or_code(concept_ref_or_code=input_concept_ref_or_code)if "." not in stripped_input_concept_ref_or_code:if (@@ -103,10 +103,12 @@ class PipeFactory(Generic[PipeAbstractType]):except StuffSpecFactoryError as exc:msg = f"Error parsing output string '{blueprint.output}': {exc}"raise PipeFactoryError(msg) from exc+ # The concept-spec projection, deliberately: runtime `StuffSpec`s never receive hints — the+ # execution path cannot consult what it never gets (hints are non-normative by construction).parsed_inputs = InputStuffSpecsFactory.make_from_blueprint(concept_provider=get_concept_library(),domain_code=domain_code,- blueprint=blueprint.inputs or {},+ blueprint=blueprint.inputs_concept_specs or {},)# The factory class name for that specific type of Pipe is the pipe class name with "Factory" suffix.diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.pyindex adf631124..cf1c9217b 100644--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py@@ -55,6 +55,8 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):# Images may be referenced in positive prompt, negative prompt, or bothimage_references: list[ImageReference] | None = Noneif blueprint.inputs:+ # Template analyzers read the slot grammar only, so they get the concept-spec projection.+ blueprint_input_specs = blueprint.inputs_concept_specs or {}all_image_refs: list[ImageReference] = []seen_paths: set[str] = set()@@ -62,7 +64,7 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):if blueprint.prompt:prompt_refs = TemplateImageAnalyzer.analyze_template_for_images(template_source=blueprint.prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,template_category=TemplateCategory.IMG_GEN_PROMPT,)@@ -75,7 +77,7 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):if blueprint.negative_prompt:negative_refs = TemplateImageAnalyzer.analyze_template_for_images(template_source=blueprint.negative_prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,template_category=TemplateCategory.IMG_GEN_PROMPT,)diff --git a/pipelex/pipe_operators/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.pyindex f1dbbc209..c457a6411 100644--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py@@ -68,13 +68,16 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):)raise PipeLLMFactoryError(error_msg) from exc+ # Template analyzers read the slot grammar only, so they get the concept-spec projection.+ blueprint_input_specs = blueprint.inputs_concept_specs or {}+# Analyze template for image referencesuser_image_references = Noneif blueprint.prompt and blueprint.inputs:user_image_references = (TemplateImageAnalyzer.analyze_template_for_images(template_source=blueprint.prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,)or None@@ -86,7 +89,7 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):user_document_references = (TemplateDocumentAnalyzer.analyze_template_for_documents(template_source=blueprint.prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,)or None@@ -98,7 +101,7 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):system_image_references = (TemplateImageAnalyzer.analyze_template_for_images(template_source=blueprint.system_prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,)or None@@ -110,7 +113,7 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):system_document_references = (TemplateDocumentAnalyzer.analyze_template_for_documents(template_source=blueprint.system_prompt,- input_specs=blueprint.inputs,+ input_specs=blueprint_input_specs,domain_code=domain_code,)or Nonediff --git a/pipelex/pipe_operators/structure/pipe_structure_blueprint.py b/pipelex/pipe_operators/structure/pipe_structure_blueprint.pyindex 8a5d697c7..3435ebb52 100644--- a/pipelex/pipe_operators/structure/pipe_structure_blueprint.py+++ b/pipelex/pipe_operators/structure/pipe_structure_blueprint.py@@ -29,7 +29,7 @@ class PipeStructureBlueprint(PipeBlueprint):# input via `working_memory.get_stuff_as_str`, which expects a single TextContent and# would otherwise crash on a ListContent with an opaque error. Users with a list of# texts should wrap PipeStructure in a PipeBatch.- input_name, input_concept_spec = next(iter((self.inputs or {}).items()))+ input_name, input_concept_spec = next(iter((self.inputs_concept_specs or {}).items()))input_parse_result = parse_concept_with_multiplicity(input_concept_spec)if input_parse_result.multiplicity is not None:msg = (diff --git a/pipelex/pipeline/hint_warnings.py b/pipelex/pipeline/hint_warnings.pynew file mode 100644index 000000000..fd19733cd--- /dev/null+++ b/pipelex/pipeline/hint_warnings.py@@ -0,0 +1,299 @@+"""Advisory intent-hints lints (`warnings`) for the validate surfaces (spec: intent-hints.md).++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`.++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;+refinement chains reaching `native.Text` / `native.Number` classify the refiner; plural sites are+judged per item). A site that is neither takes no word of this version.+"""++from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+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,+ HintSiteValueKind,+ IntentWord,+ intent_word_applies,+ is_intent_word_known,+)+from pipelex.libraries.crate_qualification import QualifiedCrateContent, qualify_crate+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+++def _native_class_value_kind(*, class_name: str) -> HintSiteValueKind:+ """The value kind of a class-backed structure, by native-class identity.++ Mirrors the deriver's `_class_backed_node` lookup: `TextContent` is the native Text payload+ (text-valued), `NumberContent` the native Number payload (number-valued). Every other class —+ the remaining natives and registered project classes alike — is not a hint-applicable site.+ """+ native_code = next((code for code in NativeConceptCode if code.structure_class_name == class_name), None)+ match native_code:+ case NativeConceptCode.TEXT:+ return HintSiteValueKind.TEXT_VALUED+ case NativeConceptCode.NUMBER:+ return HintSiteValueKind.NUMBER_VALUED+ case (+ NativeConceptCode.DYNAMIC+ | NativeConceptCode.IMAGE+ | NativeConceptCode.DOCUMENT+ | NativeConceptCode.HTML+ | NativeConceptCode.TEXT_AND_IMAGES+ | NativeConceptCode.YES_NO+ | NativeConceptCode.DATE+ | NativeConceptCode.TIME+ | NativeConceptCode.PAGE+ | NativeConceptCode.JSON+ | NativeConceptCode.SEARCH_RESULT+ | NativeConceptCode.ANYTHING+ | NativeConceptCode.COMPOSITE+ | None+ ):+ 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.++ Args:+ qualified: The qualified crate content (in-body refs resolved, so concept classification+ can follow refinement chains by qualified key).++ Returns:+ Advisory items in deterministic order: concepts (by qualified ref, fields in authored+ order), then pipes (by qualified ref, slots in authored order).+ """+ linter = _HintLinter(qualified=qualified)+ return linter.lint()+++class _HintLinter:+ def __init__(self, *, qualified: QualifiedCrateContent) -> None:+ self._concepts = qualified.concepts+ self._pipes = qualified.pipes+ self._concept_kind_cache: dict[str, HintSiteValueKind] = {}++ def lint(self) -> list[ValidationErrorItem]:+ warnings: list[ValidationErrorItem] = []+ for concept_ref in sorted(self._concepts):+ value = self._concepts[concept_ref]+ if not isinstance(value, ConceptBlueprint):+ continue+ domain_code, concept_code = self._split_ref(concept_ref)+ if value.hints:+ warnings.extend(+ self._lint_hints(+ hints=value.hints,+ site_kind=self._concept_site_kind(concept_ref),+ site_desc=f"concept '{concept_ref}'",+ domain_code=domain_code,+ concept_code=concept_code,+ )+ )+ if isinstance(value.structure, dict):+ for field_name, field in value.structure.items():+ if isinstance(field, ConceptStructureBlueprint) and field.hints:+ warnings.extend(+ self._lint_hints(+ hints=field.hints,+ site_kind=self._field_site_kind(field),+ site_desc=f"field '{field_name}' of concept '{concept_ref}'",+ domain_code=domain_code,+ concept_code=concept_code,+ field_name=field_name,+ )+ )+ for pipe_ref in sorted(self._pipes):+ blueprint = self._pipes[pipe_ref]+ if not blueprint.inputs:+ continue+ domain_code, pipe_code = self._split_ref(pipe_ref)+ for slot_name, slot_value in blueprint.inputs.items():+ if isinstance(slot_value, InputSlotBlueprint) and slot_value.hints:+ warnings.extend(+ self._lint_hints(+ hints=slot_value.hints,+ site_kind=self._slot_site_kind(slot_value.concept),+ site_desc=f"input '{slot_name}' of pipe '{pipe_ref}'",+ domain_code=domain_code,+ pipe_code=pipe_code,+ variable_names=[slot_name],+ )+ )+ return warnings++ # ---- Per-site linting -------------------------------------------------------------------------++ def _lint_hints(+ self,+ *,+ hints: dict[str, str],+ site_kind: HintSiteValueKind,+ site_desc: str,+ domain_code: str,+ concept_code: str | None = None,+ pipe_code: str | None = None,+ field_name: str | None = None,+ 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))+ 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"(prose, label, rating, quantity). The entry is preserved; consumers ignore it."+ )+ findings.append((HintLintErrorType.HINT_UNKNOWN_INTENT, unknown_intent_message))+ elif not intent_word_applies(known_word := IntentWord(intent_word), site_kind=site_kind):+ match known_word:+ case IntentWord.PROSE | IntentWord.LABEL:+ needed_kind = "text"+ 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"{needed_kind}-valued). The entry is preserved; consumers ignore it there."+ )+ findings.append((HintLintErrorType.HINT_INAPPLICABLE_INTENT, inapplicable_message))+ return [+ ValidationErrorItem(+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,+ error_type=error_type,+ message=message,+ domain_code=domain_code,+ concept_code=concept_code,+ pipe_code=pipe_code,+ field_name=field_name,+ variable_names=variable_names,+ )+ for error_type, message in findings+ ]++ # ---- Site classification (spec: Applicability) ------------------------------------------------++ def _concept_site_kind(self, concept_ref: str) -> HintSiteValueKind:+ if concept_ref in self._concept_kind_cache:+ return self._concept_kind_cache[concept_ref]+ kind = self._resolve_concept_kind(concept_ref, seen=set())+ self._concept_kind_cache[concept_ref] = kind+ return kind++ def _resolve_concept_kind(self, concept_ref: str, *, seen: set[str]) -> HintSiteValueKind:+ # Iterative on purpose, like every other chain walker (`_resolve_refinement`,+ # `_refines_chain`): a legal, arbitrarily deep refinement chain must not be able to+ # RecursionError an advisory lint out of the validate call.+ current_ref = concept_ref+ while True:+ if current_ref in seen:+ return HintSiteValueKind.OTHER # defensive: cycles are rejected upstream+ seen.add(current_ref)+ if NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=current_ref):+ native_ref = NativeConceptCode.get_validated_native_concept_ref(concept_ref_or_code=current_ref)+ if native_ref == _NATIVE_TEXT_REF:+ return HintSiteValueKind.TEXT_VALUED+ if native_ref == _NATIVE_NUMBER_REF:+ return HintSiteValueKind.NUMBER_VALUED+ return HintSiteValueKind.OTHER+ value = self._concepts.get(current_ref)+ if isinstance(value, str):+ # String-described concept: description-only, hence text-valued.+ return HintSiteValueKind.TEXT_VALUED+ if not isinstance(value, ConceptBlueprint):+ # Cross-package or unknown: not classifiable in-crate.+ return HintSiteValueKind.OTHER+ if value.refines:+ current_ref = value.refines+ continue+ if value.structure is None:+ # Description-only concepts are text-valued per the spec.+ return HintSiteValueKind.TEXT_VALUED+ if isinstance(value.structure, str):+ # Class-backed: a native class name maps by identity to its native's value kind,+ # mirroring the input-form deriver's judgment for resolvable sites (the known+ # divergences are recorded in wip/engine-hints/deferred.md). Any other registered+ # class is an object payload, hence OTHER.+ return _native_class_value_kind(class_name=value.structure)+ return HintSiteValueKind.OTHER++ def _field_site_kind(self, field: ConceptStructureBlueprint) -> HintSiteValueKind:+ if field.choices:+ # Choices dominate the declared type (the deriver and the structure generator agree):+ # the payload is an enum, which no intent word applies to.+ return HintSiteValueKind.OTHER+ match field.type:+ case ConceptStructureBlueprintFieldType.TEXT:+ return HintSiteValueKind.TEXT_VALUED+ case ConceptStructureBlueprintFieldType.INTEGER | ConceptStructureBlueprintFieldType.NUMBER:+ return HintSiteValueKind.NUMBER_VALUED+ case ConceptStructureBlueprintFieldType.CONCEPT:+ return self._concept_site_kind(field.concept_ref) if field.concept_ref else HintSiteValueKind.OTHER+ case ConceptStructureBlueprintFieldType.LIST:+ # Plural site: judged against the item as if it stood alone.+ match field.item_type:+ case ConceptStructureBlueprintFieldType.TEXT:+ return HintSiteValueKind.TEXT_VALUED+ case ConceptStructureBlueprintFieldType.INTEGER | ConceptStructureBlueprintFieldType.NUMBER:+ return HintSiteValueKind.NUMBER_VALUED+ case ConceptStructureBlueprintFieldType.CONCEPT:+ return self._concept_site_kind(field.item_concept_ref) if field.item_concept_ref else HintSiteValueKind.OTHER+ case _:+ # item_type is a free string on the blueprint; anything unrecognized is OTHER.+ return HintSiteValueKind.OTHER+ case (+ ConceptStructureBlueprintFieldType.DICT+ | ConceptStructureBlueprintFieldType.BOOLEAN+ | ConceptStructureBlueprintFieldType.DATE+ | ConceptStructureBlueprintFieldType.DATETIME+ | ConceptStructureBlueprintFieldType.TIME+ | None+ ):+ # No type (choices-only), dict, boolean, date/datetime/time: neither text- nor number-valued.+ return HintSiteValueKind.OTHER++ def _slot_site_kind(self, concept_spec: str) -> HintSiteValueKind:+ # Multiplicity is a plural site judged per item, and the item is the slot's concept —+ # so the markers simply strip away.+ parsed = parse_concept_with_multiplicity(concept_spec)+ return self._concept_site_kind(parsed.concept_ref_or_code)++ @staticmethod+ def _split_ref(qualified_ref: str) -> tuple[str, str]:+ parsed = QualifiedRef.parse(qualified_ref)+ return parsed.domain_path or "", parsed.local_codediff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.pyindex 8000d9ef3..c0b107f10 100644--- a/pipelex/pipeline/input_form.py+++ b/pipelex/pipeline/input_form.py@@ -26,7 +26,7 @@ library's window, beside `build_pipe_io_contracts`: class-backed reflection readregistry, and bundle-defined classes are only reliably current while their library is loaded."""-from collections.abc import Sequence+from collections.abc import Mapping, Sequencefrom enum import StrEnumfrom typing import Any@@ -43,9 +43,11 @@ from pipelex.core.concepts.native.pinned_blueprints import make_pinned_native_blfrom pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpecfrom pipelex.core.pipes.variable_multiplicity import PresenceMarkerfrom pipelex.interpreter_hub import get_current_library, get_library_manager+from pipelex.language.intent_hints import HintSiteValueKind, IntentWord, applicable_intent, merge_hintsfrom pipelex.libraries.crate_qualification import qualify_cratefrom pipelex.libraries.library_crate_factory import LibraryCrateFactoryfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstract+from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprintfrom pipelex.system.registries.class_registry_access import get_class_registry@@ -128,8 +130,11 @@ class InputFormField(BaseModel):never the emission's `null`-for-optional artifact. May sit beside `required: true`."""examples: list[Any] | None = None- hints: dict[str, Any] | None = None- """Reserved for MTHDS intent hints; vocabulary deliberately undesigned here."""+ hints: dict[str, str] | None = None+ """The node's effective MTHDS intent hints (spec: intent-hints.md): the key-by-key merge of the+ concept's refinement chain and the site's own hints, nearer/site layer winning. Flat+ string-to-string by contract. Everything well-formed rides here, unknown entries included; an+ applicable `intent` word additionally feeds `kind` (never competes with it)."""# `text` / `prose` constraint slots.min_length: int | None = None@@ -212,14 +217,28 @@ def build_input_form(pipes: Sequence[PipeAbstract]) -> dict[str, PipeInputFormDe`pipe_ref` → `PipeInputFormDescriptor` for every given pipe."""crate = get_library_manager().get_crate(library_id=get_current_library()) or LibraryCrateFactory.make_from_blueprints([])- deriver = InputFormDeriver(concepts=qualify_crate(crate).concepts)+ qualified = qualify_crate(crate)+ deriver = InputFormDeriver(concepts=qualified.concepts)input_form: dict[str, PipeInputFormDescriptor] = {}for pipe in pipes:- fields = [deriver.derive_slot(name=var_name, stuff_spec=stuff_spec) for var_name, stuff_spec in pipe.inputs.root.items()]+ # Slot hints come from the qualified blueprint, not the runtime spec: `StuffSpec` stays+ # hint-free by design (structural non-normativity). A pipe with no blueprint in the crate+ # (the fallback path) derives with no hints.+ blueprint = qualified.pipes.get(pipe.pipe_ref)+ blueprint_inputs: Mapping[str, str | InputSlotBlueprint] = blueprint.inputs if blueprint is not None and blueprint.inputs else {}+ fields = [+ deriver.derive_slot(name=var_name, stuff_spec=stuff_spec, slot_hints=_slot_hints_of(blueprint_inputs.get(var_name)))+ for var_name, stuff_spec in pipe.inputs.root.items()+ ]input_form[pipe.pipe_ref] = PipeInputFormDescriptor(fields=fields)return input_form+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++class InputFormDeriver:"""Derives field descriptors over one qualified crate's concepts (`QualifiedCrateContent.concepts`)."""@@ -228,12 +247,20 @@ class InputFormDeriver:# ---- Pipe slots -------------------------------------------------------------------------------- def derive_slot(self, *, name: str, stuff_spec: StuffSpec) -> InputFormField:- """A top-level field: the concept node, list-wrapped when multiple, stamped with slot facts."""+ def derive_slot(self, *, name: str, stuff_spec: StuffSpec, slot_hints: dict[str, str] | None = None) -> InputFormField:+ """A top-level field: the concept node, list-wrapped when multiple, stamped with slot facts.++ `slot_hints` are the slot's authored hints from the qualified blueprint; the site-over-concept+ merge happens here (the concept node already carries the concept's effective hints).+ """node = self._concept_node(name=name, concept_ref=stuff_spec.concept.concept_ref, seen=frozenset())+ effective_hints = merge_hints([node.hints, slot_hints])if stuff_spec.is_multiple():multiplicity = stuff_spec.multiplicityitem_count = multiplicity if isinstance(multiplicity, int) and not isinstance(multiplicity, bool) else None+ # A plural slot's merged hints ride the `list` node AND its `item` (the `concept_ref`+ # duplication precedent): applicability is judged per item, and a renderer reading+ # either node finds the same answer.node = InputFormField(kind=FieldKind.LIST,name=name,@@ -241,9 +268,12 @@ class InputFormDeriver:refines=node.refines,description=node.description,required=True,- item=node,+ hints=effective_hints,+ item=_with_effective_hints(node=node, hints=effective_hints),item_count=item_count,)+ else:+ node = _with_effective_hints(node=node, hints=effective_hints)presence = stuff_spec.presencerequired = not presence.is_optionalgating = required and not (node.kind.is_list and node.item_count is None)@@ -253,7 +283,8 @@ class InputFormDeriver:def derive_concept(self, *, name: str, concept_ref: str) -> InputFormField:"""The descriptor of a concept-typed node on its own, with no pipe-slot facts."""- return self._concept_node(name=name, concept_ref=concept_ref, seen=frozenset())+ node = self._concept_node(name=name, concept_ref=concept_ref, seen=frozenset())+ return _with_effective_hints(node=node, hints=node.hints)def _concept_node(self, *, name: str, concept_ref: str, seen: frozenset[str]) -> InputFormField:"""The descriptor of a concept-typed node (no slot facts); `seen` is the concept-ref path."""@@ -273,6 +304,26 @@ class InputFormDeriver:def _blueprint_node(self, *, name: str, concept_ref: str, blueprint: ConceptBlueprint, seen: frozenset[str]) -> InputFormField:chain = self._refines_chain(concept_ref=concept_ref)+ node = self._blueprint_node_for_chain(name=name, concept_ref=concept_ref, blueprint=blueprint, chain=chain, seen=seen)+ # The concept's effective hints: its refinement chain merged nearer-wins, computed with the+ # same `_refines_chain` walk the structure merge uses. Carried on the node WITHOUT feeding+ # `kind` yet: this node may still receive a site layer (a slot's or a field's hints), and+ # the kind flip must read the final merge — see `_with_effective_hints` at the terminals.+ effective_hints = self._effective_hints(concept_ref=concept_ref, chain=chain)+ return node.model_copy(update={"hints": effective_hints}) if effective_hints else node++ def _effective_hints(self, *, concept_ref: str, chain: list[str]) -> dict[str, str] | None:+ """The concept's effective hints along its refinement chain (natives contribute nothing)."""+ layers: list[dict[str, str] | None] = []+ for ref in [*reversed(chain), concept_ref]:+ entry = self._concepts.get(ref)+ if isinstance(entry, ConceptBlueprint):+ layers.append(entry.hints)+ return merge_hints(layers)++ def _blueprint_node_for_chain(+ self, *, name: str, concept_ref: str, blueprint: ConceptBlueprint, chain: list[str], seen: frozenset[str]+ ) -> InputFormField:refines = chain or Nonemerged_structure = self._merged_structure(concept_ref=concept_ref, chain=chain)if merged_structure:@@ -423,12 +474,17 @@ class InputFormDeriver:# ---- Structure fields -------------------------------------------------------------------------def _structure_field(self, *, name: str, field: ConceptStructureBlueprintType, seen: frozenset[str]) -> InputFormField:- """A nested field from its structure blueprint: authored facts only, never slot facts."""+ """A nested field from its structure blueprint: authored facts only, never slot facts.++ A field is a terminal hint site: the field's own hints merge over the referenced concept's+ effective hints (concept-typed and concept-item fields only — scalar fields have no concept+ layer), and the final merge is stamped here, feeding `kind` where applicable.+ """if isinstance(field, str):# The shorthand `field = "description"` form declares a required text field.return InputFormField(kind=FieldKind.TEXT, name=name, description=field, required=True)if field.choices:- return InputFormField(+ enum_node = InputFormField(kind=FieldKind.ENUM,name=name,description=field.description,@@ -436,14 +492,19 @@ class InputFormDeriver:choices=list(field.choices),default_value=field.default_value,)+ return _with_effective_hints(node=enum_node, hints=field.hints)match field.type:case ConceptStructureBlueprintFieldType.CONCEPT:if field.concept_ref is None:return _unknown_node(name=name, description=field.description, required=field.required)node = self._concept_node(name=name, concept_ref=field.concept_ref, seen=seen)+ node = _with_effective_hints(node=node, hints=merge_hints([node.hints, field.hints]))return node.model_copy(update={"description": field.description, "required": field.required})case ConceptStructureBlueprintFieldType.LIST:item = self._list_item(name=name, field=field, seen=seen)+ # The merged hints ride the `list` node AND its `item` (the `concept_ref`+ # duplication precedent); a concept item already carries its concept layer.+ effective_hints = merge_hints([item.hints, field.hints])return InputFormField(kind=FieldKind.LIST,name=name,@@ -452,10 +513,12 @@ class InputFormDeriver:description=field.description,required=field.required,default_value=field.default_value,- item=item,+ hints=effective_hints,+ item=_with_effective_hints(node=item, hints=effective_hints),)case ConceptStructureBlueprintFieldType.DICT | None:- return _unknown_node(name=name, description=field.description, required=field.required, default_value=field.default_value)+ unknown = _unknown_node(name=name, description=field.description, required=field.required, default_value=field.default_value)+ return _with_effective_hints(node=unknown, hints=field.hints)case (ConceptStructureBlueprintFieldType.TEXT| ConceptStructureBlueprintFieldType.INTEGER@@ -465,9 +528,10 @@ class InputFormDeriver:| ConceptStructureBlueprintFieldType.DATETIME| ConceptStructureBlueprintFieldType.TIME):- return _scalar_field(+ scalar = _scalar_field(field_type=field.type, name=name, description=field.description, required=field.required, default_value=field.default_value)+ return _with_effective_hints(node=scalar, hints=field.hints)def _list_item(self, *, name: str, field: ConceptStructureBlueprint, seen: frozenset[str]) -> InputFormField:"""The element node of a list field; the inner type of a nested list is inexpressible in the blueprint."""@@ -495,6 +559,60 @@ class InputFormDeriver:return _scalar_field(field_type=item_type, name=name, required=True)+def _with_effective_hints(*, node: InputFormField, hints: dict[str, str] | None) -> InputFormField:+ """Stamp a node's FINAL effective hints; an applicable `intent` word feeds `kind`, never competes.++ Call exactly once per node, at the terminal where the full merge is known (slot, field, or bare+ concept). `node.kind` is still the no-hint default there, so an absent, unknown, or inapplicable+ intent leaves it untouched — and `rating` / `quantity` never change `kind` at all (both map to+ `number`; the union has no finer kind). Inapplicable and unknown content still rides the slot as+ preserved content (the advisory lint already warned).+ """+ if not hints:+ return node+ updates: dict[str, Any] = {"hints": hints}+ match applicable_intent(hints, site_kind=_node_site_kind(node)):+ case IntentWord.PROSE:+ updates["kind"] = FieldKind.PROSE+ case IntentWord.LABEL:+ updates["kind"] = FieldKind.TEXT+ case IntentWord.RATING | IntentWord.QUANTITY | None:+ pass+ return node.model_copy(update=updates)+++def _node_site_kind(node: InputFormField) -> HintSiteValueKind:+ """The node's site value-kind for intent applicability (spec: intent-hints.md, Applicability).++ Recomputed from node facts, mirroring the lint's structural judgment (the known divergences are+ recorded in wip/engine-hints/deferred.md): `number` nodes come only from `integer`/`number`+ fields and `native.Number` chains, so the kind IS the judgment; `text`/`prose` nodes are+ text-valued EXCEPT a time-formatted text (`type = "time"` is neither) and an `Html`-backed node+ (`prose` presentation, but the chain reaches `native.Html`, not `native.Text`).+ """+ match node.kind:+ case FieldKind.NUMBER:+ return HintSiteValueKind.NUMBER_VALUED+ case FieldKind.TEXT | FieldKind.PROSE:+ if node.format is not None:+ return HintSiteValueKind.OTHER+ html_ref = NativeConceptCode.HTML.concept_ref+ if node.concept_ref == html_ref or (node.refines is not None and html_ref in node.refines):+ return HintSiteValueKind.OTHER+ return HintSiteValueKind.TEXT_VALUED+ case (+ FieldKind.DATE+ | FieldKind.BOOLEAN+ | FieldKind.ENUM+ | FieldKind.DOCUMENT+ | FieldKind.IMAGE+ | FieldKind.OBJECT+ | FieldKind.LIST+ | FieldKind.UNKNOWN+ ):+ return HintSiteValueKind.OTHER++def _scalar_field(*,field_type: ConceptStructureBlueprintFieldType,diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.pyindex 2efacee3d..3cddca5f7 100644--- a/pipelex/pipeline/validate_in_process.py+++ b/pipelex/pipeline/validate_in_process.py@@ -29,6 +29,7 @@ from pipelex.interpreter_hub import clear_current_library, get_current_library_ifrom pipelex.pipe_run.dry_run_in_process import best_effort_graph_specfrom pipelex.pipeline.blueprint_selection import select_primary_blueprintfrom pipelex.pipeline.controller_taint import collect_controller_taint_analyses+from pipelex.pipeline.hint_warnings import build_current_library_hint_warningsfrom pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_formfrom pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pipesfrom pipelex.pipeline.optionality_warnings import build_optionality_warnings@@ -111,7 +112,7 @@ async def validate_bundles_in_process(# 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)+ warnings: list[ValidationErrorItem] = build_optionality_warnings(taint_analyses) + build_current_library_hint_warnings()graph_target_ref = graph_pipe_code if graph_pipe_code is not None else select_primary_blueprint(result.blueprints).main_pipe_refgraph_spec: GraphSpec | None = await best_effort_graph_spec(pipe_ref=graph_target_ref,diff --git a/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/bundle.mthds b/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/bundle.mthdsnew file mode 100644index 000000000..a60e4ffba--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/bundle.mthds@@ -0,0 +1,28 @@+domain = "reading_circle"+description = "Writing the monthly reading-circle card, with presentation intent stated where it helps a form"+main_pipe = "write_card"++[concept.BookTitle]+description = "The title of the book under discussion"+hints = { intent = "label" }++[concept.CircleCard]+description = "The card pinned up for the month's reading circle"++[concept.CircleCard.structure]+headline = { type = "text", description = "the card's headline", hints = { intent = "label" }, required = true }+blurb = { type = "text", description = "a short blurb inviting people in", hints = { intent = "prose" } }+seats = { type = "integer", description = "how many seats the room holds", hints = { intent = "quantity" } }++[pipe.write_card]+type = "PipeLLM"+description = "Writes the circle card from the title and the host's notes"+inputs = { title = "BookTitle", notes = { concept = "Text", hints = { intent = "prose" } } }+output = "CircleCard"+prompt = """+Write the reading-circle card for this book:+@title++Host's notes:+@notes+"""diff --git a/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/entry.toml b/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/entry.tomlnew file mode 100644index 000000000..213803229--- /dev/null+++ b/pipelex/test_extras/mthds_corpus/entries/feature_intent_hints_reading_circle/entry.toml@@ -0,0 +1,10 @@+name = "feature_intent_hints_reading_circle"+description = "A reading-circle card written from a hinted brief — intent hints authored at all three sites"++validity = "valid"+tier = "dry"+granularity = "focused"++covers = [+ "feature.intent_hints",+]diff --git a/pipelex/test_extras/mthds_corpus/vocabulary.toml b/pipelex/test_extras/mthds_corpus/vocabulary.tomlindex 89ac417b6..a0d8c0120 100644--- a/pipelex/test_extras/mthds_corpus/vocabulary.toml+++ b/pipelex/test_extras/mthds_corpus/vocabulary.toml@@ -189,6 +189,21 @@ excluded = "The generic fallback for a pipe-construction failure that matched nocode = "DryRunError"fails_at = "runtime"+[error.hint_unknown_key]+code = "hint_unknown_key"+excluded = "Advisory-only: the intent-hints lint rides the validation report's `warnings` array and never makes a verdict invalid (hints are non-normative; well-formed unknown content is preserved). Same shape problem as `optional_force_redundant`: an entry contract keyed on `expected_error` has nowhere to put a warning on a valid entry. Revisit if the manifest ever grows a warnings axis."++[error.hint_unknown_intent]+code = "hint_unknown_intent"+excluded = "Advisory-only: the intent-hints lint rides the validation report's `warnings` array and never makes a verdict invalid (hints are non-normative; well-formed unknown content is preserved). Same shape problem as `optional_force_redundant`: an entry contract keyed on `expected_error` has nowhere to put a warning on a valid entry. Revisit if the manifest ever grows a warnings axis."++[error.hint_inapplicable_intent]+code = "hint_inapplicable_intent"+excluded = "Advisory-only: the intent-hints lint rides the validation report's `warnings` array and never makes a verdict invalid (hints are non-normative; well-formed unknown content is preserved). Same shape problem as `optional_force_redundant`: an entry contract keyed on `expected_error` has nowhere to put a warning on a valid entry. Revisit if the manifest ever grows a warnings axis."++[feature.intent_hints]+description = "An `intent` hint authored in a `hints` table — on a concept, a structure field, or an expanded input slot — carrying non-normative presentation intent (`prose`, `label`, `rating`, `quantity`) that renderers may honor and every other consumer safely ignores."+[feature.multi_file_library]description = "A method split across several `.mthds` files in one directory and merged additively behind a `bundle.mthds` entry point, so a pipe can be forward-declared as a signature in one file and satisfied by a concrete definition in another."diff --git a/pipelex/validation_error_types.py b/pipelex/validation_error_types.pyindex ec32fb342..93f9a519c 100644--- a/pipelex/validation_error_types.py+++ b/pipelex/validation_error_types.py@@ -282,7 +282,25 @@ class ValidationResidualErrorType(StrEnum):DRY_RUN_ERROR = "DryRunError"-ValidationErrorType: TypeAlias = PipeValidationErrorType | PipeFactoryErrorType | ValidationResidualErrorType+class HintLintErrorType(StrEnum):+ """Advisory intent-hints lint findings (spec: intent-hints.md).++ Every member is advisory-only: it rides the validation report's ``warnings`` array and never+ makes a verdict invalid — hints are non-normative, and well-formed unknown content is+ preserved, only warned about. A separate enum rather than new ``PipeValidationErrorType``+ members because hints attach to concepts and structure fields too, so the pipe enum is the+ wrong home.+ """++ # A hint key the pinned standard version does not define (only `intent` exists today).+ HINT_UNKNOWN_KEY = "hint_unknown_key"+ # An `intent` value outside the closed vocabulary (`prose`, `label`, `rating`, `quantity`).+ HINT_UNKNOWN_INTENT = "hint_unknown_intent"+ # A known `intent` word on a site it does not apply to (e.g. `rating` on a text-valued site).+ HINT_INAPPLICABLE_INTENT = "hint_inapplicable_intent"+++ValidationErrorType: TypeAlias = PipeValidationErrorType | PipeFactoryErrorType | ValidationResidualErrorType | HintLintErrorType"""The type of a bundle-validation diagnostic's ``error_type``.``ValidationErrorItem.error_type`` is typed against this alias, which is what makes the registry@@ -295,6 +313,7 @@ VALIDATION_ERROR_TYPES: tuple[ValidationErrorType, ...] = (*PipeValidationErrorType,*PipeFactoryErrorType,*ValidationResidualErrorType,+ *HintLintErrorType,)"""Every ``error_type`` a bundle-validation diagnostic can carry, in a deterministic order.diff --git a/subject_grants.toml b/subject_grants.tomlindex 1c1be17ca..851217bd1 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -3500,6 +3500,22 @@ rationale = "Verb-object: the repo root being cleaned; options stay keyword."param = "repo_root"rationale = "Verb-object: the repo root being updated; options stay keyword."+["pipelex/language/intent_hints.py::applicable_intent"]+param = "hints"+rationale = "Verb-object read: applicable_intent(hints) judges the hints table, the single obvious operand."++["pipelex/language/intent_hints.py::intent_word_applies"]+param = "word"+rationale = "Predicate on its single operand: intent_word_applies(word), the site kind being a keyword modifier."++["pipelex/language/intent_hints.py::is_intent_word_known"]+param = "word"+rationale = "Predicate on its single operand: is_intent_word_known(word)."++["pipelex/language/intent_hints.py::merge_hints"]+param = "layers"+rationale = "Verb-object read: merge_hints(layers) merges the hint layers, the single obvious operand."+["pipelex/language/mthds_factory.py::MthdsFactory.add_spaces_to_inline_tables"]param = "toml_string"rationale = "Verb-object: transforms the TOML string; single operand."@@ -3676,6 +3692,10 @@ rationale = "Single-operand qualification of the pipe blueprint; owner_domain isparam = "pipe_ref"rationale = "Single-operand transformation of the ref; domain is context."+["pipelex/libraries/crate_qualification.py::_qualify_slot_value"]+param = "slot_value"+rationale = "Verb-object read, matching sibling _qualify_io_ref: qualifies the one slot value."+["pipelex/libraries/crate_qualification.py::_qualify_structure_field"]param = "field_blueprint"rationale = "Single-operand transformation of the field blueprint; domain is context."@@ -4052,6 +4072,10 @@ rationale = "Predicate on the category string; single operand."param = "pipe_code"rationale = "Noun-named derivation: the migration message for the given pipe code; single operand."+["pipelex/pipe_machinery/pipe_blueprint.py::slot_concept_spec"]+param = "slot_value"+rationale = "Verb-object read: slot_concept_spec(slot_value) projects the one slot value to its concept spec string."+["pipelex/pipe_machinery/rendering/input_renderer.py::_delighten_entry"]param = "entry"rationale = "Single-operand transformation of the entry; kind is a mode and stays keyword."@@ -4552,6 +4576,38 @@ rationale = "Verb-object: plans the fix for the error data; single operand."param = "error_data"rationale = "Verb-object: plans the fix for the error data; single operand."+["pipelex/pipeline/hint_warnings.py::_HintLinter._concept_site_kind"]+param = "concept_ref"+rationale = "Verb-object read with a single obvious operand: the site or ref being classified/linted."++["pipelex/pipeline/hint_warnings.py::_HintLinter._field_site_kind"]+param = "field"+rationale = "Verb-object read with a single obvious operand: the site or ref being classified/linted."++["pipelex/pipeline/hint_warnings.py::_HintLinter._resolve_concept_kind"]+param = "concept_ref"+rationale = "Verb-object read with a single obvious operand: the site or ref being classified/linted."++["pipelex/pipeline/hint_warnings.py::_HintLinter._slot_site_kind"]+param = "concept_spec"+rationale = "Verb-object read with a single obvious operand: the site or ref being classified/linted."++["pipelex/pipeline/hint_warnings.py::_HintLinter._split_ref"]+param = "qualified_ref"+rationale = "Verb-object read with a single obvious operand: the site or ref being classified/linted."++["pipelex/pipeline/hint_warnings.py::build_hint_warnings"]+param = "qualified"+rationale = "Verb-object read with one obvious operand: the qualified crate content being swept."++["pipelex/pipeline/input_form.py::_node_site_kind"]+param = "node"+rationale = "Verb-object read: the node whose site value-kind is judged."++["pipelex/pipeline/input_form.py::_slot_hints_of"]+param = "slot_value"+rationale = "Verb-object read: the slot value whose hints are extracted."+["pipelex/pipeline/input_form.py::build_input_form"]param = "pipes"rationale = "Reads as a verb-object sentence over the loaded pipes, mirroring build_pipe_io_contracts."diff --git a/tests/data/input_semantics/hinted_bundle.mthds b/tests/data/input_semantics/hinted_bundle.mthdsnew file mode 100644index 000000000..69be9e233--- /dev/null+++ b/tests/data/input_semantics/hinted_bundle.mthds@@ -0,0 +1,42 @@+domain = "input_semantics_hinted"+description = "HINTED probe: sibling of probe_bundle exercising intent hints at all three sites — keep probe_bundle.mthds hint-free forever (its fingerprints are pinned)"+main_pipe = "hinted_slots"++[concept.Essay]+description = "HINTED_concept_Essay: description-only concept carrying a concept-level hint"+hints = { intent = "prose" }++[concept.Badge]+description = "HINTED_concept_Badge: base of a hinted refinement chain"+hints = { intent = "label" }++[concept.SpecialBadge]+description = "HINTED_concept_SpecialBadge: refines Badge and overrides the inherited intent"+refines = "Badge"+hints = { intent = "prose" }++[concept.PlainBadge]+description = "HINTED_concept_PlainBadge: refines Badge with no hints of its own — inherits the base's"+refines = "Badge"++[concept.Review]+description = "HINTED_concept_Review: structured concept with field-level hints"++[concept.Review.structure]+headline = { type = "text", description = "HINTED_field_headline: text field hinted as a label", hints = { intent = "label" } }+body = { type = "text", description = "HINTED_field_body: text field hinted as prose", required = true, hints = { intent = "prose" } }+stars = { type = "integer", description = "HINTED_field_stars: integer field hinted as a rating", hints = { intent = "rating" } }+plain = { type = "text", description = "HINTED_field_plain: hint-free field beside hinted ones" }+quirk = { type = "text", description = "HINTED_field_quirk: field carrying an unknown hint key (content-lenient, preserved)", hints = { emphasis = "HINTED_unknown_value" } }++[pipe.hinted_slots]+type = "PipeLLM"+description = "HINTED_pipe_hinted_slots: every slot spelling — plain string, collapsing table, hinted table, hinted table with markers"+inputs = { plain = "Essay", expanded_plain = { concept = "Essay" }, hinted = { concept = "Review", hints = { intent = "prose" } }, hinted_marked = { concept = "Badge[]", hints = { intent = "label" } } }+output = "Text"+prompt = """+@plain+@expanded_plain+@hinted+@hinted_marked+"""diff --git a/tests/data/input_semantics/rejected/per_input_description.mthds_invalid b/tests/data/input_semantics/rejected/per_input_description.mthds_invalidindex 71151eea6..7a97f72ff 100644--- a/tests/data/input_semantics/rejected/per_input_description.mthds_invalid+++ b/tests/data/input_semantics/rejected/per_input_description.mthds_invalid@@ -1,5 +1,5 @@domain = "input_semantics_rejected"-description = "REJECTED probe: a pipe input slot cannot carry its own description — inputs values are ref strings only"+description = "REJECTED probe: a pipe input slot cannot carry its own description — the expanded slot table admits only concept and hints, so description is an unknown slot-table key"[pipe.annotated_inputs]type = "PipeLLM"diff --git a/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py b/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.pyindex c929bee5f..c15e0a454 100644--- a/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py+++ b/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py@@ -2,10 +2,12 @@ import tempfilefrom collections.abc import Callablefrom pathlib import Path+from pipelex.core.concepts.concept_blueprint import ConceptBlueprintfrom pipelex.interpreter_hub import get_library_managerfrom pipelex.libraries.crate_normalization import normalize_cratefrom pipelex.libraries.library_crate_factory import LibraryCrateFactoryfrom pipelex.mthds_parsing.parser import MthdsParser+from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprintMTHDS_TEST_VERSION = "0.0.0-test"@@ -106,3 +108,40 @@ class TestCrateNormalizationRoundTrip:library_manager.load_from_crate(library_id=library_id, crate=normalized)library = library_manager.get_library(library_id=library_id)assert "intake.extract_pages" in library.pipe_library.root++ def test_hinted_crate_round_trips_and_loads(self, load_empty_library: Callable[[], str]):+ """The committed hinted fixture (hints at all three sites) normalizes, re-normalizes to a+ fixed point, and loads back into a live library — hints riding the crate, never the runtime.+ """+ library_manager = get_library_manager()++ hinted_path = Path(__file__).parents[3] / "data" / "input_semantics" / "hinted_bundle.mthds"+ blueprints = [MthdsParser.make_pipelex_bundle_blueprint(bundle_path=hinted_path)]+ crate = LibraryCrateFactory.make_from_blueprints(blueprints=blueprints)+ normalized = normalize_crate(crate, mthds_version=MTHDS_TEST_VERSION)++ # Hints are in the normalized crate: effective on concepts, as authored on slots.+ special_badge = normalized.concepts["input_semantics_hinted.SpecialBadge"]+ assert isinstance(special_badge, ConceptBlueprint)+ assert special_badge.hints == {"intent": "prose"}+ plain_badge = normalized.concepts["input_semantics_hinted.PlainBadge"]+ assert isinstance(plain_badge, ConceptBlueprint)+ assert plain_badge.hints == {"intent": "label"}+ hinted_pipe_inputs = normalized.pipes["input_semantics_hinted.hinted_slots"].inputs+ assert hinted_pipe_inputs is not None+ hinted_slot = hinted_pipe_inputs["hinted"]+ assert isinstance(hinted_slot, InputSlotBlueprint)+ assert hinted_slot.hints == {"intent": "prose"}++ renormalized = normalize_crate(normalized, mthds_version=MTHDS_TEST_VERSION)+ assert renormalized.fingerprint == normalized.fingerprint+ assert renormalized.concepts == normalized.concepts+ assert renormalized.pipes == normalized.pipes++ library_id = load_empty_library()+ library_manager.load_from_crate(library_id=library_id, crate=normalized)+ library = library_manager.get_library(library_id=library_id)+ assert "input_semantics_hinted.hinted_slots" in library.pipe_library.root+ # Runtime stays hint-free: the loaded pipe's StuffSpec sees only the concept.+ loaded_pipe = library.pipe_library.root["input_semantics_hinted.hinted_slots"]+ assert "hinted" in loaded_pipe.inputs.rootdiff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.pyindex ab75a3d49..b91331377 100644--- a/tests/integration/pipelex/pipeline/test_input_form.py+++ b/tests/integration/pipelex/pipeline/test_input_form.py@@ -48,6 +48,7 @@ def _teardown_validation_library(outer_library_id: str) -> None:_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"+_HINTED_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "hinted_bundle.mthds"_LIBRARY_DIR_MTHDS = """@@ -353,6 +354,75 @@ class TestBuildInputForm:assert [field.name for field in special.fields] == ["number", "total"]assert special.description == "An invoice flagged for review"+ async def test_hinted_slots_carry_effective_hints_on_the_wire(self, load_empty_library: Callable[[], str]) -> None:+ """Authored hints reach the descriptor (H2): slot hints merge over the concept layer, an+ applicable intent feeds `kind`, a plural slot's hints ride list AND item, and hint-free+ slots stay hint-free.+ """+ outer_library_id = load_empty_library()+ try:+ result = await validate_bundle(mthds_contents=[_HINTED_BUNDLE_PATH.read_text(encoding="utf-8")])+ input_form = build_input_form(result.pipes)+ finally:+ _teardown_validation_library(outer_library_id)++ fields = {field.name: field for field in input_form["input_semantics_hinted.hinted_slots"].fields}+ # Plain and collapsed slots derive identically: the concept layer alone (Essay: prose).+ for slot_name in ["plain", "expanded_plain"]:+ assert fields[slot_name].hints == {"intent": "prose"}+ assert fields[slot_name].kind is FieldKind.PROSE+ # Slot hints on a structured concept: inapplicable intent rides, kind stays `object`.+ assert fields["hinted"].hints == {"intent": "prose"}+ assert fields["hinted"].kind is FieldKind.OBJECT+ # Plural slot: merged hints on the list node AND its item; the item's kind flips.+ marked = fields["hinted_marked"]+ assert marked.kind is FieldKind.LIST+ assert marked.hints == {"intent": "label"}+ assert marked.item is not None+ assert marked.item.hints == {"intent": "label"}+ assert marked.item.kind is FieldKind.TEXT++ async def test_hinted_structure_fields_on_the_wire(self, load_empty_library: Callable[[], str]) -> None:+ """Field-site hints from the parsed bundle survive to the descriptor, unknown keys included."""+ outer_library_id = load_empty_library()+ try:+ result = await validate_bundle(mthds_contents=[_HINTED_BUNDLE_PATH.read_text(encoding="utf-8")])+ input_form = build_input_form(result.pipes)+ finally:+ _teardown_validation_library(outer_library_id)++ review = {field.name: field for field in input_form["input_semantics_hinted.hinted_slots"].fields}["hinted"]+ review_fields = {field.name: field for field in review.fields or []}+ assert review_fields["headline"].hints == {"intent": "label"}+ assert review_fields["headline"].kind is FieldKind.TEXT+ assert review_fields["body"].hints == {"intent": "prose"}+ assert review_fields["body"].kind is FieldKind.PROSE+ assert review_fields["stars"].hints == {"intent": "rating"}+ assert review_fields["stars"].kind is FieldKind.NUMBER+ assert review_fields["plain"].hints is None+ # Unknown key: preserved content, riding the slot with no kind effect.+ assert review_fields["quirk"].hints == {"emphasis": "HINTED_unknown_value"}+ assert review_fields["quirk"].kind is FieldKind.TEXT++ async def test_hint_free_probe_descriptor_carries_no_hints_key(self, load_empty_library: Callable[[], str]) -> None:+ """Population is wire-additive: the hint-free probe bundle's descriptor is byte-identical+ to before hints existed — no `hints` key at any depth.+ """+ input_form, _ = await self._derive_probe(load_empty_library)++ def assert_no_hints(dumped: dict[str, Any]) -> None:+ assert "hints" not in dumped+ children: list[dict[str, Any]] = dumped.get("fields") or []+ for child in children:+ assert_no_hints(child)+ item: dict[str, Any] | None = dumped.get("item")+ if item:+ assert_no_hints(item)++ for descriptor in input_form.values():+ for field in descriptor.fields:+ assert_no_hints(field.model_dump())+async def test_wire_dump_has_no_null_slots(self, load_empty_library: Callable[[], str]) -> None:"""The valid arm is dumped WITHOUT `exclude_none`, so inapplicable slots must self-exclude."""input_form, _ = await self._derive_probe(load_empty_library)diff --git a/tests/integration/pipelex/pipeline/test_protocol_validate.py b/tests/integration/pipelex/pipeline/test_protocol_validate.pyindex fb3e7f642..ae5c79d40 100644--- a/tests/integration/pipelex/pipeline/test_protocol_validate.py+++ b/tests/integration/pipelex/pipeline/test_protocol_validate.py@@ -23,6 +23,7 @@ from pipelex.pipeline.bundle_validator import DryRunStatusfrom pipelex.pipeline.exceptions import PipeIOContractError, ValidateBundleErrorfrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.pipeline.validation_report import PipelexValidationReport+from pipelex.validation_error_types import HintLintErrorTypeif TYPE_CHECKING:from collections.abc import Callable@@ -80,6 +81,23 @@ prompt = "Summarize $outline_text""""+_HINTED_WARN_MTHDS = """+domain = "protocol_validate_hints"+description = "Bundle carrying an applicable hint and a warnable one, for the advisory hint lint"++[concept.Essay]+description = "An essay"+hints = { intent = "prose", emphasis = "strong" }++[pipe.write_essay]+type = "PipeLLM"+description = "Write an essay"+inputs = { topic = "Text" }+output = "Essay"+prompt = "Write about $topic"+"""++def _signature_only_contents() -> list[str]:return [(_SIGNATURE_ONLY_DIR / "concepts.mthds").read_text(encoding="utf-8"),@@ -115,6 +133,26 @@ class TestProtocolValidate:finally:clear_current_library()+ async def test_hint_lint_warns_without_invalidating(self, load_empty_library: Callable[[], str]) -> None:+ """A warnable hint (unknown key) rides the advisory `warnings` channel; the bundle stays+ valid and runnable, and the applicable `intent` beside it warns nothing (spec: hints are+ non-normative — warn only, never reject; well-formed unknown content is preserved).+ """+ load_empty_library()+ try:+ runner = PipelexMTHDSProtocol()+ report = await runner.validate(mthds_contents=[_HINTED_WARN_MTHDS])++ assert isinstance(report, PipelexValidationReport)+ assert report.is_runnable is True+ hint_warnings = [warning for warning in report.warnings if warning.error_type == HintLintErrorType.HINT_UNKNOWN_KEY]+ assert len(hint_warnings) == 1+ assert hint_warnings[0].concept_code == "Essay"+ assert "emphasis" in hint_warnings[0].message+ assert [warning for warning in report.warnings if warning.error_type == HintLintErrorType.HINT_UNKNOWN_INTENT] == []+ finally:+ clear_current_library()+async def test_pending_signatures_reported_on_lenient_path(self, load_empty_library: Callable[[], str]) -> None:"""An unsatisfied header validated with ``allow_signatures=True`` is reported as pending — not yet runnable."""load_empty_library()diff --git a/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint_hints.py b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint_hints.pynew file mode 100644index 000000000..81ebadd98--- /dev/null+++ b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint_hints.py@@ -0,0 +1,83 @@+"""Intent hints on the concept and structure-field sites (spec: intent-hints.md): strict shape,+lenient content, empty-table normalization, and fingerprint-neutral serialization.+"""++import json++import pytest+from pydantic import ValidationError++from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+++class TestConceptBlueprintHints:+ def test_flat_table_is_accepted(self):+ blueprint = ConceptBlueprint(description="an essay", hints={"intent": "prose"})+ assert blueprint.hints == {"intent": "prose"}++ def test_unknown_key_is_preserved(self):+ blueprint = ConceptBlueprint(description="a thing", hints={"emphasis": "strong"})+ assert blueprint.hints == {"emphasis": "strong"}++ def test_empty_table_normalizes_to_absence(self):+ blueprint = ConceptBlueprint(description="a thing", hints={})+ assert blueprint.hints is None++ def test_hints_keys_are_sorted(self):+ blueprint = ConceptBlueprint(description="a thing", hints={"zeta": "z", "alpha": "a"})+ assert list(blueprint.hints or {}) == ["alpha", "zeta"]++ def test_non_table_hints_are_rejected(self):+ with pytest.raises(ValidationError):+ ConceptBlueprint.model_validate({"description": "a thing", "hints": "prose"})++ def test_non_string_value_is_rejected(self):+ with pytest.raises(ValidationError):+ ConceptBlueprint.model_validate({"description": "a thing", "hints": {"intent": 3}})++ def test_nested_table_is_rejected(self):+ with pytest.raises(ValidationError):+ ConceptBlueprint.model_validate({"description": "a thing", "hints": {"intent": {"word": "prose"}}})+++class TestStructureFieldHints:+ def test_flat_table_is_accepted(self):+ field = ConceptStructureBlueprint(description="a text field", type=ConceptStructureBlueprintFieldType.TEXT, hints={"intent": "label"})+ assert field.hints == {"intent": "label"}++ def test_empty_table_normalizes_to_absence(self):+ field = ConceptStructureBlueprint(description="a text field", type=ConceptStructureBlueprintFieldType.TEXT, hints={})+ assert field.hints is None++ def test_non_table_hints_are_rejected(self):+ with pytest.raises(ValidationError):+ ConceptStructureBlueprint.model_validate({"description": "a text field", "type": "text", "hints": "label"})++ def test_non_string_value_is_rejected(self):+ with pytest.raises(ValidationError):+ ConceptStructureBlueprint.model_validate({"description": "a text field", "type": "text", "hints": {"intent": 5}})++ def test_nested_table_is_rejected(self):+ with pytest.raises(ValidationError):+ ConceptStructureBlueprint.model_validate({"description": "a text field", "type": "text", "hints": {"a": {"b": "c"}}})+++class TestHintFreeSerialization:+ def test_hint_free_concept_serializes_without_hints_key_at_any_depth(self):+ blueprint = ConceptBlueprint(+ description="a structured concept",+ structure={+ "title": ConceptStructureBlueprint(description="the title", type=ConceptStructureBlueprintFieldType.TEXT, required=True),+ "note": "a shorthand field",+ },+ )+ assert '"hints"' not in json.dumps(blueprint.model_dump(mode="json"))++ def test_hinted_concept_serializes_hints(self):+ blueprint = ConceptBlueprint(description="an essay", hints={"intent": "prose"})+ assert blueprint.model_dump(mode="json")["hints"] == {"intent": "prose"}++ def test_hinted_field_serializes_hints(self):+ field = ConceptStructureBlueprint(description="a text field", type=ConceptStructureBlueprintFieldType.TEXT, hints={"intent": "label"})+ assert field.model_dump(mode="json")["hints"] == {"intent": "label"}diff --git a/tests/unit/pipelex/errors/test_validation_error_types.py b/tests/unit/pipelex/errors/test_validation_error_types.pyindex cdd4b4434..8cca10099 100644--- a/tests/unit/pipelex/errors/test_validation_error_types.py+++ b/tests/unit/pipelex/errors/test_validation_error_types.py@@ -14,6 +14,7 @@ from pydantic import ValidationErrorfrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.validation_error_types import (VALIDATION_ERROR_TYPES,+ HintLintErrorType,PipeFactoryErrorType,PipeValidationErrorType,ValidationErrorType,@@ -28,7 +29,7 @@ class TestValidationErrorTypeRegistry:Written as a set comparison rather than a length check: a member dropped from the registryand a member added to a source enum are both failures, and both should name the member."""- contributed = set(PipeValidationErrorType) | set(PipeFactoryErrorType) | set(ValidationResidualErrorType)+ contributed = set(PipeValidationErrorType) | set(PipeFactoryErrorType) | set(ValidationResidualErrorType) | set(HintLintErrorType)assert set(VALIDATION_ERROR_TYPES) == contributeddef test_registry_has_no_duplicate_wire_values(self) -> None:@@ -45,7 +46,7 @@ class TestValidationErrorTypeRegistry:def test_registry_order_is_deterministic(self) -> None:"""Two reads give the same order, so an artifact generated from the registry is stable."""assert tuple(VALIDATION_ERROR_TYPES) == VALIDATION_ERROR_TYPES- assert list(VALIDATION_ERROR_TYPES) == [*PipeValidationErrorType, *PipeFactoryErrorType, *ValidationResidualErrorType]+ assert list(VALIDATION_ERROR_TYPES) == [*PipeValidationErrorType, *PipeFactoryErrorType, *ValidationResidualErrorType, *HintLintErrorType]# The three tests below hold that the registry is enforced when an item is parsed, not merely# documented. They go through ``model_validate`` rather than the constructor on purpose: thediff --git a/tests/unit/pipelex/language/test_intent_hints.py b/tests/unit/pipelex/language/test_intent_hints.pynew file mode 100644index 000000000..cfde7a5de--- /dev/null+++ b/tests/unit/pipelex/language/test_intent_hints.py@@ -0,0 +1,99 @@+"""Unit tests for the shared intent-hints language module (spec: mthds/docs/spec/intent-hints.md)."""++import pytest++from pipelex.language.intent_hints import (+ INTENT_HINT_KEY,+ KNOWN_HINT_KEYS,+ HintSiteValueKind,+ IntentWord,+ applicable_intent,+ intent_word_applies,+ is_intent_word_known,+ merge_hints,+)+++class TestMergeHints:+ def test_later_layer_wins_key_by_key(self):+ base = {"intent": "prose", "extra": "kept"}+ site = {"intent": "label"}+ assert merge_hints([base, site]) == {"intent": "label", "extra": "kept"}++ def test_none_and_empty_layers_are_transparent(self):+ assert merge_hints([None, {"intent": "prose"}, None, {}]) == {"intent": "prose"}++ def test_empty_merge_is_none(self):+ assert merge_hints([]) is None+ assert merge_hints([None, {}]) is None++ def test_key_overridden_not_cleared(self):+ """No layer can unset an inherited key — an unknown word replaces, absence inherits."""+ base = {"intent": "prose"}+ assert merge_hints([base, {"intent": "banana"}]) == {"intent": "banana"}+ assert merge_hints([base, {}]) == {"intent": "prose"}++ def test_result_is_a_fresh_dict(self):+ base = {"intent": "prose"}+ merged = merge_hints([base])+ assert merged == base+ assert merged is not base++ def test_result_is_sorted_by_key(self):+ """Merged results are installed via model_copy, bypassing the sorting validators — the+ merge itself must hand back the canonical order (spec: hints entries emitted sorted by key).+ """+ merged = merge_hints([{"zeta": "1"}, {"alpha": "2"}])+ assert merged is not None+ assert list(merged) == ["alpha", "zeta"]+++class TestVocabulary:+ def test_known_words(self):+ for word in ("prose", "label", "rating", "quantity"):+ assert is_intent_word_known(word)+ assert not is_intent_word_known("banana")+ assert not is_intent_word_known("")++ def test_known_keys(self):+ assert INTENT_HINT_KEY in KNOWN_HINT_KEYS+++class TestApplicability:+ @pytest.mark.parametrize(+ ("word", "site_kind", "applies"),+ [+ (IntentWord.PROSE, HintSiteValueKind.TEXT_VALUED, True),+ (IntentWord.LABEL, HintSiteValueKind.TEXT_VALUED, True),+ (IntentWord.RATING, HintSiteValueKind.TEXT_VALUED, False),+ (IntentWord.QUANTITY, HintSiteValueKind.TEXT_VALUED, False),+ (IntentWord.PROSE, HintSiteValueKind.NUMBER_VALUED, False),+ (IntentWord.LABEL, HintSiteValueKind.NUMBER_VALUED, False),+ (IntentWord.RATING, HintSiteValueKind.NUMBER_VALUED, True),+ (IntentWord.QUANTITY, HintSiteValueKind.NUMBER_VALUED, True),+ (IntentWord.PROSE, HintSiteValueKind.OTHER, False),+ (IntentWord.RATING, HintSiteValueKind.OTHER, False),+ ],+ )+ def test_intent_word_applies(self, word: IntentWord, site_kind: HintSiteValueKind, applies: bool):+ assert intent_word_applies(word, site_kind=site_kind) is applies++ def test_every_word_applies_to_exactly_one_value_kind(self):+ # The vocabulary partition: enum growth keeps this meaningful without enumerating members.+ for word in IntentWord:+ applicable = [kind for kind in HintSiteValueKind if intent_word_applies(word, site_kind=kind)]+ assert len(applicable) == 1+++class TestApplicableIntent:+ def test_known_and_applicable(self):+ assert applicable_intent({"intent": "prose"}, site_kind=HintSiteValueKind.TEXT_VALUED) == "prose"+ assert applicable_intent({"intent": "rating"}, site_kind=HintSiteValueKind.NUMBER_VALUED) == "rating"++ def test_absent_unknown_and_inapplicable_answer_none(self):+ assert applicable_intent(None, site_kind=HintSiteValueKind.TEXT_VALUED) is None+ assert applicable_intent({}, site_kind=HintSiteValueKind.TEXT_VALUED) is None+ assert applicable_intent({"other": "x"}, site_kind=HintSiteValueKind.TEXT_VALUED) is None+ assert applicable_intent({"intent": "banana"}, site_kind=HintSiteValueKind.TEXT_VALUED) is None+ assert applicable_intent({"intent": "rating"}, site_kind=HintSiteValueKind.TEXT_VALUED) is None+ assert applicable_intent({"intent": "prose"}, site_kind=HintSiteValueKind.OTHER) is Nonediff --git a/tests/unit/pipelex/libraries/test_crate_normalization_hints.py b/tests/unit/pipelex/libraries/test_crate_normalization_hints.pynew file mode 100644index 000000000..6d30e7e4e--- /dev/null+++ b/tests/unit/pipelex/libraries/test_crate_normalization_hints.py@@ -0,0 +1,153 @@+"""Effective intent hints assembled during refinement flattening (spec: library-crate.md step 3,+intent-hints.md Precedence and Inheritance): chain merge on both arms, position-correct memoization,+authored-only travel for field and slot hints, idempotency, and fingerprint sensitivity.+"""++from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+from pipelex.core.domains.domain_blueprint import DomainBlueprint+from pipelex.libraries.crate_normalization import normalize_crate+from pipelex.libraries.library_crate import LibraryCrate+from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint++MTHDS_TEST_VERSION = "0.0.0-test"+++def _concept(ref: str, crate: LibraryCrate) -> ConceptBlueprint:+ value = crate.concepts[ref]+ assert isinstance(value, ConceptBlueprint)+ return value+++def _hinted_chain_crate() -> LibraryCrate:+ """A refinement chain with hints at several positions, plus hinted field and slot sites."""+ return LibraryCrate(+ concepts={+ # Structured base with hints: the chain's bottom.+ "docs.Base": ConceptBlueprint(+ description="the structured base",+ structure={"body": ConceptStructureBlueprint(description="the body", type=ConceptStructureBlueprintFieldType.TEXT)},+ hints={"intent": "label", "emphasis": "base"},+ ),+ # Top DELIBERATELY declared before Mid: flattening iterates in declaration order, so+ # Top's resolution walks Mid -> Base in ONE pass and caches BOTH positions — the very+ # multi-position walk the memoization guard below needs to exist.+ # Top: no hints of its own — inherits Mid's effective hints.+ "docs.Top": ConceptBlueprint(description="the top link", refines="Mid"),+ # Mid-chain: overrides `intent`, keeps inheriting `emphasis`.+ "docs.Mid": ConceptBlueprint(description="the mid link", refines="Base", hints={"intent": "prose"}),+ # Sibling refining the BASE directly: must get the base's hints, not Mid's accumulated+ # ones, even when Mid's walk populated the cache first.+ "docs.Sibling": ConceptBlueprint(description="refines the base directly", refines="Base"),+ # Hint-free chain: the empty merge leaves no member.+ "docs.PlainBase": ConceptBlueprint(+ description="hint-free base",+ structure={"note": ConceptStructureBlueprint(description="a note", type=ConceptStructureBlueprintFieldType.TEXT)},+ ),+ "docs.PlainTop": ConceptBlueprint(description="hint-free refiner", refines="PlainBase"),+ # Native-backed arm: keeps `refines`, still assembles hints.+ "docs.Summary": ConceptBlueprint(description="a short summary", refines="Text", hints={"intent": "prose"}),+ "docs.LongSummary": ConceptBlueprint(description="a longer summary", refines="Summary"),+ # Field-site hints, carried as authored.+ "docs.Card": ConceptBlueprint(+ description="a card",+ structure={+ "title": ConceptStructureBlueprint(+ description="the title", type=ConceptStructureBlueprintFieldType.TEXT, hints={"intent": "label"}+ )+ },+ ),+ },+ pipes={+ "docs.write": PipeLLMBlueprint(+ description="write a doc",+ inputs={"topic": InputSlotBlueprint(concept="Text", hints={"intent": "prose"}), "plain": "Text"},+ output="Text",+ prompt="Write about $topic using $plain",+ ),+ },+ domains={"docs": DomainBlueprint(code="docs", description="Docs domain")},+ source_map={},+ )+++class TestEffectiveHintsAssembly:+ def test_flattened_arm_merges_chain_hints_nearer_wins(self):+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ mid = _concept("docs.Mid", result)+ assert mid.refines is None+ assert isinstance(mid.structure, dict)+ # Own `intent` wins over the base's; `emphasis` is inherited, not cleared.+ assert mid.hints == {"emphasis": "base", "intent": "prose"}++ def test_hintless_refiner_inherits_effective_hints(self):+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ top = _concept("docs.Top", result)+ assert top.hints == {"emphasis": "base", "intent": "prose"}++ def test_memoized_mid_chain_resolution_carries_its_own_positions_hints(self):+ # Top walks first (dict order), caching Mid AND Base positions in one pass. Sibling then+ # resolves Base FROM the cache — and must see Base's hints, not Mid's accumulated ones.+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ sibling = _concept("docs.Sibling", result)+ assert sibling.hints == {"emphasis": "base", "intent": "label"}++ def test_empty_merge_leaves_no_member(self):+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ assert _concept("docs.PlainTop", result).hints is None++ def test_native_backed_arm_keeps_refines_and_assembles_hints(self):+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ summary = _concept("docs.Summary", result)+ assert summary.refines == "native.Text"+ assert summary.hints == {"intent": "prose"}+ long_summary = _concept("docs.LongSummary", result)+ assert long_summary.refines == "docs.Summary"+ assert long_summary.hints == {"intent": "prose"}+++class TestAuthoredHintsTravel:+ def test_field_hints_carried_as_authored(self):+ # No site-over-concept merge at crate level — that merge is the deriver's.+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ card = _concept("docs.Card", result)+ assert isinstance(card.structure, dict)+ title = card.structure["title"]+ assert isinstance(title, ConceptStructureBlueprint)+ assert title.hints == {"intent": "label"}++ def test_slot_hints_carried_as_authored_with_concept_qualified(self):+ result = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ pipe = result.pipes["docs.write"]+ assert pipe.inputs is not None+ slot = pipe.inputs["topic"]+ assert isinstance(slot, InputSlotBlueprint)+ assert slot.concept == "native.Text"+ assert slot.hints == {"intent": "prose"}+ assert pipe.inputs["plain"] == "native.Text"+++class TestHintedCrateStability:+ def test_normalization_is_idempotent_on_hinted_crate(self):+ once = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)+ twice = normalize_crate(once, mthds_version=MTHDS_TEST_VERSION)+ assert twice.fingerprint == once.fingerprint+ assert twice.concepts == once.concepts+ assert twice.pipes == once.pipes++ def test_hinted_crate_fingerprint_differs_from_hint_free_twin(self):+ hinted = normalize_crate(_hinted_chain_crate(), mthds_version=MTHDS_TEST_VERSION)++ twin = _hinted_chain_crate()+ stripped_concepts = {+ ref: value.model_copy(update={"hints": None}) if isinstance(value, ConceptBlueprint) else value for ref, value in twin.concepts.items()+ }+ hint_free = LibraryCrate(+ concepts=stripped_concepts,+ pipes=twin.pipes,+ domains=twin.domains,+ source_map=twin.source_map,+ )+ hint_free_normalized = normalize_crate(hint_free, mthds_version=MTHDS_TEST_VERSION)+ assert hint_free_normalized.fingerprint != hinted.fingerprintdiff --git a/tests/unit/pipelex/libraries/test_fingerprint_pins.py b/tests/unit/pipelex/libraries/test_fingerprint_pins.pynew file mode 100644index 000000000..93202d050--- /dev/null+++ b/tests/unit/pipelex/libraries/test_fingerprint_pins.py@@ -0,0 +1,38 @@+"""Pinned-fingerprint regression for the intent-hints milestone (H2).++The spec rule under guard: a library that authors no hints keeps its fingerprint. Both fingerprint+functions hash `model_dump(mode="json")` payloads, so an optional field added carelessly to a+blueprint model lands as `"hints": null` in every dumped concept and field and silently migrates+every existing crate digest. These pins were computed on the models BEFORE the hints fields landed;+they must never move for a hint-free bundle.++If this test fails, do NOT re-pin the hexes — find the field or serializer that leaked a new member+into the dumped payload of a hint-free blueprint and make its absence a dropped key instead.+"""++from pathlib import Path++from pipelex.libraries.crate_normalization import normalize_crate+from pipelex.libraries.library_crate_factory import LibraryCrateFactory+from pipelex.mthds_parsing.parser import MthdsParser++_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"++# Computed on the probe bundle at the base of feature/Engine-hints (models without hints fields).+_PINNED_CONTENT_FINGERPRINT = "32d3b801c1124334b5415c77f7e501b41890dbeb6bd881a76ff10c41a1fa1c14"+_PINNED_NORMALIZED_FINGERPRINT = "c6265a638147a5dcc6d9b22d24751c6579d46f7d8d29220ff443265c896fec28"++_MTHDS_TEST_VERSION = "0.0.0-test"+++class TestHintFreeFingerprintPins:+ def test_content_fingerprint_is_stable(self):+ blueprint = MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_PROBE_BUNDLE_PATH)+ crate = LibraryCrateFactory.make_from_blueprints(blueprints=[blueprint])+ assert crate.compute_fingerprint() == _PINNED_CONTENT_FINGERPRINT++ def test_normalized_fingerprint_is_stable(self):+ blueprint = MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_PROBE_BUNDLE_PATH)+ crate = LibraryCrateFactory.make_from_blueprints(blueprints=[blueprint])+ normalized = normalize_crate(crate, mthds_version=_MTHDS_TEST_VERSION)+ assert normalized.compute_normalized() == _PINNED_NORMALIZED_FINGERPRINTdiff --git a/tests/unit/pipelex/mthds_parsing/test_parser_intent_hints.py b/tests/unit/pipelex/mthds_parsing/test_parser_intent_hints.pynew file mode 100644index 000000000..105f932a0--- /dev/null+++ b/tests/unit/pipelex/mthds_parsing/test_parser_intent_hints.py@@ -0,0 +1,81 @@+"""Full-bundle parsing of intent hints (spec: intent-hints.md): the three authoring sites land on+their blueprints, hint-free expanded slots collapse, and the rejected probe fails as an unknown+slot-table key.+"""++from pathlib import Path++import pytest++from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint+from pipelex.mthds_parsing.exceptions import MthdsParserError+from pipelex.mthds_parsing.parser import MthdsParser+from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint+from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint, PipeBlueprint++_DATA_DIR = Path(__file__).parents[3] / "data" / "input_semantics"+_HINTED_BUNDLE_PATH = _DATA_DIR / "hinted_bundle.mthds"+_REJECTED_SLOT_KEY_PATH = _DATA_DIR / "rejected" / "per_input_description.mthds_invalid"+++def _parse_hinted_bundle() -> PipelexBundleBlueprint:+ blueprint = MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_HINTED_BUNDLE_PATH)+ assert isinstance(blueprint, PipelexBundleBlueprint)+ return blueprint+++def _hinted_concept(blueprint: PipelexBundleBlueprint, code: str) -> ConceptBlueprint:+ assert blueprint.concept is not None+ value = blueprint.concept[code]+ assert isinstance(value, ConceptBlueprint)+ return value+++class TestHintedBundleParsing:+ def test_concept_site(self):+ blueprint = _parse_hinted_bundle()+ assert _hinted_concept(blueprint, "Essay").hints == {"intent": "prose"}+ assert _hinted_concept(blueprint, "PlainBadge").hints is None++ def test_structure_field_site(self):+ blueprint = _parse_hinted_bundle()+ review = _hinted_concept(blueprint, "Review")+ assert isinstance(review.structure, dict)+ headline = review.structure["headline"]+ assert isinstance(headline, ConceptStructureBlueprint)+ assert headline.hints == {"intent": "label"}+ stars = review.structure["stars"]+ assert isinstance(stars, ConceptStructureBlueprint)+ assert stars.hints == {"intent": "rating"}+ plain = review.structure["plain"]+ assert isinstance(plain, ConceptStructureBlueprint)+ assert plain.hints is None+ quirk = review.structure["quirk"]+ assert isinstance(quirk, ConceptStructureBlueprint)+ assert quirk.hints == {"emphasis": "HINTED_unknown_value"}++ def test_input_slot_site(self):+ blueprint = _parse_hinted_bundle()+ assert blueprint.pipe is not None+ pipe = blueprint.pipe["hinted_slots"]+ assert isinstance(pipe, PipeBlueprint)+ assert pipe.inputs is not None+ assert pipe.inputs["plain"] == "Essay"+ # The expanded form without hints collapses to the very same string form.+ assert pipe.inputs["expanded_plain"] == "Essay"+ hinted = pipe.inputs["hinted"]+ assert isinstance(hinted, InputSlotBlueprint)+ assert hinted.concept == "Review"+ assert hinted.hints == {"intent": "prose"}+ marked = pipe.inputs["hinted_marked"]+ assert isinstance(marked, InputSlotBlueprint)+ assert marked.concept == "Badge[]"+ assert marked.hints == {"intent": "label"}+++class TestRejectedSlotTableKey:+ def test_per_input_description_fails_as_unknown_slot_table_key(self):+ with pytest.raises(MthdsParserError) as exc_info:+ MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_REJECTED_SLOT_KEY_PATH)+ assert "extra" in str(exc_info.value).lower()diff --git a/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_input_slots.py b/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_input_slots.pynew file mode 100644index 000000000..154396941--- /dev/null+++ b/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_input_slots.py@@ -0,0 +1,128 @@+"""The expanded input-slot form (spec: intent-hints.md): strict shape, the parse-time collapse+rule, grammar parity between the two arms, and fingerprint-neutral serialization.+"""++import json++import pytest+from pydantic import ValidationError++from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint, PipeBlueprint, slot_concept_spec+++class ConcretePipeBlueprint(PipeBlueprint):+ pass+++def make_blueprint(inputs: dict[str, object]) -> ConcretePipeBlueprint:+ return ConcretePipeBlueprint.model_validate(+ {+ "type": "PipeLLM",+ "pipe_category": "PipeOperator",+ "description": "slot-form test pipe",+ "inputs": inputs,+ "output": "Text",+ }+ )+++class TestInputSlotAcceptance:+ def test_hinted_table_is_kept_as_slot_blueprint(self):+ blueprint = make_blueprint({"doc": {"concept": "Text", "hints": {"intent": "prose"}}})+ assert blueprint.inputs is not None+ slot = blueprint.inputs["doc"]+ assert isinstance(slot, InputSlotBlueprint)+ assert slot.concept == "Text"+ assert slot.hints == {"intent": "prose"}++ def test_unknown_hint_key_is_preserved(self):+ # Content is lenient: an unknown, well-formed hint entry parses and survives.+ blueprint = make_blueprint({"doc": {"concept": "Text", "hints": {"emphasis": "strong"}}})+ assert blueprint.inputs is not None+ slot = blueprint.inputs["doc"]+ assert isinstance(slot, InputSlotBlueprint)+ assert slot.hints == {"emphasis": "strong"}++ def test_hints_keys_are_sorted(self):+ blueprint = make_blueprint({"doc": {"concept": "Text", "hints": {"zeta": "z", "alpha": "a"}}})+ assert blueprint.inputs is not None+ slot = blueprint.inputs["doc"]+ assert isinstance(slot, InputSlotBlueprint)+ assert list(slot.hints or {}) == ["alpha", "zeta"]++ def test_marked_concept_travels_through_the_table_arm(self):+ blueprint = make_blueprint(+ {"many": {"concept": "Widget[]", "hints": {"intent": "label"}}, "opt": {"concept": "Text?", "hints": {"intent": "prose"}}}+ )+ assert blueprint.inputs is not None+ assert slot_concept_spec(blueprint.inputs["many"]) == "Widget[]"+ assert slot_concept_spec(blueprint.inputs["opt"]) == "Text?"+++class TestInputSlotCollapse:+ def test_table_without_hints_collapses_to_string(self):+ blueprint = make_blueprint({"doc": {"concept": "Text"}})+ assert blueprint.inputs is not None+ assert blueprint.inputs["doc"] == "Text"++ def test_table_with_empty_hints_collapses_to_string(self):+ blueprint = make_blueprint({"doc": {"concept": "Text?", "hints": {}}})+ assert blueprint.inputs is not None+ assert blueprint.inputs["doc"] == "Text?"++ def test_collapsed_blueprint_equals_string_form(self):+ expanded = make_blueprint({"doc": {"concept": "Text"}})+ plain = make_blueprint({"doc": "Text"})+ assert expanded.model_dump(mode="json") == plain.model_dump(mode="json")+++class TestInputSlotRejection:+ def test_unknown_slot_table_key_is_rejected(self):+ with pytest.raises(ValidationError, match=r"[Ee]xtra"):+ make_blueprint({"doc": {"concept": "Text", "description": "the document"}})++ def test_non_table_hints_are_rejected(self):+ with pytest.raises(ValidationError):+ make_blueprint({"doc": {"concept": "Text", "hints": "prose"}})++ def test_non_string_hint_value_is_rejected(self):+ with pytest.raises(ValidationError):+ make_blueprint({"doc": {"concept": "Text", "hints": {"intent": 3}}})++ def test_nested_hint_table_is_rejected(self):+ with pytest.raises(ValidationError):+ make_blueprint({"doc": {"concept": "Text", "hints": {"intent": {"word": "prose"}}}})++ def test_table_arm_concept_passes_the_slot_grammar(self):+ with pytest.raises(ValidationError):+ make_blueprint({"doc": {"concept": "not a concept ref !!", "hints": {"intent": "prose"}}})+++class TestInputsConceptSpecsProjection:+ def test_projection_reads_both_arms(self):+ blueprint = make_blueprint({"plain": "Text", "hinted": {"concept": "Widget[]", "hints": {"intent": "label"}}})+ assert blueprint.inputs_concept_specs == {"plain": "Text", "hinted": "Widget[]"}++ def test_projection_is_none_when_inputs_absent(self):+ blueprint = ConcretePipeBlueprint(+ type="PipeLLM",+ pipe_category="PipeOperator",+ description="no inputs",+ output="Text",+ )+ assert blueprint.inputs_concept_specs is None+++class TestInputSlotSerialization:+ def test_hint_free_pipe_serializes_without_hints_key_at_any_depth(self):+ blueprint = make_blueprint({"doc": {"concept": "Text"}, "plain": "Widget"})+ assert '"hints"' not in json.dumps(blueprint.model_dump(mode="json"))++ def test_directly_constructed_hint_free_slot_drops_the_member(self):+ slot = InputSlotBlueprint(concept="Text")+ assert slot.model_dump(mode="json") == {"concept": "Text"}++ def test_hinted_slot_serializes_hints(self):+ blueprint = make_blueprint({"doc": {"concept": "Text", "hints": {"intent": "prose"}}})+ dumped = blueprint.model_dump(mode="json")+ assert dumped["inputs"]["doc"] == {"concept": "Text", "hints": {"intent": "prose"}}diff --git a/tests/unit/pipelex/pipeline/test_hint_warnings.py b/tests/unit/pipelex/pipeline/test_hint_warnings.pynew file mode 100644index 000000000..623629077--- /dev/null+++ b/tests/unit/pipelex/pipeline/test_hint_warnings.py@@ -0,0 +1,219 @@+"""The advisory intent-hints lint (spec: intent-hints.md SHOULD-warn rules): each finding fires+with site attribution, warns without rejecting, and leaves the warned content in the crate.+"""++from pipelex.base_exceptions import ValidationErrorCategory+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+from pipelex.core.domains.domain_blueprint import DomainBlueprint+from pipelex.libraries.crate_qualification import qualify_crate+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.validation_error_types import HintLintErrorType+++def _lint(crate: LibraryCrate):+ return build_hint_warnings(qualify_crate(crate))+++def _crate(concepts: dict[str, ConceptBlueprint | str], pipes: dict[str, PipeBlueprintUnion] | None = None) -> LibraryCrate:+ return LibraryCrate(+ concepts=concepts,+ pipes=pipes or {},+ domains={"docs": DomainBlueprint(code="docs", description="Docs domain")},+ source_map={},+ )+++class TestHintLintFindings:+ def test_unknown_hint_key_warns_with_concept_attribution(self):+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={"emphasis": "strong"})}))+ assert len(warnings) == 1+ warning = warnings[0]+ assert warning.error_type == HintLintErrorType.HINT_UNKNOWN_KEY+ assert warning.category == ValidationErrorCategory.BLUEPRINT_VALIDATION+ assert warning.concept_code == "Essay"+ assert warning.domain_code == "docs"+ assert "emphasis" in warning.message++ def test_unknown_intent_word_warns(self):+ warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={"intent": "poetry"})}))+ assert len(warnings) == 1+ assert warnings[0].error_type == HintLintErrorType.HINT_UNKNOWN_INTENT+ assert "poetry" in warnings[0].message++ def test_choice_field_is_not_a_text_site(self):+ """Choices dominate the declared type (the deriver emits an enum), so a text intent on a+ typed-choice field is inapplicable and must warn.+ """+ warnings = _lint(+ _crate(+ {+ "docs.Card": ConceptBlueprint(+ description="a card",+ structure={+ "mood": ConceptStructureBlueprint(+ description="the mood",+ type=ConceptStructureBlueprintFieldType.TEXT,+ choices=["calm", "wild"],+ hints={"intent": "prose"},+ )+ },+ )+ }+ )+ )+ assert len(warnings) == 1+ assert warnings[0].error_type == HintLintErrorType.HINT_INAPPLICABLE_INTENT++ def test_class_backed_native_text_concept_takes_text_intents(self):+ """A `structure = "TextContent"` concept IS the native Text payload: the deriver honors a+ `prose`/`label` hint there, so the lint must not call it inapplicable.+ """+ warnings = _lint(_crate({"docs.Styled": ConceptBlueprint(description="styled text", structure="TextContent", hints={"intent": "prose"})}))+ assert warnings == []++ def test_class_backed_native_number_concept_takes_number_intents(self):+ warnings = _lint(_crate({"docs.Score": ConceptBlueprint(description="a score", structure="NumberContent", hints={"intent": "rating"})}))+ assert warnings == []++ def test_class_backed_project_class_is_not_a_hint_site(self):+ # A registered non-native class is an object payload: intent words do not apply.+ warnings = _lint(_crate({"docs.Custom": ConceptBlueprint(description="custom", structure="SomeProjectClass", hints={"intent": "prose"})}))+ assert len(warnings) == 1+ assert warnings[0].error_type == HintLintErrorType.HINT_INAPPLICABLE_INTENT++ def test_inapplicable_intent_warns_on_structured_concept(self):+ # A structured concept is neither text- nor number-valued: `prose` does not apply there.+ warnings = _lint(+ _crate(+ {+ "docs.Card": ConceptBlueprint(+ description="a card",+ structure={"title": ConceptStructureBlueprint(description="the title", type=ConceptStructureBlueprintFieldType.TEXT)},+ hints={"intent": "prose"},+ )+ }+ )+ )+ assert len(warnings) == 1+ assert warnings[0].error_type == HintLintErrorType.HINT_INAPPLICABLE_INTENT++ def test_inapplicable_intent_warns_on_number_field_with_text_word(self):+ warnings = _lint(+ _crate(+ {+ "docs.Review": ConceptBlueprint(+ description="a review",+ structure={+ "stars": ConceptStructureBlueprint(+ description="the stars", type=ConceptStructureBlueprintFieldType.INTEGER, hints={"intent": "prose"}+ )+ },+ )+ }+ )+ )+ assert len(warnings) == 1+ warning = warnings[0]+ assert warning.error_type == HintLintErrorType.HINT_INAPPLICABLE_INTENT+ assert warning.concept_code == "Review"+ assert warning.field_name == "stars"++ def test_inapplicable_intent_warns_on_slot_with_attribution(self):+ warnings = _lint(+ _crate(+ {"docs.Amount": ConceptBlueprint(description="an amount", refines="Number")},+ {+ "docs.write": PipeLLMBlueprint(+ description="write",+ inputs={"amount": InputSlotBlueprint(concept="Amount", hints={"intent": "label"})},+ output="Text",+ prompt="Use $amount",+ )+ },+ )+ )+ assert len(warnings) == 1+ warning = warnings[0]+ assert warning.error_type == HintLintErrorType.HINT_INAPPLICABLE_INTENT+ assert warning.pipe_code == "write"+ assert warning.variable_names == ["amount"]+++class TestHintLintSilence:+ def test_applicable_hints_produce_no_warning(self):+ warnings = _lint(+ _crate(+ {+ # Description-only concept: text-valued -> `prose` applies.+ "docs.Essay": ConceptBlueprint(description="an essay", hints={"intent": "prose"}),+ # Refinement chain to native.Number -> `rating` applies.+ "docs.Score": ConceptBlueprint(description="a score", refines="Number", hints={"intent": "rating"}),+ # Text field -> `label` applies.+ "docs.Card": ConceptBlueprint(+ description="a card",+ structure={+ "title": ConceptStructureBlueprint(+ description="the title", type=ConceptStructureBlueprintFieldType.TEXT, hints={"intent": "label"}+ ),+ # List of text: plural site judged per item -> text-valued.+ "tags": ConceptStructureBlueprint(+ description="the tags",+ type=ConceptStructureBlueprintFieldType.LIST,+ item_type="text",+ hints={"intent": "label"},+ ),+ },+ ),+ },+ {+ # Slot with multiplicity: judged per item against the concept.+ "docs.write": PipeLLMBlueprint(+ description="write",+ inputs={"essays": InputSlotBlueprint(concept="Essay[]", hints={"intent": "prose"})},+ output="Text",+ prompt="Use $essays",+ )+ },+ )+ )+ assert warnings == []++ def test_hint_free_crate_produces_no_warning(self):+ warnings = _lint(+ _crate(+ {+ "docs.Plain": ConceptBlueprint(description="plain"),+ "docs.Str": "a string-described concept",+ }+ )+ )+ assert warnings == []++ def test_warned_content_stays_in_the_crate(self):+ # The lint names the finding; the crate keeps the authored entry untouched.+ crate = _crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={"emphasis": "strong"})})+ warnings = _lint(crate)+ assert len(warnings) == 1+ qualified = qualify_crate(crate)+ essay = qualified.concepts["docs.Essay"]+ assert isinstance(essay, ConceptBlueprint)+ assert essay.hints == {"emphasis": "strong"}+++class TestHintLintOrdering:+ def test_findings_are_deterministically_ordered(self):+ crate = _crate(+ {+ "docs.Beta": ConceptBlueprint(description="b", hints={"zz": "1"}),+ "docs.Alpha": ConceptBlueprint(description="a", hints={"aa": "1"}),+ }+ )+ first = [(w.error_type, w.concept_code) for w in _lint(crate)]+ second = [(w.error_type, w.concept_code) for w in _lint(crate)]+ assert first == second+ assert [code for _, code in first] == ["Alpha", "Beta"]diff --git a/tests/unit/pipelex/pipeline/test_input_form_hints.py b/tests/unit/pipelex/pipeline/test_input_form_hints.pynew file mode 100644index 000000000..ee51d1bb5--- /dev/null+++ b/tests/unit/pipelex/pipeline/test_input_form_hints.py@@ -0,0 +1,121 @@+"""Hints on the input-form descriptor (spec: intent-hints.md + mthds-input-form-descriptor.md):+effective merges visible on the wire, intent feeding `kind` on applicable sites only, list/item+duplication, and preserved-content riding.+"""++from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType+from pipelex.pipeline.input_form import FieldKind, InputFormDeriver++_CONCEPTS: dict[str, ConceptBlueprint | str] = {+ # Description-only concept: text-valued, no-hint kind is `prose`.+ "docs.Essay": ConceptBlueprint(description="an essay", hints={"intent": "prose"}),+ "docs.Title": ConceptBlueprint(description="a title", hints={"intent": "label"}),+ # Chain: base declares label, refiner overrides with prose; a second refiner inherits.+ "docs.Badge": ConceptBlueprint(description="a badge", hints={"intent": "label", "emphasis": "base"}),+ "docs.SpecialBadge": ConceptBlueprint(description="a special badge", refines="docs.Badge", hints={"intent": "prose"}),+ "docs.PlainBadge": ConceptBlueprint(description="a plain badge", refines="docs.Badge"),+ # Number-valued chain.+ "docs.Score": ConceptBlueprint(description="a score", refines="native.Number", hints={"intent": "rating"}),+ # Structured concept: neither text- nor number-valued.+ "docs.Card": ConceptBlueprint(+ description="a card",+ structure={+ "title": ConceptStructureBlueprint(description="the title", type=ConceptStructureBlueprintFieldType.TEXT, hints={"intent": "label"}),+ "body": ConceptStructureBlueprint(description="the body", type=ConceptStructureBlueprintFieldType.TEXT),+ "stars": ConceptStructureBlueprint(description="the stars", type=ConceptStructureBlueprintFieldType.INTEGER, hints={"intent": "rating"}),+ "essay": ConceptStructureBlueprint(+ description="the essay", type=ConceptStructureBlueprintFieldType.CONCEPT, concept_ref="docs.Essay", hints={"intent": "label"}+ ),+ "tags": ConceptStructureBlueprint(+ description="the tags", type=ConceptStructureBlueprintFieldType.LIST, item_type="text", hints={"intent": "label"}+ ),+ },+ hints={"intent": "prose"},+ ),+}+++def _deriver() -> InputFormDeriver:+ return InputFormDeriver(concepts=dict(_CONCEPTS))+++class TestConceptEffectiveHints:+ def test_prose_intent_keeps_prose_kind(self):+ node = _deriver().derive_concept(name="essay", concept_ref="docs.Essay")+ assert node.kind is FieldKind.PROSE+ assert node.hints == {"intent": "prose"}++ def test_label_intent_flips_text_valued_node_to_text(self):+ node = _deriver().derive_concept(name="title", concept_ref="docs.Title")+ assert node.kind is FieldKind.TEXT+ assert node.hints == {"intent": "label"}++ def test_chain_override_nearer_wins_key_by_key(self):+ node = _deriver().derive_concept(name="badge", concept_ref="docs.SpecialBadge")+ # Own `intent` wins; `emphasis` inherited, not cleared.+ assert node.hints == {"intent": "prose", "emphasis": "base"}+ assert node.kind is FieldKind.PROSE++ def test_hintless_refiner_inherits_effective_hints(self):+ node = _deriver().derive_concept(name="badge", concept_ref="docs.PlainBadge")+ assert node.hints == {"intent": "label", "emphasis": "base"}+ assert node.kind is FieldKind.TEXT++ def test_rating_on_number_valued_node_rides_without_changing_kind(self):+ node = _deriver().derive_concept(name="score", concept_ref="docs.Score")+ assert node.kind is FieldKind.NUMBER+ assert node.hints == {"intent": "rating"}++ def test_inapplicable_intent_on_object_rides_without_changing_kind(self):+ node = _deriver().derive_concept(name="card", concept_ref="docs.Card")+ assert node.kind is FieldKind.OBJECT+ assert node.hints == {"intent": "prose"}+++class TestStructureFieldHints:+ def test_field_hints_stamped_and_feed_kind(self):+ card = _deriver().derive_concept(name="card", concept_ref="docs.Card")+ fields = {field.name: field for field in card.fields or []}+ assert fields["title"].kind is FieldKind.TEXT+ assert fields["title"].hints == {"intent": "label"}+ assert fields["body"].hints is None+ assert fields["body"].kind is FieldKind.TEXT++ def test_rating_on_integer_field_rides_without_changing_kind(self):+ card = _deriver().derive_concept(name="card", concept_ref="docs.Card")+ fields = {field.name: field for field in card.fields or []}+ assert fields["stars"].kind is FieldKind.NUMBER+ assert fields["stars"].integer is True+ assert fields["stars"].hints == {"intent": "rating"}++ def test_concept_typed_field_site_wins_over_concept_layer(self):+ card = _deriver().derive_concept(name="card", concept_ref="docs.Card")+ fields = {field.name: field for field in card.fields or []}+ # Essay's concept layer says prose; the field site says label — the site wins.+ assert fields["essay"].hints == {"intent": "label"}+ assert fields["essay"].kind is FieldKind.TEXT++ def test_list_field_hints_ride_list_and_item(self):+ card = _deriver().derive_concept(name="card", concept_ref="docs.Card")+ fields = {field.name: field for field in card.fields or []}+ tags = fields["tags"]+ assert tags.kind is FieldKind.LIST+ assert tags.hints == {"intent": "label"}+ assert tags.item is not None+ assert tags.item.hints == {"intent": "label"}+ # The item is the text-valued site: the label intent flips ITS kind.+ assert tags.item.kind is FieldKind.TEXT+++class TestHintFreeByteIdentity:+ def test_hint_free_derivation_carries_no_hints_key(self):+ concepts: dict[str, ConceptBlueprint | str] = {+ "docs.Plain": ConceptBlueprint(+ description="plain",+ structure={"note": ConceptStructureBlueprint(description="a note", type=ConceptStructureBlueprintFieldType.TEXT)},+ )+ }+ node = InputFormDeriver(concepts=concepts).derive_concept(name="plain", concept_ref="docs.Plain")+ assert "hints" not in node.model_dump()+ assert all("hints" not in field for field in node.model_dump()["fields"])diff --git a/wip/engine-hints/deferred.md b/wip/engine-hints/deferred.mdnew file mode 100644index 000000000..40a87edaa--- /dev/null+++ b/wip/engine-hints/deferred.md@@ -0,0 +1,27 @@+# Engine intent hints (H2) — deferred items++Items identified during H2 execution that are deliberately not done in this branch. Each is small and self-contained; none blocks the milestone.++- **Hint lint on the CLI and builder validate channels.** `build_current_library_hint_warnings()` is wired only into `pipelex/pipeline/validate_in_process.py` (the report/API path). The bare CLI (`pipelex/cli/commands/validate/_validate_core.py`), the agent CLI (`pipelex/cli/agent_cli/commands/validate/_validate_core.py`, three sites), and the builder ops (`pipelex/builder/operations/validate_ops.py`, three sites) each assemble their `warnings` from `build_optionality_warnings` alone, so an author validating through those channels does not see the hint lint. All seven sites run inside the validation library window, so appending `+ build_current_library_hint_warnings()` is mechanical — but it touches three presentation surfaces whose output shape each needs verifying, so it was deferred rather than folded into Phase 3. Consider a shared "all advisory warnings" composition point when doing it, instead of an eighth copy of the pattern.++- **Builder emission of hints (spec layer + writer).** `pipelex/builder/operations/concept_ops.py`'s writer emits from `ConceptSpec` / `ConceptStructureSpec`, and neither spec model has a `hints` field — the builder spec layer stays `dict[str, str]`-input hint-free by design this milestone (all `*_spec.from_blueprint` sites read `inputs_concept_specs`). Preserving hints on a builder rewrite is therefore not a writer one-liner: it needs the two spec models to grow the field, the `from_blueprint` conversions to carry it, and the writer to emit it. It sits beside the known E8 spelling bug in the same writer; do them together.++## Lint/deriver site-kind divergences: deriver honors, lint says OTHER++The lint classifies sites over the qualified crate (`_resolve_concept_kind`) while the deriver re-derives applicability from node facts (`_node_site_kind`), and the two judgments are known to diverge in two spots — in both, the lint warns `hint_inapplicable_intent` while the deriver honors the same hint on the wire:++- **Class-backed `HtmlContent`.** `_node_site_kind` (input_form.py) excludes Html-backed nodes from text-valued by looking for `native.Html` in the node's `concept_ref`/`refines` — which a `structure = "HtmlContent"` class-backed concept never carries, so the deriver treats it as text-valued, while the lint (spec-faithful: Html is not text-valued) classifies the same site OTHER and warns. Surfaced by PR #1148 review triage (2026-08-23).+- **Unresolvable-base chains.** A concept refining a base the crate cannot resolve (cross-package or dangling ref) is OTHER to the lint ("not classifiable in-crate") but prose-promoted by the deriver, whose PROSE node `_node_site_kind` calls text-valued — so an `intent = "label"` there both warns AND flips the kind. Surfaced by the pre-landing adversarial review (2026-08-23); which side is right is a spec judgment (is a prose-promoted unresolvable site text-valued?).++The shared root cause is the re-derivation: `_node_site_kind` reconstructs the site kind from node facts instead of receiving the crate-walk judgment. The clean fix threads the site kind from the crate walk into `_with_effective_hints` (or gives the node a backing-class fact), which touches the wire `refines` semantics — out of proportion for these exotic authorings. Revisit together, as one shared-classifier fix, if either case shows up in real methods.++## Review deferrals (pre-landing review, 2026-08-23)++Decision-first or marginal items from PR #1148's pre-landing review — none is a defect in the shipped behavior; each needs a ruling or is a cleanup not worth widening the diff for:++- **`sync-controller-inputs` quick-fix drops authored slot hints.** `pipelex/pipeline/fixes/planner.py` (`SetKeyOp` sites) rewrites a slot to the plain `expected_ref` string, so applying the fix to an expanded slot `x = { concept = "…", hints = { … } }` silently discards the hints. Decide: preserve hints through the rewrite, or document that sync replaces the slot wholesale.+- **Pipe-declaration merge drops the losing declaration's slot hints.** `contracts_match` deliberately compares the concept-spec projection (hints are non-normative), so in `library_crate_factory` a hinted signature merged with a hint-free concrete definition keeps the definition's slots — the signature's hints vanish with no diagnostic (two matching signatures tie-break deterministically but arbitrarily). Definition-is-authority is defensible; decide and document.+- **Hint content is echoed raw and unbounded into warning messages.** The lint interpolates authored hint keys/words verbatim into `ValidationErrorItem.message` (one item per unknown key), consistent with how descriptions already flow — but a hostile bundle can inflate message size and warning count. Consider eliding long tokens and capping per-site findings when wiring the lint into the CLI/builder channels (first bullet above).+- **`qualify_crate` runs twice per validate pass.** `build_input_form` and `build_current_library_hint_warnings` each qualify the same accumulated crate inside one `validate_bundles_in_process` window — a duplicated whole-crate model_copy walk. Share the `QualifiedCrateContent` (e.g. qualify once in `validate_in_process` and pass it to both; `build_hint_warnings(qualified)` already takes one).+- **Class-name → `NativeConceptCode` reverse lookup exists in three places.** `hint_warnings._native_class_value_kind`, `input_form._class_backed_node`, and `NativeConceptCode.get_native_structure_class` each scan the enum by `structure_class_name`; a `NativeConceptCode.from_structure_class_name(...)` classmethod would replace the comment-enforced mirroring with shared code.+- **Hints dicts are aliased across copies.** `_qualify_slot_value`'s `model_copy` shares the `hints` dict between raw and qualified crates, and list/item nodes share one merged dict. No current code mutates a hints dict in place; if a mutator ever appears, copy at the stamp sites.diff --git a/wip/engine-hints/design.md b/wip/engine-hints/design.mdnew file mode 100644index 000000000..d1119f59c--- /dev/null+++ b/wip/engine-hints/design.md@@ -0,0 +1,147 @@+# Engine intent hints — H2 design++Milestone H2 of the input-form program (workspace `wip/devx/input-form-roadmap.md`), on branch `feature/Engine-hints`, cut from `dev` after the `feature/Input-semantics` program branch merged (base includes `46a3f5df2`, which carries D2's deriver). Inputs: the accepted intent-hints standard (`mthds` PR #56 at `98883bb` — `docs/spec/intent-hints.md`, the expanded input-slot form in `mthds-format.md`, the effective-hints normalization in `library-crate.md`), the H1 design log (`mthds/wip/intent-hints-design.md`), the workspace descriptor spec's reserved-hint-slot section (`../docs/specs/mthds-input-form-descriptor.md`), and the request `../wip/inbox/2026-08-22-pipelex-h2-intent-hints-engine.md`.++**Scope:** the engine round trip — hints authored in a bundle reach the wire input-form descriptor. Parse at three sites, validate strict-shape/lenient-content, carry through the crate with effective-hints normalization and fingerprint neutrality for hint-free crates, warn on unknown content, populate the descriptor's reserved `hints` slot, promote the no-hint presentation defaults from heuristics to specified rules, regenerate `mthds_schema.json`, and grow spec/conformance.++**Gate (roadmap H2):** the hint round trip proven on one real method; spec and conformance updated. The engine-side provable half is authored-in-a-bundle → visible-on-the-wire-descriptor (integration test + the trace harness's hop-5 capture); the "visible in a rendered control" half needs a consumer that reads the wire descriptor, which arrives with M1/H3 — the checkpoint records this reading so the roadmap can reconcile it.++## The contract, in one paragraph++The normative rules live in the standard and are not restated here: `hints` is a flat string→string TOML table; shape violations are structural bundle errors; unknown keys and unknown `intent` words warn on the advisory channel and are preserved; three sites (concept, structure field, expanded input slot `name = { concept = "…", hints = { … } }`), unknown slot-table keys rejected; precedence is key-by-key, site over concept, nearer chain declaration wins; normalization materializes each concept's effective hints at refinement-flattening, removes empty tables, and keeps hint-free crates byte-identical (fingerprint-stable); hints ride the hashed members; the vocabulary this version defines is one key `intent` closed over `prose`, `label`, `rating`, `quantity`, with applicability defined over text-valued and number-valued sites and per-item judgment on plural sites. Hints are non-normative: no verdict, no execution behavior, no gating decision ever reads them.++## Dataflow overview++Authored bundle → blueprint models (parse + strict shape) → library crate (hints ride the blueprint objects) → qualification (pass-through) → normalization (effective hints on concepts; fingerprint) → advisory lint (content warnings on the validation report) → input-form deriver (site-over-concept merge, `hints` slot populated, intent feeds the kind defaults). Runtime execution models never carry hints — that is the structural enforcement of non-normativity.++## Part 1 — Parsing the three sites++**(a) Concept blueprint.** Add `hints: dict[str, str] | None = None` to `ConceptBlueprint` (`pipelex/core/concepts/concept_blueprint.py:12`). `extra="forbid"` is already in force there (line 13), so a misspelled member fails loudly today; the typed field gives strict shape for free — pydantic rejects a non-table `hints` and non-string values as structural validation errors, which is exactly the spec's shape rule.++**(b) Structure-field blueprint.** Add the same field to `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py:50`). That model has no `model_config`, so extras are silently ignored (finding E7, `wip/input-semantics/findings.md` §E7) — meaning a *misspelled* `hint = {…}` on a field still vanishes silently after H2. Per the H1 design log, the E7 `extra="forbid"` fix is deliberately separate work (it belongs to S2's strictness sweep, where the whole language ceiling becomes enforceable at once); H2 adds the field and does not change the extras policy. A *present, well-spelled* `hints` member is still strictly shape-checked by its type — the H2 guarantee holds where the spec states it.++**(c) The expanded input-slot form.** Today a slot value is a bare string: `PipeBlueprint.inputs: dict[str, str] | None` (`pipelex/pipe_machinery/pipe_blueprint.py:186`), validated by `generic_validate_inputs` (lines 281–323) against the ref+multiplicity+presence grammar. Add a slot table model beside it:++- `InputSlotBlueprint(BaseModel)` with `model_config = ConfigDict(extra="forbid")` and exactly two fields: `concept: str` (the full existing slot grammar — ref, optional `[]`/`[N]`, optional `?`/`!`) and `hints: dict[str, str] | None = None`. `extra="forbid"` implements the spec's "unknown slot-table keys MUST be rejected" — the form is deliberately closed so future per-slot semantic keys (`description`, defaults) land here without a second syntax.+- Widen `inputs` to `dict[str, str | InputSlotBlueprint] | None`. The union widens every `Pipe*Blueprint` subclass at once (the union is assembled at `pipelex/mthds_parsing/pipelex_bundle_blueprint.py:59-73`), and `generic_validate_inputs` validates the `concept` value of a table arm with the same grammar it applies to the string arm — one grammar, two spellings.+- **Parse-time collapse rule:** a slot table carrying no hints (absent or empty `hints`) collapses to its plain string at model validation — `x = { concept = "S" }` and `x = { concept = "S", hints = {} }` become the string `"S"` in the blueprint. The spec sanctions this ("`x = { concept = "S" }` and `x = "S"` are the same slot in the crate and hash identically"; an empty table is equivalent to no hints), and it buys a strong invariant downstream: *a slot value that is a table carries non-empty hints*, so hint-free bundles produce byte-identical blueprints to today by construction, and the string-assuming code paths stay dominant.++Two downstream sites iterate slot values as strings and need the table arm: `crate_qualification._qualify_io_ref` (`pipelex/libraries/crate_qualification.py:140-141`) must qualify the table's `concept` through the same marker-preserving rewrite (`_render_ref_with_markers`, lines 191–198) while passing `hints` through untouched (a hints table contains no refs — qualification never rewrites it), and `crate_normalization._collect_referenced_natives` (`pipelex/libraries/crate_normalization.py:235`) must read the table arm's `concept`. `InputStuffSpecsFactory.make_from_blueprint` (`pipelex/core/pipes/inputs/input_stuff_specs_factory.py:26`) accepts the union and extracts the `concept` string for the runtime spec — and nothing more: `StuffSpec` (`pipelex/core/pipes/stuff_spec/stuff_spec.py:11`) does **not** grow a hints field. The deriver reads slot hints from the qualified crate instead (Part 6). Keeping hints out of the runtime input models is the design's structural answer to "an implementation MUST NOT consult hints when executing a pipe": the execution path cannot read what it never receives.++**Fixture consequence:** the committed rejection fixture `tests/data/input_semantics/rejected/per_input_description.mthds_invalid` (`inputs = { doc = { concept = "Text", description = "…" } }`) **remains a valid rejection** — `description` is an unknown slot-table key and the expanded form rejects unknown keys. Its rationale shifts from "tables are not accepted" to "this key is not accepted"; update its commentary, verify the new failure surfaces as the slot-table extras error, and add accepted-fixture siblings for `{ concept = "…" }` (collapses to the string form) and `{ concept = "…", hints = { intent = "prose" } }`.++## Part 2 — Serialization and the fingerprint hazard++This is the highest-risk detail in the milestone. Both fingerprint functions (`pipelex/libraries/library_crate.py`: `compute_fingerprint_from_content` lines 51–68, `compute_normalized_fingerprint` lines 74–98) hash `model_dump(mode="json")` payloads **without** `exclude_none`. A naïvely added optional field therefore lands as `"hints": null` in every dumped concept and field, changing **every existing crate digest** — the exact opposite of the spec's "a library that authors no hints keeps its fingerprint".++The fix is the spec's own rule made local: "absent hints are an absent member — never `null`, never an empty table". Give `ConceptBlueprint`, `ConceptStructureBlueprint`, and `InputSlotBlueprint` a `@model_serializer(mode="wrap")` that drops only the `hints` key when it is `None` — the exact pattern `InputFormField.serialize_without_inapplicable_slots` already uses (`pipelex/pipeline/input_form.py:183-189`). Deliberately *not* a blanket `exclude_none`: the crate spec's general absent-members-not-null canonicalization is a separate forward contract whose adoption would migrate every existing fingerprint, and H2 must not smuggle that in. The targeted serializer keeps every current digest stable, makes hinted crates hash differently (correct — a hint edit is a semantic change to authored presentation, the domain-`description` precedent), and satisfies the crate encoding rule everywhere blueprints are dumped, including codegen's crate encoding. JSON canonical ordering is free (`sort_keys=True` in both fingerprint functions covers the "hints entries emitted sorted by key" rule); if `pipelex/codegen/crate_encoding.py`'s TOML encoding orders keys differently, it needs the same sorted-emission check.++**Byte-identity guards:** a unit test asserting the serialized JSON of a hint-free concept/field/pipe contains no `hints` key at any depth; the existing determinism and idempotency tests (`tests/unit/pipelex/libraries/test_library_crate.py::test_fingerprint_determinism`, `test_crate_normalization.py::test_normalization_is_idempotent`, `tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py`) re-run unchanged; and one pinned-fingerprint regression test — compute the normalized fingerprint of a committed hint-free fixture bundle on current `dev`, hardcode the hex in the test, and land the pin *before* the hints fields so the suite proves the digests did not move.++## Part 3 — Crate travel and effective hints++Hints need no new crate machinery to *travel* — they are blueprint content and ride `LibraryCrate.concepts`/`pipes` like every other member. The work is in normalization (`pipelex/libraries/crate_normalization.py`):++- **Effective hints are assembled where the refinement chain is already walked**: `_flatten_refinement` (lines 117–137) via `_resolve_refinement` (lines 139–189). The chain structure makes this cheap: `refines` XOR `structure` means at most the chain's *end* carries structure, so the existing walk already visits every intermediate link — it only needs to accumulate hints as it goes. Extend `_RefinementResolution` (line 53) with `effective_hints: dict[str, str] | None`; while walking child→base, merge with first-seen-wins (nearer declaration wins, key by key — the shared merge helper of Part 4). Per the crate spec, this applies to every refining concept whose bases resolve in-crate — the one flattened to a bare structure *and* the one that keeps its `refines` link (native-backed chains; the pinned natives carry no hints this version, so they contribute nothing to the merge). A merge that yields nothing leaves the concept without a `hints` member. Mind the memoization at lines 187–188: a cached resolution must carry the hints of *its* position in the chain, not the querying concept's.+- **Empty-table removal** is already done at parse time (the Part 1 collapse rule normalizes `hints = {}` to absence on slots, and the concept/field models can do the same in a validator), so the crate never holds an empty `hints` table and step-5 materialization owes nothing.+- **Structure-field and slot hints are carried as authored** — the site-over-concept merge is the consumer's (here: the deriver's), both layers being present in the crate. Qualification passes them through untouched.+- Idempotency: re-normalizing a normalized crate must be a no-op — a concept whose hints are already its effective hints re-merges to the same table (`test_normalization_is_idempotent` extends to a hinted fixture).++## Part 4 — One shared hints module++New module `pipelex/language/intent_hints.py` (beside `mthds_schema_generator.py` — this is language-standard knowledge, not runtime config), the single owner of:++- The constants: `INTENT_HINT_KEY = "intent"` and the closed vocabulary `prose`, `label`, `rating`, `quantity`, pinned per standard version like the native concept definitions.+- `merge_hints(layers)` — the one precedence implementation: key-by-key, later (nearer) layer wins, empty result is `None`. Called from the normalizer's chain walk, from the deriver's site merge, everywhere. The codebase already has three refinement-chain walks (`crate_normalization._resolve_refinement`, `InputFormDeriver._refines_chain`/`_merged_structure`, codegen's native expansion); hints must not add a fourth *merge semantics* — the walks stay where they are, but they all call this one merge.+- The applicability predicates: text-valued and number-valued site judgment per the spec's Applicability section (structure-field types; refinement chains reaching `native.Text`/`native.Number`; description-only concepts are text-valued; plural sites judged per item), plus `applicable_intent(hints, *, site) -> str | None` returning the effective `intent` word only when it is known *and* applicable — the deriver's and the lint's shared question.++## Part 5 — The advisory lint++The spec's SHOULD-warn rules (unknown key, unknown `intent` word, applicable-word-on-inapplicable-site) cannot live in pydantic validators — a validator can only raise, and these must never reject. The engine already has the right pattern: a post-parse lint pass producing `ValidationErrorItem`s onto the report's `warnings` list (`pipelex/pipeline/validation_report.py:70`), exactly as `build_optionality_warnings` does (`pipelex/pipeline/optionality_warnings.py:33`, wired at `pipelex/pipeline/validate_in_process.py:114`).++New module `pipelex/pipeline/hint_warnings.py` with `build_hint_warnings(...)` sweeping the qualified crate's three sites and emitting one advisory item per finding: an unknown hint key, an unknown `intent` word, an `intent` word on a site it does not apply to. Each warning names its site (concept code / field name / pipe code + slot name) so the author can find it. Well-formed unknown content is *only* warned about — it is preserved into the crate and the descriptor untouched.++Error-type registry: add a dedicated advisory enum (working name `HintLintErrorType`: `hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`) joined into the `ValidationErrorType` alias (`pipelex/validation_error_types.py:285`), rather than growing `PipeValidationErrorType` — hints attach to concepts and fields too, so the pipe enum is the wrong home, and a new enum sidesteps rippling through the pipe enum's exhaustive `match` property blocks while still implementing whatever properties the render layer requires. Two gates will trip and must be updated deliberately: the error-identity snapshot (`tests/unit/pipelex/errors/test_error_identity_snapshot.py`, `make gei`) and the error-reference docs pages (`make gep`).++## Part 6 — Populating the descriptor++The reserved slot already exists and is never written: `InputFormField.hints` (`pipelex/pipeline/input_form.py:131`). Its `None`-dropping serializer means population is wire-additive and absent-when-unset for free. Narrow its annotation from `dict[str, Any]` to `dict[str, str]` — the flatness invariant is contract.++**Getting slot hints to the deriver without touching runtime models:** `build_input_form` (line 199) already computes `qualify_crate(crate)`; keep its `concepts` and also keep `pipes`. For each pipe, the qualified blueprint's `inputs` map yields, per slot name, either a string (no hints) or a slot table (hints). `InputFormDeriver` grows a per-derivation lookup (pipe ref → slot name → hints) or simply receives the slot's hints as an argument to `derive_slot` from the `build_input_form` loop — the loop is where both the runtime `StuffSpec` and the crate blueprint are in hand. The fallback path (no crate loaded) derives with no hints, as today.++**Where each site's hints are stamped:**++- Concept nodes (`_blueprint_node`, lines 274–303, and `derive_concept`): the concept's *effective* hints — the deriver works over the qualified (unflattened) crate, so it computes the chain merge itself via its existing `_refines_chain` walk calling the shared `merge_hints`. String-shorthand concepts, natives, and class-backed concepts author no hints this version and stamp nothing.+- Structure fields (`_structure_field`, lines 425–470): `merge_hints([referenced concept's effective hints (concept-typed and concept-item fields only), field.hints])` — the site layer winning key by key, stamped via the `model_copy(update=…)` pattern already used at the `concept` arm (line 444).+- Input slots (`derive_slot`, lines 231–250): `merge_hints([slot concept's effective hints, slot hints])`, stamped in the final `model_copy(update=…)` at line 250 beside `presence`/`required`/`gating`.+- Plural slots and list fields: the merged hints are stamped on the `list` node **and** on its `item` descriptor, mirroring the `concept_ref` duplication precedent ("the list node is where a renderer reads the slot's identity; the item is what it renders once per entry") — the spec judges applicability per item, and a renderer reading either node finds the same answer. Conformance pins this duplication.++Everything well-formed rides the slot — including unknown keys and unknown words (preserved content per spec); a consumer ignores what it does not know.++**Intent feeds the kind defaults — never competes with them.** The descriptor spec's ruling: an applicable `intent` word is an *input* to the deriver's kind-and-presentation defaults, never a second answer beside a derived `kind`. Concretely, via `applicable_intent(...)` from the shared module:++- On a **text-valued node**, effective `intent = "prose"` yields `kind: "prose"` and `intent = "label"` yields `kind: "text"`; absent (or inapplicable, or unknown) intent leaves the node on the no-hint default.+- On a **number-valued node**, `rating` and `quantity` do not change `kind` (both are `number` — the union has no finer kind); they ride the `hints` slot and the renderer decides what a judgment-versus-amount presentation means. The semantic bounds a rating presents against are already the constraint slots.+- An intent word on an inapplicable site changes nothing in `kind` (the lint already warned); it still rides the `hints` slot as preserved content.++**Promoting the no-hint defaults from heuristics to specified rules** is the other half of H2's mandate: the deriver's existing text-versus-prose and per-node kind assignments do not change behavior, but they get written down — as a stated rule table in `docs/under-the-hood/input-form-descriptor.md` and reflected into the workspace descriptor spec's kind-assignment section — so the no-hint case is specified, not folklore. H2 changes a node's kind only where an applicable authored intent says so.++## Part 7 — Schema regeneration and propagation++`mthds_schema.json` regenerates from the blueprint models (`pipelex/language/mthds_schema_generator.py:39`), so the two new `hints` fields and the slot-form union propagate automatically via `make gms` / checked by `make cms`. The slot union renders as an `anyOf` in Draft-4; if Taplo's disambiguation misbehaves on it, `_patch_construct_schema` (lines 218–304) is the precedent for a hand-patch. The generated file is gitignored (`derived/`), so drift is invisible in PRs — run `make cms` in the milestone's check loop. Propagation to the served schema and the vendored copies is the `/mthds-schema-sync` workspace plugin (`internal-tools/plugins/mthds-schema-sync/`), release-gated with a manual S3 step — it runs at the release that ships H2, not in this branch. The mthds site's intent-hints "Specification Status" section (which currently records that the served schema predates hints) gets its conformance assertion updated at the same release — an `mthds`-repo follow-up, filed at milestone close.++## Part 8 — Tests++- **Parsing (unit):** each site accepts a valid flat table; non-table `hints`, non-string values, and nested tables fail as structural errors at all three sites; unknown slot-table keys still fail; the collapse rule (`{ concept = "S" }` ≡ `"S"`, empty hints ≡ none); grammar preserved through the table arm (multiplicity + markers on `concept`). Homes: `tests/unit/pipelex/core/concepts/concept_blueprint/`, `tests/unit/pipelex/mthds_parsing/`.+- **Fingerprint neutrality (unit + integration):** the pinned-fingerprint regression (landed before the fields), the no-`hints`-key serialization assertion, determinism/idempotency/round-trip suites extended with a hinted fixture; a hinted crate's fingerprint differs from its hint-free twin.+- **Normalization (unit):** effective-hints merge along a chain (nearer wins, key by key), on both the flattened and the `refines`-keeping arms; memoized mid-chain resolution carries its own position's hints; empty merge leaves no member. Home: `tests/unit/pipelex/libraries/test_crate_normalization.py`.+- **Lint (unit):** unknown key warns, unknown word warns, inapplicable word warns, all with site attribution; a warned bundle is still valid; warned content survives into crate and descriptor. Home: beside `test_validation_errors.py`; snapshot and docs gates re-generated.+- **Deriver (unit + integration):** site-over-concept and chain precedence visible on the wire; `prose`/`label` flip `kind` on text-valued nodes only; `rating`/`quantity` leave `kind` untouched and ride the slot; list/item duplication; hint-free descriptor output byte-identical to today. Extend the probe bundle under `tests/data/input_semantics/` with hinted fixtures, and `tests/integration/pipelex/pipeline/test_input_form.py`'s kind table.+- **Corpus:** one MTHDS Test Corpus entry authoring hints at all three sites (`pipelex/test_extras/mthds_corpus/`), `make generate-corpus-vocabulary` re-run; the entry is the "one real method" the gate's round-trip proof runs on, and `mthds-corpus-sync` propagates it at close.++## Part 9 — Docs and changelog++Update `docs/under-the-hood/input-form-descriptor.md` (the stated no-hint kind rules; the hints slot is no longer reserved-only; drop the now-false "the blueprint parser drops keys it does not know, so an authored `minimum = 0` never reaches the deriver" framing where it touches hints), document the three authoring sites and the lint in the language-facing docs where the engine documents blueprint fields, and record the feature under `## [Unreleased]` in the changelog. The workspace descriptor spec (`../docs/specs/mthds-input-form-descriptor.md`) updates its reserved-hint-slot section from "reserved" to "populated" with its unverified-comment lifted at conformance time; the conformance repo grows the hint-slot arm as a skip-gated skeleton (same de-gating pattern as D2's, arming at the release that ships H2). Both are workspace-side edits filed or made at milestone close per the execution protocol.++## Phased plan++**Phase 1 — Language surface.** The shared `intent_hints` module (constants, `merge_hints`, applicability). The pinned-fingerprint regression test, landed first against unchanged models. Then the three site additions: `ConceptBlueprint.hints`, `ConceptStructureBlueprint.hints`, `InputSlotBlueprint` + the `inputs` union + `generic_validate_inputs` table arm + the parse-time collapse rule. The targeted `None`-dropping serializers. Fixtures: accepted siblings, the reinterpreted rejection fixture, parse unit tests, fingerprint-neutrality assertions green.++**Phase 2 — Crate travel.** Widen `_qualify_io_ref` and `_collect_referenced_natives` for the table arm; `InputStuffSpecsFactory` accepts the union and extracts the concept string only. Effective hints in `_resolve_refinement`/`_flatten_refinement` via the shared merge; normalization unit tests incl. idempotency on hinted fixtures; round-trip integration green.++**Checkpoint A** — the crate layer is done: hints parse at three sites, travel qualified and normalized, hint-free crates provably keep their digests. Update this doc with decisions taken and any deviation folded into the later phases; verify cold-start readiness.++> **Checkpoint A reached.** Phases 1–2 landed on `feature/Engine-hints`; execution detail is tracked in `TODOS.md` (repo root), whose "Resume state" section records the decisions this design left open, with these outcomes worth pinning here:+>+> - `PipeBlueprint.inputs` widened to `Mapping[str, str | InputSlotBlueprint]` (value-covariant, so `dict[str, str]` construction sites stay legal), with the grammar-only projection `inputs_concept_specs` / `slot_concept_spec` for consumers that don't read hints. `InputStuffSpecsFactory` kept its `dict[str, str]` signature; the projection happens at the `pipe_factory` call site — same invariant (runtime `StuffSpec` never sees hints), smaller surface.+> - The spec's sorted-hints-emission rule is implemented at the model: the shared `normalize_empty_hints` validator sorts keys, so fingerprints, codegen crate encoding, and the wire all emit canonically without encoder logic.+> - Effective hints ride `_RefinementResolution.effective_hints` and are position-specific in the memoization cache (each visited ref's entry merges its own hints over what lies below); `_flatten_refinement` stamps the merge on the flattened arm, the native-backed refines-keeping arm, and structureless-base chains alike. The position-correctness guard is mutation-verified.+> - Hint-free digest neutrality is proven by `tests/unit/pipelex/libraries/test_fingerprint_pins.py`, whose pinned hexes were committed before any model change; `tests/data/input_semantics/probe_bundle.mthds` must stay hint-free forever — hinted fixtures live in `hinted_bundle.mthds` beside it.++**Phase 3 — Advisory lint.** `hint_warnings.py`, the advisory error-type enum joined into `ValidationErrorType`, wiring in `validate_in_process` beside the optionality warnings, error-identity snapshot and error-docs regenerated, lint unit tests.++**Phase 4 — Descriptor population.** Slot-hints plumbing from the qualified crate through `build_input_form` into `derive_slot`; concept/field/slot stamping via the shared merge; the intent→kind rule on text-valued nodes; `InputFormField.hints` narrowed; list/item duplication; deriver unit + integration tests over the hinted probe bundle; hint-free descriptor byte-identity.++**Checkpoint B** — the round trip exists end to end in-engine: authored hints visible in `hop5_input_form.json` via the trace harness on the hinted corpus method. Same checkpoint protocol as A.++> **Checkpoint B reached.** Phases 3–4 landed; the trace harness on `tests/data/input_semantics/hinted_bundle.mthds` shows every authored hint in `hop5_input_form.json` — concept layer (`prose` on a description-only concept), field layer (label/prose/rating, an unknown key preserved), slot layer (site-over-concept merge), and the list/item duplication with the item's kind flipped. Decisions worth pinning:+>+> - **Lint (Phase 3):** `HintLintErrorType` is its own enum joined into the `ValidationErrorType` alias (open question 1 resolved: no render-layer properties were needed; `make gei`/`gep` produced no diff since these are enum members, not error classes — the corpus vocabulary did regenerate, with the three tags excluded as advisory-only). Wired into `validate_in_process` via `build_current_library_hint_warnings()`, which sweeps the same accumulated crate `build_input_form` reads and is empty with no library window. The bare-CLI / agent-CLI / builder-ops warning channels are deferred (`wip/engine-hints/deferred.md`).+> - **Descriptor (Phase 4):** open question 3 resolved as a per-call `derive_slot(slot_hints=...)` argument. The kind flip happens in exactly one place, `_with_effective_hints`, called once per node at the terminal where the FINAL merge is known — inner layers carry hints without flipping, so an outer layer overriding `intent` with an inapplicable word correctly falls back to the no-hint kind. `_node_site_kind` mirrors the lint's structural applicability judgment (number nodes are exact by construction; time-formatted text and Html-backed prose nodes are NOT text-valued).++**Phase 5 — Schema, corpus, docs, close.** `make gms`/`cms` (Taplo patch if the slot union needs it); the corpus entry + vocabulary regen; Part 9's docs and changelog; `make agent-check` + `make agent-test`. Milestone close per the workspace protocol: roadmap checkpoint with SHAs, the workspace-side spec/conformance edits, inbox items for the `mthds`-site status assertion and the `mthds-corpus-sync`/`mthds-schema-sync` runs that ride the next release, and the H3 handoff note.++## Out of scope, stated++- The E7 `extra="forbid"` fix on `ConceptStructureBlueprint` (S2's strictness sweep) — H2 notes the boundary in Part 1(b).+- Per-slot *semantic* keys (`description`, defaults, examples) on the expanded form — the form is their future home, the language does not define them yet.+- Hints on class-backed (Python-defined) structures and on native definitions — no authoring surface this version.+- The crate spec's general absent-members-not-null canonicalization and step-5 materialization — forward contracts; H2 implements only the hints-specific absence rule.+- Builder/authoring-CLI emission of hints (`pipelex/builder/operations/concept_ops.py` writes concepts today and would drop authored hints on a rewrite) — flag as its own small follow-up unless it turns out to be a one-liner in Phase 5; it sits beside the known E8 spelling bug in the same writer.+- The kernel rendering hints (H3) and the wire-descriptor swap in consumers (M1).++## Open questions++1. **Advisory enum home:** the design proposes a new `HintLintErrorType` joined into the `ValidationErrorType` alias; if the render layer's required properties make a shared enum cheaper, deciding at Phase 3 with the code in view is fine — the wire strings (`hint_unknown_key`, …) are the contract, the enum layout is not.+2. **Gate wording:** "visible in a rendered control" — this design reads the engine-provable gate as wire-descriptor visibility (Checkpoint B), with the rendered-control demonstration completing when a descriptor-reading consumer exists (M1/H3). To reconcile in the roadmap at close.+3. **`derive_slot` signature vs lookup:** whether slot hints reach the deriver as a per-call argument or a pipe-ref-keyed map is an implementation-taste call made in Phase 4; the invariant that matters is that runtime `StuffSpec` stays hint-free.diff --git a/wip/flaky-test-transported-run-structures.md b/wip/flaky-test-transported-run-structures.mdnew file mode 100644index 000000000..7c2a18bb1--- /dev/null+++ b/wip/flaky-test-transported-run-structures.md@@ -0,0 +1,17 @@+# Flaky under full suite: `test_transported_run_generates_concept_structures`++`tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py::TestDirectExecutorWorkdir::test_transported_run_generates_concept_structures` failed in three of four full-suite runs on `feature/Engine-hints` (both checkpoint `make test` runs and the final `make test`; the Phase 5 `make agent-test` run passed) with:++```+pydantic_core._pydantic_core.ValidationError: 1 validation error for PipeFunc+function_name: Value error, Function 'greet_it' not found in registry+ (raised from pipelex/pipe_operators/func/pipe_func_factory.py:28, during load_libraries)+```++It passes in isolation and when its whole module runs alone (16/16). Evidence that this is a pre-existing order-dependent flake, not an Engine-hints regression:++- The test sets `get_config().interpreter.pipe_func.execution_mode = "local_sandbox"` (the mode whose loader tolerates a yet-unregistered function) immediately before `load_libraries`, restoring it in `finally`. The observed failure means the loader read a non-tolerant mode — i.e. under xdist the config object the factory reads was not the one the test mutated, which is a test-isolation problem around the shared `get_config()` singleton, not a hints problem.+- The hints diff touches concept/pipe blueprints, crate normalization, the input-form deriver and an advisory lint. It does not touch config plumbing, PipeFunc, the func registry, or execution modes.+- The test file was last modified by the ruff 0.16.4 move (`6214a7b4f`), before this branch existed.++Suggested fix direction (deferred, not done here to avoid scope creep on the hints PR): make the test independent of the live config singleton — e.g. patch `execution_mode` via `mocker.patch.object` on the exact config instance the loader reads, or give the loader an explicit mode parameter for tests.diff --git a/wip/input-semantics/d2-input-form-descriptor-plan-DONE.md b/wip/input-semantics/d2-input-form-descriptor-plan-DONE.mdnew file mode 100644index 000000000..f28106f29--- /dev/null+++ b/wip/input-semantics/d2-input-form-descriptor-plan-DONE.md@@ -0,0 +1,113 @@+# D2 — Input-form descriptor: reference derivation + report carriage (✅ done — all phases complete 2026-08-22)++> **Archived 2026-08-23 from the repo-root `TODOS.md`, where it was the live tracker while D2 was built.** Every phase and checkpoint below is complete; this file is kept as the as-built record — the settled design decisions, the decisions taken while implementing, and what landed where. Paths in this document are relative to the repo root, not to this file's own directory. What is still open lives outside this repo: the two `../wip/inbox/` items filed in Phase 6, both waiting on a `pipelex` release that carries the derivation.++Implements `../wip/inbox/2026-08-22-pipelex-d2-input-form-descriptor-derivation.md` on the stacked branch `feature/Input-semantics-D2` (program branch `feature/Input-semantics`; no PR to `dev`, per the program's branch ruling).++**Contract:** `docs/specs/mthds-input-form-descriptor.md` (workspace root) — every section. **Gate:** the skip-gated skeletons in `conformance/tests/pipelex_api/test_validate_input_form.py` de-gated and green against the booted sibling `pipelex-api`, plus the per-kind assignment coverage. The two live absent-by-default tests must keep passing untouched. The de-gating itself rides the `pipelex-api` inbox item (Phase 6) because the sibling boots a **pinned PyPI runtime** — this repo's deliverable is the derivation, the report carriage, the pinned assignment table, and the follow-up filings.++## Settled design decisions (read before implementing)++- **Derivation input = loaded pipes + the qualified (NOT normalized) crate.** The slot key space and slot list come from the loaded pipes (`result.pipes` → `pipe.inputs.root` `StuffSpec`s), guaranteeing key-set equality with `pipe_io_contracts` by construction (same iteration, including `PipeSignature` placeholders and controller-inferred inputs). Concept facts (description, `refines`, structure fields) come from a crate built as `qualify_crate(LibraryCrateFactory.make_from_blueprints(result.blueprints))` — **not** `normalize_crate`, because normalization flattens in-crate refinement and drops the `refines` links the descriptor must report as a chain (`crate_normalization.py` step 3 vs spec's `refines` slot). Never read the emitted JSON Schema (the whole point — the E1/E2/E3/E4 losses live downstream of the blueprint).+- **Fact sources per node:** authored concepts → their `ConceptBlueprint.structure` (`ConceptStructureBlueprint` retains `default_value`, `choices`, `required`, descriptions, `concept_ref`/`item_concept_ref` — everything the schema loses); natives → `materialize_native_concept` pinned blueprints; class-backed concepts (`structure = "ClassName"`) → class-registry reflection (generalize the faithful-or-absent approach of `codegen/native_expansion.reflect_native_structure`), falling back to `kind: "unknown"` when unmappable. A pipe slot whose concept is absent from the crate (e.g. loaded from `library_dirs`) still gets a descriptor: slot facts from the loaded `StuffSpec`, concept payload via natives/reflection/`unknown`.+- **Slot facts from `StuffSpec`:** `presence: PresenceMarker` is already the spec's exact three-valued wire vocabulary (`plain`/`optional`/`force`) — reuse it. `multiplicity: VariableMultiplicity | None` keeps the fixed `[N]` int (E4's fact) — `None` → single node, `True` → `list` (no `item_count`), int → `list` with `item_count`.+- **Derived booleans (in the deriver, per spec):** top-level `required = presence != optional`; `gating = required and not (kind == "list" and item_count is None)`. Fixed-count lists gate. Nested fields carry neither `presence` nor `gating`.+- **E3 honesty:** a field authored `required = true` **and** `default_value` reports both — read from the blueprint, so the hop-2 accident never enters. `default_value` emitted only when authored (never the emission's `null`-for-optional artifact).+- **E10:** `choices` always a list on the wire, even one member.+- **Report carriage:** `PipelexValidationReport.input_form: dict[str, PipeInputFormDescriptor]` as a **required** field, `build_validation_report(..., input_form=...)` as a **required** kwarg. No default — the pipelex-server worker path must fail loudly at its next pipelex bump (shared-assembly rule: populated everywhere or nowhere), fixed by its own inbox item. The report always carries it; absence-by-default on the HTTP wire is the route's pop (the `rendered_markdown` precedent), which is `pipelex-api`'s item.+- **Wire absence of inapplicable slots:** the valid arm is dumped **without** `exclude_none`, so a flat model with `None`s would leak `"presence": null` everywhere. Give the field model a None-dropping `@model_serializer` (no slot legitimately carries JSON `null`: TOML cannot author a null default). Flat recursive model + per-kind validators, not a discriminated union — simpler, and D4 owns the TS types.+- **`title`: omitted in D2** (slot exists on the model; renderer falls back to `name` — never the mangled class name). H2 refines.+- **`description` for a flattened scalar:** the concept's authored description, else the payload field's. This is the E6 fix on the descriptor side: class-backed and native concepts get their blueprint/pinned description.+- **Cycle guard:** track the concept-ref path while recursing objects/lists; on revisit emit `unknown` (json_schema's `$ref`s keep the payload contract; the descriptor stays finite).+- **`refines` chain:** walk authored links immediate-parent-first to the end, qualified. A string-described / description-only concept reports `kind: "prose"` with `refines: ["native.Text"]` — this engine's stated fact (it generates a `TextContent` subclass and its `json_schema` is `{text}`), not shape invention.+- **Kind assignment table** (pinned by tests in Phase 3; chain-membership decides, never shape sniffing):+ - chain bottoms at / is `native.Text` (incl. string-promoted concepts) → `prose`; `native.Html` → `prose`; `native.Number` → `number` (`integer: false`); `native.YesNo` → `boolean`; `native.Date` → `date` (`datetime: false`); `native.Time` → `text` + `format: "time"`; `native.Document` → `document`; `native.Image` → `image`; `native.Page`, `native.TextAndImages`, `native.SearchResult` → `object` (pinned-blueprint fields); `native.Dynamic`, `native.Anything`, `native.JSON`, `native.Composite` → `unknown`.+ - structured concept → `object` (fields in declared order, recursing); nested field types: `text`→`text`, `integer`→`number`(`integer: true`), `number`→`number`, `boolean`→`boolean`, `date`→`date`(`datetime: false`), `datetime`→`date`(`datetime: true`), `time`→`text`+`format:"time"`, `choices` present → `enum` (choices win over `type`, matching the generator), `concept`→ recurse (with `concept_ref` — the E1 fact), `list`→`list` (item from `item_type`/`item_concept_ref`; inner `list` item → `unknown`), `dict`→`unknown`.+ - multi-field custom concept never flattens; flattening applies only via the native-chain rules above.+- **No new error class** — the derivation is total (`unknown` is the escape hatch); no `gei`/`gep` needed.+- **Keyword-only rule:** new functions keyword-only; if `build_input_form(pipes, ...)` keeps a positional subject, record the grant (`make sgr`) BEFORE running `make agent-check` (the auto-fixer silently keyword-onlys ungranted subjects).+- Rich ready-made fixture for tests: `tests/data/input_semantics/probe_bundle.mthds` (chains, class-backed, natives, defaults, single choice, `[N]`, `!`, `?`).++## Close-out state (2026-08-22) — what landed where++**All phases done.** What landed where:++- `pipelex/pipeline/input_form.py` — wire models, `build_input_form`, `InputFormDeriver`; `pipelex/codegen/native_expansion.py` — `reflect_structure_class`; `pipelex/pipeline/validation_report.py` + `validate_in_process.py` — the required `input_form` carriage.+- Tests: `tests/integration/pipelex/pipeline/test_input_form.py` (probe bundle + kind-table bundle), `tests/unit/pipelex/pipeline/test_input_form_models.py`, `tests/unit/pipelex/pipeline/test_input_form_deriver.py`, plus the carriage sweep and the trace-harness test.+- Docs: `docs/under-the-hood/input-form-descriptor.md` (nav'd), `docs/contribute/trace-input-semantics.md` (the `hop5_input_form.json` capture), the `## [Unreleased]` changelog entry.+- Sibling repos: `conformance/` branch `feature/Input-form-kind-table` (per-kind skeletons, skip-gated); workspace root `dev` (the spec's two new `> Verified by:` lines).+- Inbox: `../wip/inbox/2026-08-22-pipelex-api-validate-views-input-form.md` (the `views` opt-in + OpenAPI + the de-gating of the whole conformance module once the pin moves — this closes D2's gate) and `../wip/inbox/2026-08-22-pipelex-server-worker-input-form-carriage.md` (`temporal/`: carry `input_form` on `DryValidateResult`; rides the D3 pin cascade, fails loudly until then by design).++**Waiting on:** a `pipelex` release carrying the derivation, then the two inbox items. Nothing else in this repo.++Decisions taken while implementing (beyond the settled list above):++- **Signature is `build_input_form(pipes, *, blueprints)`**, not `crate=`: the deriver builds the qualified crate itself (`qualify_crate(LibraryCrateFactory.make_from_blueprints(...))`) so both assembly paths hand it the same thing they already hold. The `pipes` subject is granted in `subject_grants.toml`. The deriver class is public (`InputFormDeriver`, with `derive_slot` and `derive_concept`) so its escape hatches can be unit-tested on a hand-built crate without private access.+- **Inheritance of structure along a chain.** A refining concept with no structure of its own (`SpecialEntity refines BaseEntity`) is an `object` whose fields are the merged authored structures along its chain, base fields first, a refining concept overriding its parents' — because the validator requires `fields` on `object` and the test pins `object` for exactly this case. Precedence per node: merged dict structure → `object`; else the first `structure = "ClassName"` on the chain (self first) → class-backed; else a chain bottoming at a native → that native's kind with the concept's own `concept_ref`/description/`refines`; else prose promotion (`refines` = chain + `["native.Text"]`).+- **Class-backed reflection** goes through a new public `reflect_structure_class(*, structure_class)` in `pipelex/codegen/native_expansion.py` (the native probe now delegates to it). A native class name maps by identity (`TextContent` → the `native.Text` rules); any other registered `BaseModel` is reflected into blueprint form and rendered as `object`; unregistered or unmappable → `unknown`. A concept absent from the crate (a `library_dirs` load) takes the same path with the class named by its code.+- **Constraint slots come only from reflected classes.** The blueprint parser drops unknown keys (E7), so an authored `minimum = 0` never reaches the deriver; a registered class's `Field(gt=, ge=, lt=, le=, min_length=, max_length=, pattern=)` does, read from `FieldInfo.metadata` and stamped on `number` (bounds) and `text` (length/pattern) nodes only.+- **`[1]` is a single node.** The parser keeps `multiplicity = 1`, but `StuffSpec.is_multiple()` is `count > 1`, so the runtime takes one value, not a one-element list — the descriptor says the same (no `item`, no `item_count`, `gating: true`).+- **The cycle guard is unreachable from a bundle**: the library loader rejects concept cycles (`Cycle detected in concept references`) before `build_input_form` runs. It stays, because the derivation must be total on any crate handed to it, and is pinned at the deriver level.+- **Remaining natives as inputs** (`TextAndImages`, `SearchResult`, `Dynamic`, `Anything`, `JSON`) are exercised through a `PipeCompose`, because a PipeLLM's dry run treats a `Dynamic` input as an image. `Composite` is not a pipe input and has no row.+- **Nested concept fields** take the blueprint field's `description` and `required` over the concept's (the author described the field); a flattened scalar at the top level keeps the concept's description (E6).+- **Item nodes** reuse the parent field's `name` and report `required: true` (a list element is a value); nested `list` nodes copy the element's `concept_ref`/`refines` per the spec.+- **Enum comparisons** go through properties (`PresenceMarker.is_optional`, a new `FieldKind.is_list`) per the house match/case rule; the scalar-type mapping is one exhaustive `match` in `_scalar_field`.+- `make agent-check`'s keyword-only auto-fixer silently rewrote an internal helper's positional parameter mid-session — the helper was replaced by a keyword-only one; nothing else was touched by it.++## Phase 1 — Wire models + derivation (`pipelex/pipeline/input_form.py`)++- [x] TDD red: derivation + model tests written (see Session state above; paths differ slightly from the original sketch — integration tests live in `tests/integration/pipelex/pipeline/test_input_form.py`, model tests in `tests/unit/pipelex/pipeline/test_input_form_models.py`): key set equals `build_pipe_io_contracts`'s; authored slot order preserved; presence three-valued (`!` ≠ plain — E5); `required`/`gating` incl. the divergence (plain scalar `gating: true` vs plain `Concept[]` `required: true, gating: false`) and `?` (`required: false, gating: false`); `[N]` → `item_count` + `gating: true` (E4); empty-inputs pipe → `{ "fields": [] }`; namespaced `concept_ref` on every concept node incl. nested (E1); `refines` chain walked to the end, absent when nothing refined (E2); E3 both-facts; single-member `choices` list (E10); serialization drops inapplicable slots (no `null`s in `model_dump(mode="json")`).+- [x] Models: `FieldKind` StrEnum (closed union), recursive `InputFormField` (common slots + per-kind slots + reserved `examples`/`hints`), `PipeInputFormDescriptor` (`fields: list[InputFormField]`), all snake_case wire names per the spec's common-slots table (MTHDS-owned artifact — no `pipelex_` prefixes), None-dropping serializer, per-kind validators (`datetime` required on `date`, `choices` on `enum`, `fields` on `object`, `item` on `list`, `integer` on `number`).+- [x] Deriver: `build_input_form(pipes, *, blueprints) -> dict[str, PipeInputFormDescriptor]` — one public function per the spec's shared-assembly rule; internals per the decisions above.+- [x] Green + `make agent-check`.++## Phase 2 — Report carriage (both in-repo assembly points)++- [x] `PipelexValidationReport.input_form` (required field, docstringed per house style) + required `input_form` kwarg on `build_validation_report`.+- [x] `validate_in_process.py`: build the qualified crate and call `build_input_form` inside the library window, right beside `build_pipe_io_contracts` (the descriptor must be assembled before teardown for the same class-registry reason).+- [x] Sweep other report producers/consumers in-repo: `tests/unit/pipelex/pipeline/test_validation_report.py`, `test_runner_validate_plumbing.py`, `test_direct_bundle_validator.py`, `test_protocol_validate.py`, the agent-CLI validate envelope, `format_validate_markdown` — update constructions; nothing renders the descriptor in Markdown (it is a structured view, not text).+- [x] Integration assertion in `test_protocol_validate.py` (or a sibling): the in-process report carries `input_form` keyed like `pipe_io_contracts`.++**CP1 — DONE (commit "D2 CP1: input-form descriptor derivation + report carriage"):** models + derivation + carriage, `make agent-check` and the pipeline/codegen suites green. Decisions recorded in the session state above.++## Phase 3 — Pin the full kind-assignment table (pipelex tests)++- [x] Extend the unit tests with the complete per-native ruling (every `NativeConceptCode` as a direct input → its kind above), string-promoted concept → `prose` + `refines: ["native.Text"]`, class-backed reflection (e.g. `structure = "TextContent"` → flattened `prose` carrying the concept description — E6) and the unmappable → `unknown` fallback, nested `dict`/inner-list → `unknown`, `datetime`/`time` formats, cycle guard.+- [x] Pin whatever the parser does for `[1]` (an `is_multiple()` edge) in one test, reporting it as authored.+- [x] Constraint slots: populate from reflected `FieldInfo` metadata where the engine states them (`Gt`/`Ge`/`Lt`/`Le`/`MinLen`/`MaxLen`/pattern → `exclusive_minimum` etc.); test on a registered class with a constrained field (the `ImageContent.width` precedent).++**CP2 — DONE (commit "D2 CP2: pin the kind-assignment table and reflected constraint slots"):** assignment table pinned; `make agent-check` + full `make agent-test` green.++## Phase 4 — Conformance: per-kind coverage (sibling repo `conformance/`, own commit there)++- [x] Add per-kind skeleton tests to `conformance/tests/pipelex_api/test_validate_input_form.py`, skip-gated with the same `SKELETON_REASON` (the sibling boots a pinned PyPI runtime that predates the derivation): one bundle exercising the assignment table end to end (prose/document/image/number/boolean/single-member-enum/object-with-nested-concept_ref/list-with-`[N]`-item_count/date/unknown-dict), asserting kinds, `refines` membership, `presence`, E3 both-facts, and no-`null` inapplicable slots.+- [x] Do NOT touch the two live absent-by-default tests.+- [x] `make check-spec-links` in `conformance/` (new tests join the already-linked module; verify nothing drifted). Follow that repo's branch/PR convention for the commit.++**CP3 — DONE:** `conformance/` branch `feature/Input-form-kind-table` (commit "Pin the kind-assignment table skeletons in the input-form descriptor module", `make agent-check` green there) plus the spec's two new `> Verified by:` lines under *Field kinds* and *Structured multiplicity*, committed on the workspace root's `dev` ("Link the field-kinds and structured-multiplicity sections to their conformance skeletons"). The kind-table bundle was derived locally on this branch before the assertions were written, so the skeletons state what the deriver already produces.++## Phase 5 — Docs + changelog (this repo)++- [x] New docs page documenting the descriptor derivation: where it lives, the fact sources, the kind-assignment table, the gating rule, pointer to the workspace spec as the contract. Link it from the docs nav where natural (MkDocs conventions: blank line before lists).+- [x] `docs/contribute/trace-input-semantics.md` + harness: add the descriptor as a trace artifact (a hop beside `hop5_pipe_io_contracts.json`) so a mangled authored fact localizes into the new projection too — small, per the keep-useful-harnesses rule.+- [x] `CHANGELOG.md` under `## [Unreleased]`: bold-label condensed entry (breaking: `build_validation_report` requires `input_form`; the report gains the field).++## Phase 6 — File the two cross-repo follow-ups (workspace `wip/inbox/`, from here `../wip/inbox/`)++- [x] `YYYY-MM-DD-pipelex-api-validate-views-input-form.md` (use `_TEMPLATE.md`): add `views: list[str]` beside `render` with identical lenient mechanics (`validate.py:31/:59` precedent), resolve-then-attach-or-pop `input_form` on the valid arm only, regenerate the committed OpenAPI, bump the `pipelex` pin once released, then **de-gate the whole conformance module** (this closes D2's gate). Carry the evidence pointers (spec section, skeleton file/lines, this branch's derivation site).+- [x] `YYYY-MM-DD-pipelex-server-worker-input-form-carriage.md`: carry `input_form` on `DryValidateResult` inside the library window (`act_dry_validate.py:52`) and hand it to `build_validation_report` (`temporal_bundle_validator.py:107`); state plainly that the next pipelex bump fails loudly on the missing kwarg by design (shared-assembly rule) — rides D3's cascade. Name the member (`temporal/`) in the body.++## Phase 7 — Close out++- [x] Full `make agent-check` + `make agent-test` (the full suite — new test modules only get seen there).+- [x] Commit remaining work on `feature/Input-semantics-D2` with the CP structure above; no PR to `dev` (program ruling) — the PR is stacked on `feature/Input-semantics`.+- [x] Final checkpoint note in this file: what landed where, decisions taken, what the two inbox items are waiting on.+- [x] PR #1146 review round (stacked on `feature/Input-semantics`): greptile's one finding (library-dir concepts degraded to `unknown`) led to deriving over the library's accumulated crate instead of the bundle blueprints — `build_input_form(pipes)` no longer takes `blueprints`; the gstack pre-landing review's two clear wins (description-only and refining library-dir concepts) are covered by the same change and its test; its two decision-first items are deferred in `wip/input-semantics/deferred-descriptor-reflection-and-roundtrip.md`. cubic and Codex were out of quota for this PR.+- [x] `make check` + serial `make test` before the PR: one order-dependent failure in a `pipe_func` workdir test, unrelated to D2 (passes alone and under `agent-test`); deferred to `wip/input-semantics/deferred-serial-make-test-flake.md`.++## Deliberately out of scope (do not widen the diff)++- The `pipelex-api` route change (`views`) — Phase 6 item 1.+- The `pipelex-server/temporal/` worker carriage — Phase 6 item 2.+- Any S2 emission fix (E1–E10 in the schema chain): the descriptor reports authored intent from the blueprint, so none are prerequisites.+- The kernel swap (M1), SDK types (D4), hints (H1/H2), `@pipelex/runtime` parity (E1-track).diff --git a/wip/pytest-teardown-hang-leaked-threads.md b/wip/pytest-teardown-hang-leaked-threads.mdnew file mode 100644index 000000000..b7d001197--- /dev/null+++ b/wip/pytest-teardown-hang-leaked-threads.md@@ -0,0 +1,7 @@+# Full-suite pytest can hang AFTER the summary line (leaked non-daemon threads)++On 2026-08-23 a full `make test` run printed its complete summary (`1 failed, 10984 passed … in 0:12:24`) and then never exited. A `sample` of the process showed the main thread in `Py_Finalize -> atexit_callfuncs -> threading._shutdown -> ThreadHandle_join`, waiting forever on non-daemon worker threads, all parked in `lock_PyThread_acquire_lock` (the `queue.Queue.get()` consumer shape). The last test output before the summary came from `tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py` telemetry tests, so the prime suspect is a telemetry/analytics consumer thread created during a setup test and never flushed/joined. py-spy could not name the threads (requires root on macOS).++The hang is intermittent — the two checkpoint `make test` runs on the same branch exited normally — and predates the Engine-hints diff (which touches no threading or telemetry code). `make agent-test-debug` already guards against this class with an outer wall-clock timeout; plain `make test` does not.++Suggested fix direction (deferred): make the telemetry client used in setup tests either daemon-threaded or explicitly shut down in the test/fixture teardown; or add the outer timeout to `make test` the way `agent-test-debug` has one.