Skip to content

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

Input semantics: trace harness + input-form descriptor (#1147)

Louis Choquel46a3f5df254c
diff --git a/.badges/tests.json b/.badges/tests.json
index e0fc8d6ee..b32304c29 100644
--- a/.badges/tests.json
+++ b/.badges/tests.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"label": "tests",
- "message": "10727",
+ "message": "10757",
"color": "blue",
"cacheSeconds": 300
-}
\ No newline at end of file
+}
diff --git a/AGENTS.md b/AGENTS.md
index e62508af5..c21ef4f3a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -94,6 +94,12 @@
.venv/bin/pipelex-dev generate-error-identity
```
+ - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
+ ```
+
### Pipelex CLI Commands
To run the Pipelex CLI commands without the logo, you can use the `--no-logo` flag, this will avoid useless tokens in the console output.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d758ca296..584842ff7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
## [Unreleased]
+### Added
+
+- **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`.
+
### Changed
- **Ruff moves to 0.16.4, matching the version the VS Code extension bundles.** The extension now syncs `pyproject.toml` and `ruff.toml` documents to the language server, because Ruff from 0.16 on lints its own config files. A binary older than that parses those documents as Python source and paints phantom `invalid-syntax` diagnostics across every `pyproject.toml` — `requires-python = ...` read as `requires - python`. Pinning the dev dependency to the exact version the extension ships keeps the editor and the command line on one binary, so a rule can never fire in one and not the other. This is a dev-dependency change: nothing shipped changes, and there is no version bump.
diff --git a/CLAUDE.md b/CLAUDE.md
index 354ffb36c..a41fd932b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,6 +145,12 @@
.venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
```
+ - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
+ ```
+
- **`drift`**: Drift contracts — deterministic review obligations between code and docs, declared in the root `drift.toml` (see `docs/contribute/drift-contracts.md`). When `make drift-check` (part of `make agent-check`, `make check`, and CI) reports an open contract: run `make drift-plan` to see what changed and what to review, actually review the targets and fix what is stale, `git add` the trigger files (the digest reads the git index, not the working tree), then record the review with `make drift-ack CONTRACT=<id> RATIONALE="…"`. The rationale is the on-the-record review decision — write an honest sentence. There is no bypass flag; "reviewed, no doc change needed" is a legitimate rationale.
```bash
diff --git a/TODOS.md b/TODOS.md
new file mode 100644
index 000000000..df6911400
--- /dev/null
+++ b/TODOS.md
@@ -0,0 +1,111 @@
+# D2 — Input-form descriptor: reference derivation + report carriage
+
+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).
+
+**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]`, `!`, `?`).
+
+## Session state (updated 2026-08-22 at close-out — resume here after /compact or cold start)
+
+**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/docs/contribute/trace-input-semantics.md b/docs/contribute/trace-input-semantics.md
new file mode 100644
index 000000000..eff406edf
--- /dev/null
+++ b/docs/contribute/trace-input-semantics.md
@@ -0,0 +1,31 @@
+# Tracing Input Semantics
+
+`pipelex-dev trace-input-semantics` is an internal capture harness that answers one question with evidence instead of code-reading: **what does each hop of the input-schema emission chain do to every fact a method author writes?** Given one or more `.mthds` bundle files, it loads them through the validation library and dumps one artifact per hop of the chain that turns authored structure syntax into the `json_schema` emitted on `pipe_io_contracts`.
+
+```bash
+.venv/bin/pipelex-dev trace-input-semantics path/to/bundle.mthds -o output_dir
+```
+
+## What it captures
+
+The chain has five hops, and the output directory holds one artifact per hop, so a lost or mangled fact is localized to exactly one:
+
+- `hop1_bundle_blueprints.json` — **parse**: the `PipelexBundleBlueprint` dumps, i.e. what survived TOML.
+- `hop2_generated_sources/` — **resolve + generate**: the structure-class source the runtime generates per concept, re-derived with the same `StructureGenerator` calls the concept factory issues at load time. Saved as `.py.txt` so captures stay inert to linters.
+- `hop3_raw_pydantic_schemas/` — raw `model_json_schema()` per structure class, before any Pipelex render wrapping.
+- `hop4_schema_renders/` — the `SCHEMA` representation per pipe input: the `{"concept", "content"}` envelope, with array wrapping when the input is multiple.
+- `hop5_pipe_io_contracts.json` — the final wire contracts from `build_pipe_io_contracts`.
+- `hop5_input_form.json` — the input-form descriptors from `build_input_form`, the sibling projection that reads the authored blueprints directly instead of the emitted schema (see [Input-Form Descriptor](../under-the-hood/input-form-descriptor.md)). Captured beside the contracts so a fact can be checked on both sides: lost in the schema, stated in the descriptor.
+- `trace_manifest.json` — the capture inventory plus the wire framing per pipe input: authored ref string, resolved concept ref, multiplicity, presence marker.
+
+The tool is a tracer, not a report generator: it never mutates the loaded library, and any analysis of the captures (diffing hops, building a survival table) stays with the caller. Rerunning into the same output directory replaces the `hop2_generated_sources/`, `hop3_raw_pydantic_schemas/`, and `hop4_schema_renders/` capture directories wholesale, so no artifact from a removed or renamed concept, pipe, or input lingers from an earlier trace.
+
+## When to reach for it
+
+Use it whenever a change touches the emission chain — the structure blueprint, the structure generator, the schema render, the contract builder, or the input-form deriver — and you want to see what actually reaches the wire rather than reason about it. The committed probe bundle at `tests/data/input_semantics/probe_bundle.mthds` exercises every construct the language accepts (all field types, choices, defaults, required both ways, nesting, refinements, native concepts, and the `?` / `!` / `[]` / `[N]` input markers), and `tests/data/input_semantics/rejected/` holds deliberately-invalid fixtures pinning what the language refuses:
+
+```bash
+.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
+```
+
+The harness was built for the S1 input-semantics audit; its measured survival table and findings live with that audit's working documents. The integration test at `tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py` keeps the per-hop capture format honest.
diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.md
new file mode 100644
index 000000000..1c6aeda7a
--- /dev/null
+++ b/docs/under-the-hood/input-form-descriptor.md
@@ -0,0 +1,62 @@
+# Input-Form Descriptor
+
+Every valid `validate` report carries, beside `pipe_io_contracts`, an **input-form descriptor** per pipe: an ordered list of field descriptors a renderer can turn into a fill-in form with no schema heuristics, no hardcoded concept tables, and no description matching. The wire contract is the MTHDS spec `docs/specs/mthds-input-form-descriptor.md` at the workspace root; this page documents Pipelex's reference derivation of it.
+
+The descriptor exists because the emitted `json_schema` is a *payload* contract, and the projection that produces it loses facts a form needs: which concept a node is, what it refines, whether `!` or plain was authored, a fixed `[N]` count, an authored default beside `required`, a one-member choice list. The descriptor reports those facts from where they still exist — the authored blueprints — and leaves the payload shape to the schema. It is presentation; it never changes what a caller submits.
+
+## Where it lives
+
+- `pipelex/pipeline/input_form.py` — the wire models (`FieldKind`, `InputFormField`, `PipeInputFormDescriptor`), the one public derivation `build_input_form(pipes)`, and the `InputFormDeriver` behind it.
+- `PipelexValidationReport.input_form` (`pipelex/pipeline/validation_report.py`) — a **required** field, keyed exactly like `pipe_io_contracts`. `build_validation_report` requires it as a keyword: the shared-assembly rule says a report field is populated on every backend or none, so a backend that forgets it fails loudly instead of shipping an empty view.
+- `pipelex/pipeline/validate_in_process.py` — the in-process assembly derives it inside the validation library's window, right beside `build_pipe_io_contracts`.
+- `pipelex/codegen/native_expansion.py` — `reflect_structure_class`, the faithful-or-absent reflection of a registered structure class into blueprint form, shared with the native consistency probe.
+
+The report always carries the field. Whether it travels on the HTTP wire is the route's decision (absent unless a caller opts in), which belongs to the API.
+
+## Fact sources
+
+The derivation reads two things and nothing else:
+
+- **Slot facts** from the loaded pipes' `StuffSpec`s: the authored input order, the three-valued presence marker (`plain` / `optional` / `force`), and the multiplicity including a fixed `[N]` count. Iterating the same loaded pipes as `build_pipe_io_contracts` — `PipeSignature` placeholders and controller-inferred inputs included — is what makes the two key sets equal by construction.
+- **Concept facts** from the *qualified* library crate built from the parsed blueprints: descriptions, refinement links, structure fields with their defaults, choices, required-ness and nested concept refs. Qualified, not normalized: normalization flattens in-crate refinement, and the descriptor must report the `refines` chain as a list. Native concepts contribute their pinned blueprints; class-backed concepts (`structure = "ClassName"`) are reflected from the class registry, which is why the derivation must run while the validation library is still loaded.
+
+The derivation is total. A node it cannot map honestly reports `kind: "unknown"`, the renderer's raw escape hatch against the sibling `json_schema`; nothing raises.
+
+## Kind assignment
+
+Kinds are decided by chain membership and declared types — never by sniffing a schema shape. Per node, in precedence order:
+
+1. A concept with authored structure fields anywhere along its refinement chain is an `object`; its fields are the merged structures along the chain, base fields first, a refining concept overriding its parents'.
+2. Otherwise, the first `structure = "ClassName"` on the chain decides: a native class name (`TextContent`, `ImageContent`, …) maps by identity to that native's row; any other registered class is reflected field by field into an `object`; an unregistered or unmappable class is `unknown`.
+3. Otherwise, a chain bottoming at a native concept takes that native's row, keeping the concept's own `concept_ref`, description and `refines`.
+4. Otherwise — a description-only or string-described concept — `prose` with `refines` ending in `native.Text`: this engine backs such a concept with a `TextContent` subclass, so that is a stated fact, not shape invention.
+
+The 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`.
+
+| Native concept | Kind |
+|---|---|
+| `Text`, `Html` | `prose` |
+| `Number` | `number` with `integer: false` |
+| `YesNo` | `boolean` |
+| `Date` | `date` with `datetime: false` |
+| `Time` | `text` with `format: "time"` |
+| `Document` | `document` |
+| `Image` | `image` |
+| `Page`, `TextAndImages`, `SearchResult` | `object` over the pinned blueprint's fields |
+| `Dynamic`, `Anything`, `JSON` | `unknown` |
+
+Nested 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.
+
+## Required, presence and gating
+
+On a top-level field, `required` is `presence != "optional"`, and `gating` — whether the run is blocked until the caller provides content — is `required` and not a variable-multiplicity list. A plain `Concept[]` slot is therefore `required: true, gating: false`: its empty form is the legitimate value `[]`. A fixed-count `Concept[N]` slot is a `list` with `item_count: N` that gates like any scalar. `Concept[1]` is a single node, because the runtime takes one value there (`StuffSpec.is_multiple()` is `count > 1`), and the descriptor says what the runtime accepts. Nested fields carry neither `presence` nor `gating`; their `required` is the payload fact.
+
+## Wire shape
+
+Inapplicable slots are absent, never JSON `null`: the report's valid arm is dumped without `exclude_none`, so `InputFormField` owns its wire shape through a serializer that drops `None` values and writes the `date` kind's flag under its spec name `datetime`. Applicable falsy values (`required: false`, `integer: false`, `gating: false`) are kept. Per-kind validators keep a node honest at construction (`enum` needs `choices`, `object` needs `fields`, `list` needs `item`, `number` needs `integer`, `date` needs `datetime`).
+
+## 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`.
diff --git a/mkdocs.yml b/mkdocs.yml
index c1cf11286..92272891b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -317,6 +317,7 @@ plugins:
- under-the-hood/pipelex-kernel.md: "The Pipelex Kernel"
- under-the-hood/build-time-elaboration.md: "Build-time Elaboration"
- under-the-hood/codegen-projections.md: "Codegen Projections"
+ - under-the-hood/input-form-descriptor.md: "Input-Form Descriptor"
- under-the-hood/dry-run-mock-generation.md: "Dry Run Mock Generation"
- under-the-hood/execution-graph-tracing.md: "Execution Graph Tracing"
- under-the-hood/tokens-usage-wire-records.md: "TokensUsage Wire Records"
@@ -343,6 +344,7 @@ plugins:
- contribute/registration-surface.md: "Registration Surface"
- contribute/drift-contracts.md: "Drift Contracts"
- contribute/mthds-test-corpus.md: "MTHDS Test Corpus"
+ - contribute/trace-input-semantics.md: "Tracing Input Semantics"
- migration-ledger.md: "Migration Ledger"
- changelog.md: "Changelog"
@@ -563,6 +565,7 @@ nav:
- The Pipelex Kernel: under-the-hood/pipelex-kernel.md
- Build-time Elaboration: under-the-hood/build-time-elaboration.md
- Codegen Projections: under-the-hood/codegen-projections.md
+ - Input-Form Descriptor: under-the-hood/input-form-descriptor.md
- Dry Run Mock Generation: under-the-hood/dry-run-mock-generation.md
- Execution Graph Tracing: under-the-hood/execution-graph-tracing.md
- TokensUsage Wire Records: under-the-hood/tokens-usage-wire-records.md
@@ -589,6 +592,7 @@ nav:
- Registration Surface: contribute/registration-surface.md
- Drift Contracts: contribute/drift-contracts.md
- MTHDS Test Corpus: contribute/mthds-test-corpus.md
+ - Tracing Input Semantics: contribute/trace-input-semantics.md
- Migration Ledger: migration-ledger.md
- Code of Conduct: CODE_OF_CONDUCT.md
- License: license.md
diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.py
index d637169ec..ed0a81838 100644
--- a/pipelex/cli/dev_cli/_dev_cli.py
+++ b/pipelex/cli/dev_cli/_dev_cli.py
@@ -31,6 +31,7 @@ from pipelex.cli.dev_cli.commands.store_test_durations_cmd import store_test_dur
from pipelex.cli.dev_cli.commands.subject_grant_cmd import subject_grant_cmd
from pipelex.cli.dev_cli.commands.sync_kit_configs_cmd import sync_kit_configs_cmd
from pipelex.cli.dev_cli.commands.sync_main_config_cmd import SyncTarget, sync_main_config_cmd
+from pipelex.cli.dev_cli.commands.trace_input_semantics_cmd import trace_input_semantics_cmd
from pipelex.cli.dev_cli.commands.update_gateway_models_cmd import update_gateway_models_cmd
from pipelex.cli.dev_cli.commands.update_migration_schemas_cmd import update_migration_schemas_cmd
from pipelex.runtime_hub import get_console
@@ -65,6 +66,7 @@ class PipelexDevCLI(TyperGroup):
"subject-grant",
"sync-kit-configs",
"sync-main-config",
+ "trace-input-semantics",
"update-gateway-models",
"update-migration-schemas",
]
@@ -504,6 +506,16 @@ def sync_kit_configs_command(
sys.exit(1)
[email protected](name="trace-input-semantics", help="Dump one artifact per hop of the input-schema emission chain for a bundle")
+def trace_input_semantics_command(
+ bundles: Annotated[list[Path], typer.Argument(help="MTHDS bundle file(s) to load as one batch")],
+ output_dir: Annotated[Path, typer.Option("--output-dir", "-o", help="Directory receiving the per-hop artifacts")],
+ allow_signatures: Annotated[bool, typer.Option("--allow-signatures", help="Tolerate unimplemented pipe signatures")] = False,
+) -> None:
+ """Trace what each hop of the emission chain does to every authored input fact."""
+ trace_input_semantics_cmd(bundle_paths=bundles, output_dir=output_dir, allow_signatures=allow_signatures)
+
+
@app.command(name="preprocess-test-models", help="Preprocess test models and generate fixture files")
def preprocess_test_models_command(
profile: Annotated[str, typer.Option("--profile", "-p", help="Test profile to use (ci, dev, coverage, full)")] = "dev",
diff --git a/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py b/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py
new file mode 100644
index 000000000..dfa650908
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py
@@ -0,0 +1,377 @@
+"""Capture harness for the input-semantics audit: per-hop dumps of the input-schema emission chain.
+
+Given one or more MTHDS bundle files, this tool loads them through the validation library and,
+inside the validation window, dumps one artifact per hop of the chain that turns authored `.mthds`
+facts into the `json_schema` emitted on `pipe_io_contracts`:
+
+- ``hop1_bundle_blueprints.json`` — parse: the `PipelexBundleBlueprint` dumps (what survived TOML).
+- ``hop2_generated_sources/`` — resolve + generate: the structure-class source the runtime
+ generates per concept, re-derived with the same `StructureGenerator` calls
+ `ConceptFactory.make_from_blueprint` issues at load time.
+- ``hop3_raw_pydantic_schemas/`` — raw `model_json_schema()` per concept's structure class,
+ before any Pipelex render wrapping.
+- ``hop4_schema_renders/`` — the `ConceptRepresentationFormat.SCHEMA` render per pipe input
+ (the `{"concept": ..., "content": ...}` envelope, with array wrapping when multiple).
+- ``hop5_pipe_io_contracts.json`` — the final wire contracts from `build_pipe_io_contracts`.
+- ``hop5_input_form.json`` — the input-form descriptors from `build_input_form`, the projection
+ that reads the authored facts directly (a fact lost on the schema side should survive here).
+- ``trace_manifest.json`` — the capture inventory plus the wire framing per pipe input
+ (authored ref string, resolved concept ref, multiplicity, presence marker).
+
+The tool is a tracer, not a report generator: it never mutates the loaded library, and analysis
+of the captures (e.g. a survival table) stays with the caller.
+"""
+
+import asyncio
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.cli.cli_factory import make_pipelex_for_cli
+from pipelex.cli.error_handlers import ErrorContext
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
+from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
+from pipelex.core.concepts.helpers import make_qualified_structure_class_name, normalize_structure_blueprint
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.structure_generation.generator import StructureGenerator
+from pipelex.core.qualified_ref import QualifiedRef
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.interpreter_hub import (
+ clear_current_library,
+ get_concept_library,
+ get_current_library_id_or_none,
+ get_library_manager,
+ set_current_library,
+)
+from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
+from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
+from pipelex.pipelex import Pipelex
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.input_form import build_input_form
+from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.runtime_hub import get_console
+
+MANIFEST_FILE_NAME = "trace_manifest.json"
+HOP1_FILE_NAME = "hop1_bundle_blueprints.json"
+HOP2_DIR_NAME = "hop2_generated_sources"
+HOP3_DIR_NAME = "hop3_raw_pydantic_schemas"
+HOP4_DIR_NAME = "hop4_schema_renders"
+HOP5_FILE_NAME = "hop5_pipe_io_contracts.json"
+HOP5_INPUT_FORM_FILE_NAME = "hop5_input_form.json"
+
+
+def _write_json(*, path: Path, payload: Any) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def regenerate_structure_source(
+ *,
+ domain_code: str,
+ concept_code: str,
+ declaration: ConceptBlueprint | str,
+) -> str | None:
+ """Re-derive the structure-class source the runtime generated for one concept declaration.
+
+ Mirrors the generation branches of `ConceptFactory.make_from_blueprint`
+ (pipelex/core/concepts/concept_factory.py) with the same `StructureGenerator` arguments, so the
+ captured source is what the factory produced at load time. Returns None for a
+ `structure = "ClassName"` declaration (the factory generates nothing there — the class
+ pre-exists in the registry). Must run inside the validation window: generated code that
+ inherits a bundle-defined base class resolves it through the class registry.
+ """
+ qualified_class_name = make_qualified_structure_class_name(domain_code=domain_code, concept_code=concept_code)
+
+ if isinstance(declaration, str):
+ source, _ = StructureGenerator().generate_from_structure_blueprint(
+ class_name=qualified_class_name,
+ structure_blueprint={},
+ base_class_name=TextContent.__name__,
+ description=declaration,
+ )
+ return source
+
+ if isinstance(declaration.structure, str):
+ return None
+
+ if isinstance(declaration.structure, dict):
+ normalized_structure = normalize_structure_blueprint(declaration.structure)
+ source, _ = StructureGenerator(local_domain=domain_code).generate_from_structure_blueprint(
+ class_name=qualified_class_name,
+ structure_blueprint=normalized_structure,
+ description=declaration.description,
+ )
+ return source
+
+ if declaration.refines is not None:
+ current_refine = ConceptFactory.make_refine(refine=declaration.refines, domain_code=domain_code)
+ if QualifiedRef.has_cross_package_prefix(current_refine):
+ source, _ = StructureGenerator().generate_from_structure_blueprint(
+ class_name=qualified_class_name,
+ structure_blueprint={},
+ description=declaration.description,
+ )
+ return source
+ refined_ref = QualifiedRef.parse(current_refine)
+ refined_concept_code = refined_ref.local_code
+ if NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=current_refine):
+ refined_structure_class_name = refined_concept_code + "Content"
+ else:
+ refined_domain_code = refined_ref.domain_path or domain_code
+ refined_structure_class_name = make_qualified_structure_class_name(domain_code=refined_domain_code, concept_code=refined_concept_code)
+ source, _ = StructureGenerator().generate_from_structure_blueprint(
+ class_name=qualified_class_name,
+ structure_blueprint={},
+ base_class_name=refined_structure_class_name,
+ description=declaration.description,
+ )
+ return source
+
+ # Basic blueprint (description only): the factory generates an empty TextContent subclass.
+ source, _ = StructureGenerator().generate_from_structure_blueprint(
+ class_name=qualified_class_name,
+ structure_blueprint={},
+ base_class_name=TextContent.__name__,
+ description=declaration.description,
+ )
+ return source
+
+
+def _capture_hop1(*, blueprints: list[PipelexBundleBlueprint], output_dir: Path) -> str:
+ payload = [blueprint.model_dump(mode="json") for blueprint in blueprints]
+ _write_json(path=output_dir / HOP1_FILE_NAME, payload=payload)
+ return HOP1_FILE_NAME
+
+
+def _capture_hop2(*, blueprints: list[PipelexBundleBlueprint], output_dir: Path) -> dict[str, str | None]:
+ captures: dict[str, str | None] = {}
+ for blueprint in blueprints:
+ if not blueprint.concept:
+ continue
+ for concept_code, declaration in blueprint.concept.items():
+ concept_ref = f"{blueprint.domain}.{concept_code}"
+ source = regenerate_structure_source(domain_code=blueprint.domain, concept_code=concept_code, declaration=declaration)
+ if source is None:
+ captures[concept_ref] = None
+ continue
+ # `.py.txt` on purpose: these are evidence artifacts, not code — a bare `.py`
+ # extension would drag them into the repo's linters when captured under wip/.
+ relative_path = f"{HOP2_DIR_NAME}/{concept_ref}.py.txt"
+ source_path = output_dir / relative_path
+ source_path.parent.mkdir(parents=True, exist_ok=True)
+ source_path.write_text(source, encoding="utf-8")
+ captures[concept_ref] = relative_path
+ return captures
+
+
+def _collect_traced_concept_refs(*, blueprints: list[PipelexBundleBlueprint], pipes: list[PipeAbstract]) -> list[str]:
+ """Every concept the trace must render: bundle-declared concepts plus every pipe-input concept."""
+ concept_refs: list[str] = []
+ for blueprint in blueprints:
+ if not blueprint.concept:
+ continue
+ for concept_code in blueprint.concept:
+ concept_refs.append(f"{blueprint.domain}.{concept_code}")
+ for pipe in pipes:
+ for stuff_spec in pipe.inputs.root.values():
+ concept_refs.append(stuff_spec.concept.concept_ref)
+ # Preserve first-seen order while deduplicating.
+ return list(dict.fromkeys(concept_refs))
+
+
+def _capture_hop3(
+ *,
+ concept_refs: list[str],
+ concept_provider: ConceptProviderAbstract,
+ output_dir: Path,
+) -> tuple[dict[str, str], list[str]]:
+ captures: dict[str, str] = {}
+ skipped: list[str] = []
+ for concept_ref in concept_refs:
+ concept = concept_provider.get_required_concept(concept_ref)
+ if not concept.declares_a_structure_class:
+ skipped.append(f"{concept_ref}: declares no structure class")
+ continue
+ structure_class = concept_provider.get_structure_class(concept=concept)
+ relative_path = f"{HOP3_DIR_NAME}/{concept_ref}.json"
+ _write_json(path=output_dir / relative_path, payload=structure_class.model_json_schema())
+ captures[concept_ref] = relative_path
+ return captures, skipped
+
+
+def _capture_hop4(
+ *,
+ pipes: list[PipeAbstract],
+ concept_provider: ConceptProviderAbstract,
+ output_dir: Path,
+) -> dict[str, str]:
+ captures: dict[str, str] = {}
+ for pipe in pipes:
+ for var_name, stuff_spec in pipe.inputs.root.items():
+ render = stuff_spec.render_stuff_spec(concept_provider=concept_provider, output_format=ConceptRepresentationFormat.SCHEMA)
+ relative_path = f"{HOP4_DIR_NAME}/{pipe.pipe_ref}__{var_name}.json"
+ _write_json(path=output_dir / relative_path, payload=render)
+ captures[f"{pipe.pipe_ref}.{var_name}"] = relative_path
+ return captures
+
+
+def _capture_hop5(*, pipes: list[PipeAbstract], output_dir: Path) -> str:
+ io_contracts = build_pipe_io_contracts(pipes)
+ payload = {pipe_ref: contract.model_dump(mode="json") for pipe_ref, contract in io_contracts.items()}
+ _write_json(path=output_dir / HOP5_FILE_NAME, payload=payload)
+ return HOP5_FILE_NAME
+
+
+def _capture_hop5_input_form(*, pipes: list[PipeAbstract], output_dir: Path) -> str:
+ """The descriptor projection, captured beside the schema one so the two can be diffed fact by fact."""
+ input_form = build_input_form(pipes)
+ payload = {pipe_ref: descriptor.model_dump(mode="json") for pipe_ref, descriptor in input_form.items()}
+ _write_json(path=output_dir / HOP5_INPUT_FORM_FILE_NAME, payload=payload)
+ return HOP5_INPUT_FORM_FILE_NAME
+
+
+def _build_wire_framing(*, blueprints: list[PipelexBundleBlueprint], pipes: list[PipeAbstract]) -> list[dict[str, Any]]:
+ """One entry per pipe input: what the author wrote versus what the loaded spec resolved it to."""
+ authored_specs: dict[str, str] = {}
+ for blueprint in blueprints:
+ if not blueprint.pipe:
+ continue
+ for pipe_code, pipe_blueprint in blueprint.pipe.items():
+ if not pipe_blueprint.inputs:
+ continue
+ for var_name, authored in pipe_blueprint.inputs.items():
+ authored_specs[f"{blueprint.domain}.{pipe_code}.{var_name}"] = authored
+
+ framing: list[dict[str, Any]] = []
+ for pipe in pipes:
+ for var_name, stuff_spec in pipe.inputs.root.items():
+ framing.append(
+ {
+ "pipe_ref": pipe.pipe_ref,
+ "input_name": var_name,
+ "authored_spec": authored_specs.get(f"{pipe.pipe_ref}.{var_name}"),
+ "concept_ref": stuff_spec.concept.concept_ref,
+ "multiplicity": stuff_spec.multiplicity,
+ "presence": stuff_spec.presence,
+ "is_multiple": stuff_spec.is_multiple(),
+ }
+ )
+ return framing
+
+
+async def trace_input_semantics(
+ *,
+ bundle_paths: list[Path],
+ output_dir: Path,
+ allow_signatures: bool = False,
+) -> dict[str, Any]:
+ """Validate the given bundles and dump one artifact per hop of the input-schema chain.
+
+ Runs `validate_bundle` and performs every capture inside the validation window (the schema
+ renders resolve bundle-defined structure classes through the loaded library), then restores
+ the caller's current library and tears the validation library down.
+
+ Args:
+ bundle_paths: The `.mthds` files to load as one bundle batch.
+ output_dir: Directory receiving the per-hop artifacts (created if missing).
+ allow_signatures: Tolerate unimplemented pipe signatures, as `validate_bundle` does.
+
+ Returns:
+ The manifest dict, also written to ``trace_manifest.json`` in ``output_dir``.
+
+ Raises:
+ ValidateBundleError: When the bundle is invalid — the trace requires a valid bundle.
+ """
+ mthds_contents = [bundle_path.read_text(encoding="utf-8") for bundle_path in bundle_paths]
+ mthds_sources = [str(bundle_path) for bundle_path in bundle_paths]
+
+ output_dir.mkdir(parents=True, exist_ok=True)
+ # The per-item hop directories accumulate one file per concept / per pipe input, so a rerun
+ # into the same output directory must replace them wholesale — a leftover capture from a
+ # removed or renamed declaration would read as part of the current trace.
+ for hop_dir_name in (HOP2_DIR_NAME, HOP3_DIR_NAME, HOP4_DIR_NAME):
+ stale_hop_dir = output_dir / hop_dir_name
+ if stale_hop_dir.is_dir():
+ shutil.rmtree(stale_hop_dir)
+
+ prev_library_id = get_current_library_id_or_none()
+ validation_library_id: str | None = None
+ try:
+ result = await validate_bundle(
+ mthds_contents=mthds_contents,
+ mthds_sources=mthds_sources,
+ allow_signatures=allow_signatures,
+ )
+ validation_library_id = get_current_library_id_or_none()
+ concept_provider = get_concept_library()
+
+ hop1_capture = _capture_hop1(blueprints=result.blueprints, output_dir=output_dir)
+ hop2_captures = _capture_hop2(blueprints=result.blueprints, output_dir=output_dir)
+ concept_refs = _collect_traced_concept_refs(blueprints=result.blueprints, pipes=result.pipes)
+ hop3_captures, hop3_skipped = _capture_hop3(concept_refs=concept_refs, concept_provider=concept_provider, output_dir=output_dir)
+ hop4_captures = _capture_hop4(pipes=result.pipes, concept_provider=concept_provider, output_dir=output_dir)
+ hop5_capture = _capture_hop5(pipes=result.pipes, output_dir=output_dir)
+ hop5_input_form_capture = _capture_hop5_input_form(pipes=result.pipes, output_dir=output_dir)
+ wire_framing = _build_wire_framing(blueprints=result.blueprints, pipes=result.pipes)
+ finally:
+ if validation_library_id is not None and validation_library_id != prev_library_id:
+ if prev_library_id is not None:
+ set_current_library(library_id=prev_library_id)
+ else:
+ clear_current_library()
+ get_library_manager().teardown(library_id=validation_library_id)
+
+ manifest: dict[str, Any] = {
+ "bundle_paths": mthds_sources,
+ "hop1_bundle_blueprints": hop1_capture,
+ "hop2_generated_sources": hop2_captures,
+ "hop3_raw_pydantic_schemas": hop3_captures,
+ "hop3_skipped": hop3_skipped,
+ "hop4_schema_renders": hop4_captures,
+ "hop5_pipe_io_contracts": hop5_capture,
+ "hop5_input_form": hop5_input_form_capture,
+ "wire_framing": wire_framing,
+ }
+ _write_json(path=output_dir / MANIFEST_FILE_NAME, payload=manifest)
+ return manifest
+
+
+def trace_input_semantics_cmd(*, bundle_paths: list[Path], output_dir: Path, allow_signatures: bool = False) -> None:
+ """CLI wrapper: boot Pipelex, run the trace, report the artifact inventory."""
+ console = get_console()
+ for bundle_path in bundle_paths:
+ if not bundle_path.is_file():
+ console.print(f"[red]Bundle file not found: {bundle_path}[/red]")
+ sys.exit(2)
+
+ make_pipelex_for_cli(context=ErrorContext.VALIDATION, needs_inference=False, needs_model_specs=True)
+ try:
+ manifest = asyncio.run(
+ trace_input_semantics(
+ bundle_paths=bundle_paths,
+ output_dir=output_dir,
+ allow_signatures=allow_signatures,
+ )
+ )
+ except ValidateBundleError as exc:
+ console.print(f"[red]Bundle validation failed — the trace requires a valid bundle:[/red]\n{exc}")
+ sys.exit(1)
+ except PipelexError as exc:
+ console.print(f"[red]Trace failed:[/red]\n{exc}")
+ sys.exit(1)
+ finally:
+ Pipelex.teardown_if_needed()
+
+ console.print(f"[green]✓ Input-semantics trace written to {output_dir}[/green]")
+ console.print(f" hop 1: {manifest['hop1_bundle_blueprints']}")
+ console.print(f" hop 2: {len(manifest['hop2_generated_sources'])} generated sources under {HOP2_DIR_NAME}/")
+ console.print(f" hop 3: {len(manifest['hop3_raw_pydantic_schemas'])} raw schemas under {HOP3_DIR_NAME}/")
+ console.print(f" hop 4: {len(manifest['hop4_schema_renders'])} schema renders under {HOP4_DIR_NAME}/")
+ console.print(f" hop 5: {manifest['hop5_pipe_io_contracts']} + {manifest['hop5_input_form']}")
+ console.print(f" manifest: {MANIFEST_FILE_NAME}")
diff --git a/pipelex/codegen/native_expansion.py b/pipelex/codegen/native_expansion.py
index 154fb75c3..5bea43011 100644
--- a/pipelex/codegen/native_expansion.py
+++ b/pipelex/codegen/native_expansion.py
@@ -58,7 +58,18 @@ def reflect_native_structure(native_code: NativeConceptCode) -> dict[str, Concep
structure_class = native_code.structure_class
if structure_class is None:
return None
- model_fields = cast("type[StuffContent]", structure_class).model_fields
+ return reflect_structure_class(structure_class=cast("type[BaseModel]", structure_class))
+
+
+def reflect_structure_class(*, structure_class: type[BaseModel]) -> dict[str, ConceptStructureBlueprintType] | None:
+ """Reflect a registered structure class into blueprint form, faithful-or-absent.
+
+ Same rules as native reflection: every field must map unambiguously to a blueprint field, or
+ the whole reflected structure is absent (`None`) — never a guessed shape. The input-form
+ deriver uses this for class-backed concepts (`structure = "ClassName"`), where the class is
+ the only statement of the payload's fields.
+ """
+ model_fields = structure_class.model_fields
if not model_fields:
return None
try:
diff --git a/pipelex/kit/agent_rules/codex_commands.md b/pipelex/kit/agent_rules/codex_commands.md
index 5dafcc587..99259bc89 100644
--- a/pipelex/kit/agent_rules/codex_commands.md
+++ b/pipelex/kit/agent_rules/codex_commands.md
@@ -92,6 +92,12 @@
.venv/bin/pipelex-dev generate-error-identity
```
+ - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
+ ```
+
## Pipelex CLI Commands
To run the Pipelex CLI commands without the logo, you can use the `--no-logo` flag, this will avoid useless tokens in the console output.
diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.md
index 530458bf3..dcac95f5a 100644
--- a/pipelex/kit/agent_rules/commands.md
+++ b/pipelex/kit/agent_rules/commands.md
@@ -143,6 +143,12 @@
.venv/bin/pipelex-dev refresh-graph-ui-sri --mthds-ui-version 0.6.3 --elkjs-version 0.11.1
```
+ - **`trace-input-semantics`**: Capture harness for the input-schema emission chain — given one or more `.mthds` bundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. See `docs/contribute/trace-input-semantics.md`.
+
+ ```bash
+ .venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-trace
+ ```
+
- **`drift`**: Drift contracts — deterministic review obligations between code and docs, declared in the root `drift.toml` (see `docs/contribute/drift-contracts.md`). When `make drift-check` (part of `make agent-check`, `make check`, and CI) reports an open contract: run `make drift-plan` to see what changed and what to review, actually review the targets and fix what is stale, `git add` the trigger files (the digest reads the git index, not the working tree), then record the review with `make drift-ack CONTRACT=<id> RATIONALE="…"`. The rationale is the on-the-record review decision — write an honest sentence. There is no bypass flag; "reviewed, no doc change needed" is a legitimate rationale.
```bash
diff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.py
new file mode 100644
index 000000000..8000d9ef3
--- /dev/null
+++ b/pipelex/pipeline/input_form.py
@@ -0,0 +1,626 @@
+"""Per-pipe input-form descriptors (`input_form`) for the validate surfaces.
+
+This is the reference derivation of the MTHDS input-form descriptor (workspace spec
+`docs/specs/mthds-input-form-descriptor.md`): for each loaded pipe, an ordered list of field
+descriptors a renderer can turn into a fill-in form with no schema heuristics, no hardcoded
+concept tables, and no description matching. It is keyed by the same namespaced `pipe_ref` set as
+`pipe_io_contracts` — both are built from the same loaded pipes, so the key spaces are equal by
+construction.
+
+The descriptor is derived from **authored facts, never from the emitted JSON Schema**. Two fact
+sources feed it:
+
+- **Slot facts** come from the loaded pipes' `StuffSpec`s: authored input order, the three-valued
+ presence marker (`plain` / `optional` / `force`), and the multiplicity including a fixed `[N]`
+ count. `required` and `gating` are derived here, per the spec's stated rule.
+- **Concept facts** come from the *qualified* library crate built from the parsed blueprints —
+ qualified, not normalized, because normalization flattens in-crate refinement and the descriptor
+ must report the `refines` chain as a list. Authored concepts contribute their description,
+ refinement links and structure fields (defaults, choices, required-ness, nested concept refs —
+ everything the schema projection loses); native concepts contribute their pinned blueprints;
+ class-backed concepts (`structure = "ClassName"`) are reflected from the class registry.
+
+The derivation is total: a node that cannot be mapped honestly reports `kind: "unknown"`, the
+renderer's raw escape hatch against the sibling `json_schema`. Call it inside the validation
+library's window, beside `build_pipe_io_contracts`: class-backed reflection reads the class
+registry, and bundle-defined classes are only reliably current while their library is loaded.
+"""
+
+from collections.abc import Sequence
+from enum import StrEnum
+from typing import Any
+
+from annotated_types import Ge, Gt, Le, Lt, MaxLen, MinLen
+from pydantic import BaseModel, Field, SerializerFunctionWrapHandler, model_serializer, model_validator
+from pydantic.fields import FieldInfo
+from typing_extensions import Self
+
+from pipelex.codegen.native_expansion import reflect_structure_class
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint, ConceptStructureBlueprintType
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.native.pinned_blueprints import make_pinned_native_blueprint
+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.interpreter_hub import get_current_library, get_library_manager
+from pipelex.libraries.crate_qualification import qualify_crate
+from pipelex.libraries.library_crate_factory import LibraryCrateFactory
+from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
+from pipelex.system.registries.class_registry_access import get_class_registry
+
+
+class FieldKind(StrEnum):
+ """The closed `kind` union of the input-form descriptor — field intents, never widget names."""
+
+ TEXT = "text"
+ PROSE = "prose"
+ DATE = "date"
+ NUMBER = "number"
+ BOOLEAN = "boolean"
+ ENUM = "enum"
+ DOCUMENT = "document"
+ IMAGE = "image"
+ OBJECT = "object"
+ LIST = "list"
+ UNKNOWN = "unknown"
+
+ @property
+ def is_list(self) -> bool:
+ match self:
+ case FieldKind.LIST:
+ return True
+ case (
+ FieldKind.TEXT
+ | FieldKind.PROSE
+ | FieldKind.DATE
+ | FieldKind.NUMBER
+ | FieldKind.BOOLEAN
+ | FieldKind.ENUM
+ | FieldKind.DOCUMENT
+ | FieldKind.IMAGE
+ | FieldKind.OBJECT
+ | FieldKind.UNKNOWN
+ ):
+ return False
+
+
+class InputFormField(BaseModel):
+ """One field descriptor: a recursive node discriminated on `kind`.
+
+ Every wire name is the spec's snake_case slot name. Inapplicable slots are dropped at
+ serialization rather than emitted as JSON `null` — the report's valid arm is dumped without
+ `exclude_none`, so the model owns its own wire shape. Applicable falsy values (`required: false`,
+ `integer: false`, ...) are kept.
+ """
+
+ kind: FieldKind = Field(strict=False)
+ name: str
+ """The identifier as authored: the input slot name on a top-level field, the structure field
+ name on a nested one. Unused on a `list`'s `item` (the index labels items)."""
+
+ title: str | None = None
+ """Human label; a renderer falls back to `name`. Never the generated class name."""
+
+ concept_ref: str | None = None
+ """The namespaced concept ref on every concept-typed node (`native.Document`, `demo.Invoice`).
+ On a `list` node it names the ELEMENT concept."""
+
+ refines: list[str] | None = None
+ """The concept's refinement chain, immediate parent first, walked to its end. Absent when the
+ concept refines nothing."""
+
+ description: str | None = None
+ required: bool
+ """Top-level: the caller must supply the slot (`presence != "optional"`). Nested: the field must
+ be present within the concept's payload. The two levels never interact."""
+
+ presence: PresenceMarker | None = Field(default=None, strict=False)
+ """The authored presence marker of the pipe's input slot, three-valued so `!` is not flattened.
+ Top-level fields only."""
+
+ gating: bool | None = None
+ """Top-level fields only: the run cannot start until this slot has content. Stated rather than
+ re-derived from `required` — a variable-multiplicity list never gates (`[]` is its legitimate
+ value) while a fixed-count one does."""
+
+ default_value: Any | None = None
+ """The value applied when the caller omits the field — present only when a default was authored,
+ 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."""
+
+ # `text` / `prose` constraint slots.
+ min_length: int | None = None
+ max_length: int | None = None
+ pattern: str | None = None
+ format: str | None = None
+ # `date`: the `datetime` wire slot (the attribute name avoids shadowing the stdlib module).
+ datetime_flag: bool | None = None
+ # `number` slots.
+ integer: bool | None = None
+ minimum: float | None = None
+ maximum: float | None = None
+ exclusive_minimum: float | None = None
+ exclusive_maximum: float | None = None
+ # `enum`.
+ choices: list[Any] | None = None
+ # `object`.
+ fields: list["InputFormField"] | None = None
+ # `list`.
+ item: "InputFormField | None" = None
+ item_count: int | None = None
+ """Present exactly when the slot was authored with a fixed `[N]` multiplicity."""
+
+ @model_validator(mode="after")
+ def validate_per_kind_slots(self) -> Self:
+ match self.kind:
+ case FieldKind.ENUM:
+ if not self.choices:
+ msg = f"Field '{self.name}' of kind 'enum' must carry a non-empty 'choices' list"
+ raise ValueError(msg)
+ case FieldKind.OBJECT:
+ if self.fields is None:
+ msg = f"Field '{self.name}' of kind 'object' must carry 'fields'"
+ raise ValueError(msg)
+ case FieldKind.LIST:
+ if self.item is None:
+ msg = f"Field '{self.name}' of kind 'list' must carry 'item'"
+ raise ValueError(msg)
+ case FieldKind.NUMBER:
+ if self.integer is None:
+ msg = f"Field '{self.name}' of kind 'number' must state 'integer'"
+ raise ValueError(msg)
+ case FieldKind.DATE:
+ if self.datetime_flag is None:
+ msg = f"Field '{self.name}' of kind 'date' must state 'datetime'"
+ raise ValueError(msg)
+ case FieldKind.TEXT | FieldKind.PROSE | FieldKind.BOOLEAN | FieldKind.DOCUMENT | FieldKind.IMAGE | FieldKind.UNKNOWN:
+ pass
+ return self
+
+ @model_serializer(mode="wrap")
+ def serialize_without_inapplicable_slots(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+ dumped: dict[str, Any] = handler(self)
+ wire = {slot: value for slot, value in dumped.items() if value is not None}
+ if "datetime_flag" in wire:
+ wire["datetime"] = wire.pop("datetime_flag")
+ return wire
+
+
+class PipeInputFormDescriptor(BaseModel):
+ """The input form of one pipe — an `input_form` entry."""
+
+ fields: list[InputFormField]
+ """One field descriptor per input slot, in authored input order. Empty for a pipe with no inputs."""
+
+
+def build_input_form(pipes: Sequence[PipeAbstract]) -> dict[str, PipeInputFormDescriptor]:
+ """Derive the `input_form` descriptors of loaded pipes from the authored blueprints of the current library.
+
+ Works on any loaded `PipeAbstract`, `PipeSignature` placeholders included, iterating exactly
+ as `build_pipe_io_contracts` does so the two artifacts share one key set. Must run while the
+ validation library is still loaded (see the module docstring): the authored facts are the
+ library's accumulated crate, which covers the validated bundle and every `library_dirs`
+ bundle loaded beside it, so a concept from a library dir is derived exactly like a local one.
+
+ Args:
+ pipes: The loaded pipes to describe (typically `ValidateBundleResult.pipes`).
+
+ Returns:
+ `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)
+ 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()]
+ input_form[pipe.pipe_ref] = PipeInputFormDescriptor(fields=fields)
+ return input_form
+
+
+class InputFormDeriver:
+ """Derives field descriptors over one qualified crate's concepts (`QualifiedCrateContent.concepts`)."""
+
+ def __init__(self, *, concepts: dict[str, ConceptBlueprint | str]) -> None:
+ self._concepts = concepts
+
+ # ---- 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."""
+ node = self._concept_node(name=name, concept_ref=stuff_spec.concept.concept_ref, seen=frozenset())
+ if stuff_spec.is_multiple():
+ multiplicity = stuff_spec.multiplicity
+ item_count = multiplicity if isinstance(multiplicity, int) and not isinstance(multiplicity, bool) else None
+ node = InputFormField(
+ kind=FieldKind.LIST,
+ name=name,
+ concept_ref=node.concept_ref,
+ refines=node.refines,
+ description=node.description,
+ required=True,
+ item=node,
+ item_count=item_count,
+ )
+ presence = stuff_spec.presence
+ required = not presence.is_optional
+ gating = required and not (node.kind.is_list and node.item_count is None)
+ return node.model_copy(update={"presence": presence, "required": required, "gating": gating})
+
+ # ---- Concept nodes ----------------------------------------------------------------------------
+
+ 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())
+
+ 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."""
+ if concept_ref in seen:
+ return _unknown_node(name=name, concept_ref=concept_ref)
+ seen |= {concept_ref}
+ if NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=concept_ref):
+ native_ref = NativeConceptCode.get_validated_native_concept_ref(concept_ref_or_code=concept_ref)
+ return self._native_node(name=name, native_code=_native_code_of(native_ref=native_ref), seen=seen)
+ entry = self._concepts.get(concept_ref)
+ if entry is None:
+ # Not in the crate: no authored fact to read, so the honest answer is the raw escape hatch.
+ return _unknown_node(name=name, concept_ref=concept_ref)
+ if isinstance(entry, str):
+ return _prose_promoted_node(name=name, concept_ref=concept_ref, description=entry, chain=[])
+ return self._blueprint_node(name=name, concept_ref=concept_ref, blueprint=entry, seen=seen)
+
+ def _blueprint_node(self, *, name: str, concept_ref: str, blueprint: ConceptBlueprint, seen: frozenset[str]) -> InputFormField:
+ chain = self._refines_chain(concept_ref=concept_ref)
+ refines = chain or None
+ merged_structure = self._merged_structure(concept_ref=concept_ref, chain=chain)
+ if merged_structure:
+ fields = [self._structure_field(name=field_name, field=field, seen=seen) for field_name, field in merged_structure.items()]
+ return InputFormField(
+ kind=FieldKind.OBJECT,
+ name=name,
+ concept_ref=concept_ref,
+ refines=refines,
+ description=blueprint.description,
+ required=True,
+ fields=fields,
+ )
+ class_name = self._first_class_structure(concept_ref=concept_ref, chain=chain)
+ if class_name is not None:
+ return self._class_backed_node(
+ name=name, concept_ref=concept_ref, class_name=class_name, description=blueprint.description, refines=refines, seen=seen
+ )
+ if chain and NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=chain[-1]):
+ return self._native_node(
+ name=name,
+ native_code=_native_code_of(native_ref=chain[-1]),
+ concept_ref=concept_ref,
+ description=blueprint.description,
+ refines=refines,
+ seen=seen,
+ )
+ return _prose_promoted_node(name=name, concept_ref=concept_ref, description=blueprint.description, chain=chain)
+
+ def _native_node(
+ self,
+ *,
+ name: str,
+ native_code: NativeConceptCode,
+ concept_ref: str | None = None,
+ description: str | None = None,
+ refines: list[str] | None = None,
+ seen: frozenset[str],
+ ) -> InputFormField:
+ """The node of a native concept, or of a concept whose chain bottoms at one (identity-decided, never shape-sniffed)."""
+ pinned = make_pinned_native_blueprint(native_code)
+ kind: FieldKind
+ integer: bool | None = None
+ datetime_flag: bool | None = None
+ text_format: str | None = None
+ fields: list[InputFormField] | None = None
+ match native_code:
+ case NativeConceptCode.TEXT | NativeConceptCode.HTML:
+ kind = FieldKind.PROSE
+ case NativeConceptCode.NUMBER:
+ kind = FieldKind.NUMBER
+ integer = False
+ case NativeConceptCode.YES_NO:
+ kind = FieldKind.BOOLEAN
+ case NativeConceptCode.DATE:
+ kind = FieldKind.DATE
+ datetime_flag = False
+ case NativeConceptCode.TIME:
+ kind = FieldKind.TEXT
+ text_format = "time"
+ case NativeConceptCode.DOCUMENT:
+ kind = FieldKind.DOCUMENT
+ case NativeConceptCode.IMAGE:
+ kind = FieldKind.IMAGE
+ case NativeConceptCode.PAGE | NativeConceptCode.TEXT_AND_IMAGES | NativeConceptCode.SEARCH_RESULT:
+ kind = FieldKind.OBJECT
+ pinned_structure = pinned.structure if isinstance(pinned.structure, dict) else {}
+ fields = [self._structure_field(name=field_name, field=field, seen=seen) for field_name, field in pinned_structure.items()]
+ case NativeConceptCode.DYNAMIC | NativeConceptCode.ANYTHING | NativeConceptCode.JSON | NativeConceptCode.COMPOSITE:
+ kind = FieldKind.UNKNOWN
+ return InputFormField(
+ kind=kind,
+ name=name,
+ concept_ref=concept_ref or native_code.concept_ref,
+ refines=refines,
+ description=description or pinned.description,
+ required=True,
+ integer=integer,
+ datetime_flag=datetime_flag,
+ format=text_format,
+ fields=fields,
+ )
+
+ def _class_backed_node(
+ self,
+ *,
+ name: str,
+ concept_ref: str,
+ class_name: str,
+ description: str | None,
+ refines: list[str] | None,
+ seen: frozenset[str],
+ ) -> InputFormField:
+ """A concept whose payload is stated by a registered class: a native class maps by identity, any other is reflected."""
+ native_code = next((code for code in NativeConceptCode if code.structure_class_name == class_name), None)
+ if native_code is not None:
+ return self._native_node(name=name, native_code=native_code, concept_ref=concept_ref, description=description, refines=refines, seen=seen)
+ structure_class = get_class_registry().get_class(name=class_name)
+ if not (isinstance(structure_class, type) and issubclass(structure_class, BaseModel)):
+ return _unknown_node(name=name, concept_ref=concept_ref, description=description, refines=refines)
+ reflected = reflect_structure_class(structure_class=structure_class)
+ if reflected is None:
+ return _unknown_node(name=name, concept_ref=concept_ref, description=description, refines=refines)
+ fields = [
+ _with_reflected_constraints(
+ node=self._structure_field(name=field_name, field=field, seen=seen), field_info=structure_class.model_fields[field_name]
+ )
+ for field_name, field in reflected.items()
+ ]
+ return InputFormField(
+ kind=FieldKind.OBJECT, name=name, concept_ref=concept_ref, refines=refines, description=description, required=True, fields=fields
+ )
+
+ # ---- Crate walks ------------------------------------------------------------------------------
+
+ def _refines_chain(self, *, concept_ref: str) -> list[str]:
+ """The authored refinement links, immediate parent first, walked to the end (a native link ends it)."""
+ chain: list[str] = []
+ visited = {concept_ref}
+ current = self._concepts.get(concept_ref)
+ while isinstance(current, ConceptBlueprint) and current.refines:
+ link = current.refines
+ if link in visited:
+ break
+ chain.append(link)
+ visited.add(link)
+ if NativeConceptCode.is_native_concept_ref_or_code(concept_ref_or_code=link):
+ break
+ current = self._concepts.get(link)
+ return chain
+
+ def _merged_structure(self, *, concept_ref: str, chain: list[str]) -> dict[str, ConceptStructureBlueprintType]:
+ """The authored structure fields along the chain, base fields first, a refining concept overriding its parents'."""
+ merged: dict[str, ConceptStructureBlueprintType] = {}
+ for ref in [*reversed(chain), concept_ref]:
+ entry = self._concepts.get(ref)
+ if isinstance(entry, ConceptBlueprint) and isinstance(entry.structure, dict):
+ merged.update(entry.structure)
+ return merged
+
+ def _first_class_structure(self, *, concept_ref: str, chain: list[str]) -> str | None:
+ for ref in [concept_ref, *chain]:
+ entry = self._concepts.get(ref)
+ if isinstance(entry, ConceptBlueprint) and isinstance(entry.structure, str):
+ return entry.structure
+ return None
+
+ # ---- 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."""
+ 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(
+ kind=FieldKind.ENUM,
+ name=name,
+ description=field.description,
+ required=field.required,
+ choices=list(field.choices),
+ default_value=field.default_value,
+ )
+ 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)
+ return node.model_copy(update={"description": field.description, "required": field.required})
+ case ConceptStructureBlueprintFieldType.LIST:
+ item = self._list_item(name=name, field=field, seen=seen)
+ return InputFormField(
+ kind=FieldKind.LIST,
+ name=name,
+ concept_ref=item.concept_ref,
+ refines=item.refines,
+ description=field.description,
+ required=field.required,
+ default_value=field.default_value,
+ item=item,
+ )
+ case ConceptStructureBlueprintFieldType.DICT | None:
+ return _unknown_node(name=name, description=field.description, required=field.required, default_value=field.default_value)
+ case (
+ ConceptStructureBlueprintFieldType.TEXT
+ | ConceptStructureBlueprintFieldType.INTEGER
+ | ConceptStructureBlueprintFieldType.NUMBER
+ | ConceptStructureBlueprintFieldType.BOOLEAN
+ | ConceptStructureBlueprintFieldType.DATE
+ | ConceptStructureBlueprintFieldType.DATETIME
+ | ConceptStructureBlueprintFieldType.TIME
+ ):
+ return _scalar_field(
+ field_type=field.type, name=name, description=field.description, required=field.required, default_value=field.default_value
+ )
+
+ 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."""
+ item_type: ConceptStructureBlueprintFieldType | None
+ try:
+ item_type = ConceptStructureBlueprintFieldType(field.item_type) if field.item_type else None
+ except ValueError:
+ item_type = None
+ match item_type:
+ case ConceptStructureBlueprintFieldType.CONCEPT:
+ if field.item_concept_ref is None:
+ return _unknown_node(name=name)
+ return self._concept_node(name=name, concept_ref=field.item_concept_ref, seen=seen)
+ case None | ConceptStructureBlueprintFieldType.LIST | ConceptStructureBlueprintFieldType.DICT:
+ return _unknown_node(name=name)
+ case (
+ ConceptStructureBlueprintFieldType.TEXT
+ | ConceptStructureBlueprintFieldType.INTEGER
+ | ConceptStructureBlueprintFieldType.NUMBER
+ | ConceptStructureBlueprintFieldType.BOOLEAN
+ | ConceptStructureBlueprintFieldType.DATE
+ | ConceptStructureBlueprintFieldType.DATETIME
+ | ConceptStructureBlueprintFieldType.TIME
+ ):
+ return _scalar_field(field_type=item_type, name=name, required=True)
+
+
+def _scalar_field(
+ *,
+ field_type: ConceptStructureBlueprintFieldType,
+ name: str,
+ required: bool,
+ description: str | None = None,
+ default_value: Any | None = None,
+) -> InputFormField:
+ """The node of a scalar blueprint type: its kind and per-kind flags (a compound type maps to `unknown`)."""
+ kind: FieldKind
+ integer: bool | None = None
+ datetime_flag: bool | None = None
+ text_format: str | None = None
+ match field_type:
+ case ConceptStructureBlueprintFieldType.TEXT:
+ kind = FieldKind.TEXT
+ case ConceptStructureBlueprintFieldType.INTEGER:
+ kind = FieldKind.NUMBER
+ integer = True
+ case ConceptStructureBlueprintFieldType.NUMBER:
+ kind = FieldKind.NUMBER
+ integer = False
+ case ConceptStructureBlueprintFieldType.BOOLEAN:
+ kind = FieldKind.BOOLEAN
+ case ConceptStructureBlueprintFieldType.DATE:
+ kind = FieldKind.DATE
+ datetime_flag = False
+ case ConceptStructureBlueprintFieldType.DATETIME:
+ kind = FieldKind.DATE
+ datetime_flag = True
+ case ConceptStructureBlueprintFieldType.TIME:
+ kind = FieldKind.TEXT
+ text_format = "time"
+ case ConceptStructureBlueprintFieldType.LIST | ConceptStructureBlueprintFieldType.DICT | ConceptStructureBlueprintFieldType.CONCEPT:
+ kind = FieldKind.UNKNOWN
+ return InputFormField(
+ kind=kind,
+ name=name,
+ description=description,
+ required=required,
+ default_value=default_value,
+ integer=integer,
+ datetime_flag=datetime_flag,
+ format=text_format,
+ )
+
+
+def _with_reflected_constraints(*, node: InputFormField, field_info: FieldInfo) -> InputFormField:
+ """Stamp the constraints a registered class states on a field (`Field(gt=..., max_length=..., pattern=...)`).
+
+ Only the slots that apply to the node's kind are read: bounds on a `number`, length and pattern
+ on a `text`. Anything else the class may declare is not a form fact and is left out.
+ """
+ constraints: dict[str, Any] = {}
+ match node.kind:
+ case FieldKind.NUMBER:
+ for constraint in field_info.metadata:
+ match constraint:
+ case Gt(gt=bound):
+ constraints["exclusive_minimum"] = bound
+ case Ge(ge=bound):
+ constraints["minimum"] = bound
+ case Lt(lt=bound):
+ constraints["exclusive_maximum"] = bound
+ case Le(le=bound):
+ constraints["maximum"] = bound
+ case _:
+ pass
+ case FieldKind.TEXT:
+ for constraint in field_info.metadata:
+ match constraint:
+ case MinLen(min_length=length):
+ constraints["min_length"] = length
+ case MaxLen(max_length=length):
+ constraints["max_length"] = length
+ case _:
+ # pydantic folds `pattern=` into its own general-metadata object.
+ pattern = getattr(constraint, "pattern", None)
+ if isinstance(pattern, str):
+ constraints["pattern"] = pattern
+ case (
+ FieldKind.PROSE
+ | FieldKind.DATE
+ | FieldKind.BOOLEAN
+ | FieldKind.ENUM
+ | FieldKind.DOCUMENT
+ | FieldKind.IMAGE
+ | FieldKind.OBJECT
+ | FieldKind.LIST
+ | FieldKind.UNKNOWN
+ ):
+ pass
+ return node.model_copy(update=constraints) if constraints else node
+
+
+def _prose_promoted_node(*, name: str, concept_ref: str, description: str, chain: list[str]) -> InputFormField:
+ """A description-only or string-described concept: this engine backs it with a `TextContent` subclass."""
+ return InputFormField(
+ kind=FieldKind.PROSE,
+ name=name,
+ concept_ref=concept_ref,
+ refines=[*chain, NativeConceptCode.TEXT.concept_ref],
+ description=description,
+ required=True,
+ )
+
+
+def _unknown_node(
+ *,
+ name: str,
+ concept_ref: str | None = None,
+ description: str | None = None,
+ refines: list[str] | None = None,
+ required: bool = True,
+ default_value: Any | None = None,
+) -> InputFormField:
+ return InputFormField(
+ kind=FieldKind.UNKNOWN,
+ name=name,
+ concept_ref=concept_ref,
+ refines=refines,
+ description=description,
+ required=required,
+ default_value=default_value,
+ )
+
+
+def _native_code_of(*, native_ref: str) -> NativeConceptCode:
+ return NativeConceptCode(native_ref.rsplit(".", 1)[-1])
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
index d33bc05cb..2efacee3d 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_i
from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
+from pipelex.pipeline.input_form import PipeInputFormDescriptor, build_input_form
from pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pipes
from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.pipe_io_contracts import PipeIOContract, build_pipe_io_contracts
@@ -85,8 +86,9 @@ async def validate_bundles_in_process(
# `validation_library_id` stays None and the cleanup below is a no-op. Artifacts that
# need the open validation library are built INSIDE the window, before the `finally`
# tears it down: `pipe_io_contracts`'s JSON-Schema rendering resolves bundle-defined
- # structure classes through the class registry, and the graph arm dry-runs the main
- # pipe against the loaded library.
+ # structure classes through the class registry, `input_form`'s class-backed reflection
+ # reads the same registry, and the graph arm dry-runs the main pipe against the loaded
+ # library.
prev_library_id = get_current_library_id_or_none()
validation_library_id: str | None = None
# Explicit body-success flag — NOT sys.exc_info() in the finally, which also sees an
@@ -105,6 +107,7 @@ async def validate_bundles_in_process(
# something inside the window later moves the contextvar.
validation_library_id = get_current_library_id_or_none()
pipe_io_contracts: dict[str, PipeIOContract] = build_pipe_io_contracts(result.pipes)
+ input_form: dict[str, PipeInputFormDescriptor] = build_input_form(result.pipes)
# One 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)
@@ -140,6 +143,7 @@ async def validate_bundles_in_process(
return build_validation_report(
blueprints=result.blueprints,
pipe_io_contracts=pipe_io_contracts,
+ input_form=input_form,
liftable_pipes=liftable_pipes,
dry_run_result=result.dry_run_result,
pending_signatures=result.pending_signatures,
diff --git a/pipelex/pipeline/validation_report.py b/pipelex/pipeline/validation_report.py
index ec01d8ccc..1c916a3f7 100644
--- a/pipelex/pipeline/validation_report.py
+++ b/pipelex/pipeline/validation_report.py
@@ -22,6 +22,7 @@ from pipelex.graph.graphspec import GraphSpec
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.bundle_validator import DryRunOutput
+from pipelex.pipeline.input_form import PipeInputFormDescriptor
from pipelex.pipeline.liftable_pipes import LiftablePipeEntry
from pipelex.pipeline.pipe_io_contracts import PipeIOContract
from pipelex.pipeline.validate_bundle import ValidatedPipeEntry, build_validated_pipes
@@ -48,6 +49,13 @@ class PipelexValidationReport(ValidationReport):
pipe_io_contracts: dict[str, PipeIOContract] = Field(default_factory=dict)
"""Per-pipe input/output contracts, keyed by namespaced `pipe_ref` (`domain.code`)."""
+ input_form: dict[str, PipeInputFormDescriptor]
+ """Per-pipe input-form descriptors (the MTHDS input-form descriptor, derived from authored
+ facts — never from `json_schema`), keyed exactly like `pipe_io_contracts`. Required, no
+ default: the shared-assembly rule says a report field is populated on every backend or none,
+ so a backend that forgets it fails loudly instead of shipping an empty view. The HTTP route
+ decides whether the field travels on the wire (absent unless a caller opts in via `views`)."""
+
liftable_pipes: list[LiftablePipeEntry] = Field(default_factory=empty_list_factory_of(LiftablePipeEntry))
"""Pipes that may be skipped (lifted) when an optional slot resolves absent — the
build-time visibility that the implicit-lifting design (D3) commits to."""
@@ -75,6 +83,7 @@ def build_validation_report(
*,
blueprints: Sequence[PipelexBundleBlueprint],
pipe_io_contracts: dict[str, PipeIOContract],
+ input_form: dict[str, PipeInputFormDescriptor],
dry_run_result: dict[str, DryRunOutput],
pending_signatures: list[str],
graph_spec: GraphSpec | None = None,
@@ -90,6 +99,7 @@ def build_validation_report(
Args:
blueprints: The validated batch's blueprints, in declaration order (non-empty).
pipe_io_contracts: Per-pipe contracts from `build_pipe_io_contracts`, keyed by `pipe_ref`.
+ input_form: Per-pipe input-form descriptors from `build_input_form`, keyed by `pipe_ref`.
dry_run_result: The sweep's per-pipe status map (`ValidateBundleResult.dry_run_result`).
pending_signatures: Library-wide unsatisfied signature refs.
graph_spec: Best-effort graph of the declared main pipe, when one was produced.
@@ -102,6 +112,7 @@ def build_validation_report(
return PipelexValidationReport(
bundle_blueprint=select_primary_blueprint(blueprints).blueprint,
pipe_io_contracts=pipe_io_contracts,
+ input_form=input_form,
liftable_pipes=liftable_pipes or [],
graph_spec=graph_spec,
validated_pipes=build_validated_pipes(dry_run_result),
diff --git a/subject_grants.toml b/subject_grants.toml
index 1ae7df851..1c1be17ca 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -4552,6 +4552,10 @@ 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/input_form.py::build_input_form"]
+param = "pipes"
+rationale = "Reads as a verb-object sentence over the loaded pipes, mirroring build_pipe_io_contracts."
+
["pipelex/pipeline/input_normalizer.py::_normalize_list"]
param = "items"
rationale = "Verb-object: normalizes the items; context stays keyword."
diff --git a/tests/data/input_semantics/probe_bundle.mthds b/tests/data/input_semantics/probe_bundle.mthds
new file mode 100644
index 000000000..d1e86af7c
--- /dev/null
+++ b/tests/data/input_semantics/probe_bundle.mthds
@@ -0,0 +1,148 @@
+domain = "input_semantics_probe"
+description = "PROBE_bundle_desc: probe bundle for the input-semantics audit — every authored fact carries a PROBE_ sentinel so its survival is greppable in every capture"
+main_pipe = "probe_single"
+
+[concept]
+StringNote = "PROBE_desc_concept_StringNote: a concept declared as a bare string"
+
+[concept.Trinket]
+description = "PROBE_desc_concept_Trinket: leaf structure for two-level nesting"
+
+[concept.Trinket.structure]
+label = "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf"
+
+[concept.Gadget]
+description = "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget"
+
+[concept.Gadget.structure]
+name = { type = "text", description = "PROBE_desc_field_gadget_name", required = true }
+trinket = { type = "concept", concept_ref = "Trinket", description = "PROBE_desc_field_gadget_trinket: nested concept, level two" }
+
+[concept.Widget]
+description = "PROBE_desc_concept_Widget: the full-matrix structure under audit"
+
+[concept.Widget.structure]
+shorthand_note = "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)"
+title = { type = "text", description = "PROBE_desc_field_title: required text", required = true }
+subtitle = { type = "text", description = "PROBE_desc_field_subtitle: optional text (required omitted)" }
+summary = { type = "text", description = "PROBE_desc_field_summary: optional text (required explicit false)", required = false }
+motto = { type = "text", description = "PROBE_desc_field_motto: text with default", default_value = "PROBE_default_motto" }
+titled_default = { type = "text", description = "PROBE_desc_field_titled_default: required AND default together", required = true, default_value = "PROBE_default_titled" }
+count = { type = "integer", description = "PROBE_desc_field_count: integer with default", default_value = 42 }
+enabled = { type = "boolean", description = "PROBE_desc_field_enabled: boolean with default", default_value = true }
+price = { type = "number", description = "PROBE_desc_field_price: number with default", default_value = 9.99 }
+released_on = { type = "date", description = "PROBE_desc_field_released_on: date with default", default_value = 2026-01-15 }
+launched_at = { type = "datetime", description = "PROBE_desc_field_launched_at: datetime with default", default_value = 2026-01-15T12:30:00 }
+daily_at = { type = "time", description = "PROBE_desc_field_daily_at: time with default", default_value = 12:30:00 }
+tags = { type = "list", item_type = "text", description = "PROBE_desc_field_tags: list of text with default", default_value = [
+ "PROBE_tag_a",
+ "PROBE_tag_b",
+] }
+ratings = { type = "list", item_type = "integer", description = "PROBE_desc_field_ratings: list of integer" }
+matrix = { type = "list", item_type = "list", description = "PROBE_desc_field_matrix: nested list with unspecified inner item" }
+gadgets = { type = "list", item_type = "concept", item_concept_ref = "Gadget", description = "PROBE_desc_field_gadgets: list of concept" }
+attributes = { type = "dict", key_type = "text", value_type = "text", description = "PROBE_desc_field_attributes: dict text to text" }
+scores = { type = "dict", key_type = "text", value_type = "number", description = "PROBE_desc_field_scores: dict text to number with default", default_value = { speed = 5 } }
+milestones = { type = "dict", key_type = "text", value_type = "date", description = "PROBE_desc_field_milestones: dict text to date" }
+main_gadget = { type = "concept", concept_ref = "Gadget", description = "PROBE_desc_field_main_gadget: required concept field", required = true }
+icon = { type = "concept", concept_ref = "native.Image", description = "PROBE_desc_field_icon: native concept field" }
+tone = { choices = [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful",
+], description = "PROBE_desc_field_tone: choices with default", default_value = "PROBE_choice_casual" }
+only_choice = { choices = [
+ "PROBE_choice_single",
+], description = "PROBE_desc_field_only_choice: single-entry choice list" }
+typed_choice = { type = "text", choices = [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b",
+], description = "PROBE_desc_field_typed_choice: type AND choices together" }
+constrained_count = { type = "integer", description = "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys", minimum = 0, maximum = 100, examples = [
+ 1,
+ 2,
+], unit = "PROBE_unit_items" }
+
+[concept.PlainNote]
+description = "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)"
+
+[concept.RefinedDoc]
+description = "PROBE_desc_concept_RefinedDoc: refinement of a native concept"
+refines = "native.Document"
+
+[concept.BaseEntity]
+description = "PROBE_desc_concept_BaseEntity: base of a custom refinement chain"
+
+[concept.BaseEntity.structure]
+ident = { type = "text", description = "PROBE_desc_field_base_ident: inherited field", required = true }
+
+[concept.SpecialEntity]
+description = "PROBE_desc_concept_SpecialEntity: refines a custom concept"
+refines = "BaseEntity"
+
+[concept.ExtraSpecialEntity]
+description = "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain"
+refines = "SpecialEntity"
+
+[concept.ClassBacked]
+description = "PROBE_desc_concept_ClassBacked: structure declared as an existing class name"
+structure = "TextContent"
+
+[pipe.probe_single]
+type = "PipeLLM"
+description = "PROBE_pipe_probe_single: plain structured, qualified, and description-only inputs"
+inputs = { widget = "Widget", gadget_q = "input_semantics_probe.Gadget", note = "PlainNote" }
+output = "Text"
+prompt = """
+Consider the widget:
+@widget
+And the gadget:
+@gadget_q
+And the note:
+@note
+"""
+
+[pipe.probe_native_inputs]
+type = "PipeLLM"
+description = "PROBE_pipe_probe_native_inputs: native concepts as direct inputs"
+inputs = { text_in = "Text", image_in = "Image", document_in = "Document", page_in = "Page", number_in = "Number", date_in = "Date", time_in = "Time", html_in = "Html", yesno_in = "YesNo" }
+output = "Text"
+prompt = """
+@text_in
+@image_in
+@document_in
+@page_in
+@number_in
+@date_in
+@time_in
+@html_in
+@yesno_in
+"""
+
+[pipe.probe_markers]
+type = "PipeLLM"
+description = "PROBE_pipe_probe_markers: optional, list, fixed-count, and force markers"
+inputs = { opt = "Widget?", many = "Widget[]", two = "Gadget[2]", forced = "Text!" }
+output = "Text"
+prompt = """
+@?opt
+Many widgets:
+@many
+Two gadgets:
+@two
+Forced text:
+@forced
+"""
+
+[pipe.probe_refined]
+type = "PipeLLM"
+description = "PROBE_pipe_probe_refined: refinements and class-backed concepts as inputs"
+inputs = { refdoc = "RefinedDoc", special = "SpecialEntity", extra = "ExtraSpecialEntity", classbacked = "ClassBacked", stringnote = "StringNote" }
+output = "Text"
+prompt = """
+@refdoc
+@special
+@extra
+@classbacked
+@stringnote
+"""
diff --git a/tests/data/input_semantics/rejected/default_on_concept_field.mthds_invalid b/tests/data/input_semantics/rejected/default_on_concept_field.mthds_invalid
new file mode 100644
index 000000000..158458a13
--- /dev/null
+++ b/tests/data/input_semantics/rejected/default_on_concept_field.mthds_invalid
@@ -0,0 +1,14 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: a concept-typed field cannot carry a default_value"
+
+[concept.Holder]
+description = "Holder of a concept field with a default"
+
+[concept.Holder.structure]
+part = { type = "concept", concept_ref = "Part", description = "concept field with default", default_value = "nope" }
+
+[concept.Part]
+description = "A part"
+
+[concept.Part.structure]
+name = "A name"
diff --git a/tests/data/input_semantics/rejected/multiple_refines.mthds_invalid b/tests/data/input_semantics/rejected/multiple_refines.mthds_invalid
new file mode 100644
index 000000000..af1fe419e
--- /dev/null
+++ b/tests/data/input_semantics/rejected/multiple_refines.mthds_invalid
@@ -0,0 +1,6 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: refines takes a single ref — a list of refined concepts is refused"
+
+[concept.MultiParent]
+description = "A concept trying to refine two concepts"
+refines = ["native.Text", "native.Document"]
diff --git a/tests/data/input_semantics/rejected/non_string_choices.mthds_invalid b/tests/data/input_semantics/rejected/non_string_choices.mthds_invalid
new file mode 100644
index 000000000..9b9aec1f9
--- /dev/null
+++ b/tests/data/input_semantics/rejected/non_string_choices.mthds_invalid
@@ -0,0 +1,8 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: choices must be strings — numeric choice values are refused"
+
+[concept.Rating]
+description = "A rating with numeric choices"
+
+[concept.Rating.structure]
+stars = { choices = [1, 2, 3], description = "numeric choices" }
diff --git a/tests/data/input_semantics/rejected/per_input_description.mthds_invalid b/tests/data/input_semantics/rejected/per_input_description.mthds_invalid
new file mode 100644
index 000000000..71151eea6
--- /dev/null
+++ b/tests/data/input_semantics/rejected/per_input_description.mthds_invalid
@@ -0,0 +1,11 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: a pipe input slot cannot carry its own description — inputs values are ref strings only"
+
+[pipe.annotated_inputs]
+type = "PipeLLM"
+description = "Pipe trying to describe an input slot"
+inputs = { doc = { concept = "Text", description = "the document to analyse" } }
+output = "Text"
+prompt = """
+@doc
+"""
diff --git a/tests/data/input_semantics/rejected/refines_plus_structure.mthds_invalid b/tests/data/input_semantics/rejected/refines_plus_structure.mthds_invalid
new file mode 100644
index 000000000..e8fff4d98
--- /dev/null
+++ b/tests/data/input_semantics/rejected/refines_plus_structure.mthds_invalid
@@ -0,0 +1,9 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: refines and structure are mutually exclusive on a concept"
+
+[concept.Hybrid]
+description = "A concept trying to refine AND declare structure"
+refines = "native.Text"
+
+[concept.Hybrid.structure]
+extra = "An extra field"
diff --git a/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py b/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py
new file mode 100644
index 000000000..27dceecb6
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py
@@ -0,0 +1,157 @@
+"""Pin the `pipelex-dev trace-input-semantics` capture harness: one artifact per hop of the
+input-schema emission chain, captured inside the validation window.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.trace_input_semantics_cmd import (
+ HOP1_FILE_NAME,
+ HOP2_DIR_NAME,
+ HOP3_DIR_NAME,
+ HOP4_DIR_NAME,
+ HOP5_FILE_NAME,
+ HOP5_INPUT_FORM_FILE_NAME,
+ MANIFEST_FILE_NAME,
+ trace_input_semantics,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+_SMALL_BUNDLE = """
+domain = "trace_tool_test"
+description = "Bundle for trace-input-semantics tests"
+
+[concept.Item]
+description = "SENT_concept_item"
+
+[concept.Item.structure]
+label = { type = "text", description = "SENT_field_label", required = true }
+qty = { type = "integer", description = "SENT_field_qty", default_value = 3 }
+
+[pipe.do_one]
+type = "PipeLLM"
+description = "Make text from item"
+inputs = { item = "Item", items = "Item[]", hint = "Text?" }
+output = "Text"
+prompt = '''
+@item
+@items
+@?hint
+'''
+"""
+
+_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"
+
+
+def _read_json(path: Path) -> Any:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
[email protected](loop_scope="class")
+class TestTraceInputSemantics:
+ async def test_per_hop_captures_on_small_bundle(self, tmp_path: Path, load_empty_library: Callable[[], str]) -> None:
+ """Each hop of the chain lands one artifact, and authored sentinels are found where expected."""
+ load_empty_library()
+ bundle_path = tmp_path / "small_bundle.mthds"
+ bundle_path.write_text(_SMALL_BUNDLE, encoding="utf-8")
+ output_dir = tmp_path / "trace"
+
+ manifest = await trace_input_semantics(bundle_paths=[bundle_path], output_dir=output_dir)
+
+ # Hop 1: the parsed blueprint dump carries the authored field facts.
+ hop1 = _read_json(output_dir / HOP1_FILE_NAME)
+ item_structure = hop1[0]["concept"]["Item"]["structure"]
+ assert item_structure["label"]["description"] == "SENT_field_label"
+ assert item_structure["label"]["required"] is True
+ assert item_structure["qty"]["default_value"] == 3
+
+ # Hop 2: the regenerated structure-class source threads description and default into Field().
+ hop2_relative = manifest["hop2_generated_sources"]["trace_tool_test.Item"]
+ assert hop2_relative is not None
+ source = (output_dir / hop2_relative).read_text(encoding="utf-8")
+ assert 'description="SENT_field_label"' in source
+ assert "default=3" in source
+
+ # Hop 3: the raw pydantic schema for the concept's structure class.
+ hop3 = _read_json(output_dir / manifest["hop3_raw_pydantic_schemas"]["trace_tool_test.Item"])
+ assert hop3["properties"]["label"]["description"] == "SENT_field_label"
+ assert hop3["properties"]["qty"]["default"] == 3
+
+ # Hop 4: the SCHEMA render per pipe input — envelope with concept ref, array wrap on [].
+ hop4_single = _read_json(output_dir / manifest["hop4_schema_renders"]["trace_tool_test.do_one.item"])
+ assert hop4_single["concept"] == "trace_tool_test.Item"
+ assert hop4_single["content"]["properties"]["label"]["description"] == "SENT_field_label"
+ hop4_multi = _read_json(output_dir / manifest["hop4_schema_renders"]["trace_tool_test.do_one.items"])
+ assert hop4_multi["content"]["type"] == "array"
+
+ # Hop 5: the final wire contracts, keyed by namespaced pipe_ref, with presence flags.
+ hop5 = _read_json(output_dir / HOP5_FILE_NAME)
+ do_one = hop5["trace_tool_test.do_one"]
+ assert do_one["inputs"]["item"]["concept_ref"] == "trace_tool_test.Item"
+ assert do_one["inputs"]["hint"]["optional"] is True
+ assert do_one["inputs"]["items"]["json_schema"]["type"] == "array"
+
+ # Hop 5, descriptor side: the same pipes, keyed identically, with the authored facts stated directly.
+ input_form = _read_json(output_dir / HOP5_INPUT_FORM_FILE_NAME)
+ assert set(input_form) == set(hop5)
+ do_one_fields = {field["name"]: field for field in input_form["trace_tool_test.do_one"]["fields"]}
+ assert do_one_fields["items"]["kind"] == "list"
+ assert do_one_fields["items"]["concept_ref"] == "trace_tool_test.Item"
+ assert do_one_fields["hint"]["presence"] == "optional"
+
+ # Manifest: wire framing pairs the authored ref string with the resolved spec.
+ framing_by_input = {f"{entry['pipe_ref']}.{entry['input_name']}": entry for entry in manifest["wire_framing"]}
+ assert framing_by_input["trace_tool_test.do_one.items"]["authored_spec"] == "Item[]"
+ assert framing_by_input["trace_tool_test.do_one.items"]["is_multiple"] is True
+ assert framing_by_input["trace_tool_test.do_one.hint"]["presence"] == "optional"
+ assert (output_dir / MANIFEST_FILE_NAME).is_file()
+
+ async def test_rerun_into_same_output_dir_prunes_stale_hop_artifacts(self, tmp_path: Path, load_empty_library: Callable[[], str]) -> None:
+ """A rerun into an existing output directory replaces the per-item hop captures wholesale —
+ no artifact from a removed or renamed concept, pipe, or input survives on disk.
+ """
+ load_empty_library()
+ bundle_path = tmp_path / "small_bundle.mthds"
+ bundle_path.write_text(_SMALL_BUNDLE, encoding="utf-8")
+ output_dir = tmp_path / "trace"
+ await trace_input_semantics(bundle_paths=[bundle_path], output_dir=output_dir)
+
+ renamed_bundle_path = tmp_path / "renamed_bundle.mthds"
+ renamed_bundle_path.write_text(_SMALL_BUNDLE.replace("Item", "Widget"), encoding="utf-8")
+ manifest = await trace_input_semantics(bundle_paths=[renamed_bundle_path], output_dir=output_dir)
+
+ assert manifest["hop2_generated_sources"]["trace_tool_test.Widget"] is not None
+ hop_dirs_to_manifest_keys = {
+ HOP2_DIR_NAME: "hop2_generated_sources",
+ HOP3_DIR_NAME: "hop3_raw_pydantic_schemas",
+ HOP4_DIR_NAME: "hop4_schema_renders",
+ }
+ for hop_dir_name, manifest_key in hop_dirs_to_manifest_keys.items():
+ on_disk = {str(path.relative_to(output_dir)) for path in (output_dir / hop_dir_name).rglob("*") if path.is_file()}
+ expected = {relative_path for relative_path in manifest[manifest_key].values() if relative_path is not None}
+ assert on_disk == expected, f"stale artifacts under {hop_dir_name}: {sorted(on_disk - expected)}"
+
+ async def test_probe_fixture_validates_and_traces(self, tmp_path: Path, load_empty_library: Callable[[], str]) -> None:
+ """The committed audit probe bundle validates cleanly and every hop capture lands."""
+ load_empty_library()
+ output_dir = tmp_path / "probe_trace"
+
+ manifest = await trace_input_semantics(bundle_paths=[_PROBE_BUNDLE_PATH], output_dir=output_dir)
+
+ assert manifest["hop2_generated_sources"]["input_semantics_probe.Widget"] is not None
+ # A `structure = "ClassName"` declaration generates no class — captured as None.
+ assert manifest["hop2_generated_sources"]["input_semantics_probe.ClassBacked"] is None
+ assert "input_semantics_probe.Widget" in manifest["hop3_raw_pydantic_schemas"]
+ # Native concepts appearing as direct pipe inputs are traced too.
+ assert "native.Image" in manifest["hop3_raw_pydantic_schemas"]
+ assert manifest["hop4_schema_renders"]
+ hop5 = _read_json(output_dir / HOP5_FILE_NAME)
+ assert "input_semantics_probe.probe_markers" in hop5
+ assert "input_semantics_probe.probe_markers" in _read_json(output_dir / HOP5_INPUT_FORM_FILE_NAME)
diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.py
new file mode 100644
index 000000000..ab75a3d49
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_input_form.py
@@ -0,0 +1,514 @@
+"""Pin the D2 `build_input_form` deriver: the per-pipe input-form descriptor from authored facts.
+
+Contract: the workspace spec `docs/specs/mthds-input-form-descriptor.md`. The descriptor is derived
+from the loaded pipes (slot facts: order, presence, multiplicity) plus the authored blueprints
+(concept facts: descriptions, refinement chains, structure fields) — never from the emitted JSON
+Schema, so the facts the schema projection destroys (S1 findings E1-E10) survive here:
+
+- concept identity on every concept-typed node (E1) and the refinement chain as a stated list (E2);
+- three-valued `presence` so `!` is not flattened (E5), and `gating` stated as its own fact;
+- structured multiplicity including fixed `[N]` counts (E4/E9);
+- authored `required` AND `default_value` both reported (E3 — the descriptor reports authored
+ intent, not the generator's silent drop);
+- single-member `choices` normalized to a list, never `const` (E10);
+- concept descriptions on class-backed and native nodes (E6).
+
+The deriver runs against the open validation library (`validate_bundle` leaves it loaded on
+success), mirroring `build_pipe_io_contracts` — same window, same key space.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+import pytest
+from pydantic import Field
+
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.pipeline.input_form import FieldKind, InputFormField, build_input_form
+from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.system.registries.class_registry_access import get_class_registry
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+ from pipelex.pipeline.input_form import PipeInputFormDescriptor
+
+
+def _teardown_validation_library(outer_library_id: str) -> None:
+ """Tear down the library `validate_bundle` left open on success, restoring the outer one."""
+ validation_library_id = get_current_library_id_or_none()
+ if validation_library_id is not None and validation_library_id != outer_library_id:
+ set_current_library(library_id=outer_library_id)
+ get_library_manager().teardown(library_id=validation_library_id)
+ clear_current_library()
+
+
+_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"
+
+
+_LIBRARY_DIR_MTHDS = """
+domain = "input_form_lib"
+description = "Library domain loaded through library_dirs"
+
+[concept.Invoice]
+description = "An invoice"
+
+[concept.Invoice.structure]
+number = { type = "text", description = "Invoice number", required = true }
+total = { type = "number", description = "Total amount" }
+
+[concept]
+Memo = "A short memo"
+"""
+
+_LIBRARY_CONSUMER_MTHDS = """
+domain = "input_form_consumer"
+description = "Bundle whose pipe input is a concept from a library dir"
+
+[concept.SpecialInvoice]
+description = "An invoice flagged for review"
+refines = "input_form_lib.Invoice"
+
+[pipe.process]
+type = "PipeLLM"
+description = "Process an invoice"
+output = "Text"
+prompt = '''
+@invoice
+@memo
+@special
+'''
+
+[pipe.process.inputs]
+invoice = "input_form_lib.Invoice"
+memo = "input_form_lib.Memo"
+special = "SpecialInvoice"
+"""
+
+
+_NO_INPUTS_MTHDS = """
+domain = "input_form_empty"
+description = "Bundle with a pipe declaring no inputs"
+
+[pipe.generate]
+type = "PipeLLM"
+description = "Generate something from nothing"
+output = "Text"
+prompt = "Write a haiku."
+"""
+
+
+def _field_by_name(descriptor: PipeInputFormDescriptor, name: str) -> InputFormField:
+ by_name = {field.name: field for field in descriptor.fields}
+ assert name in by_name, f"Expected a field named {name!r}, got {sorted(by_name)}"
+ return by_name[name]
+
+
+def _assert_no_null_values(dumped: Any, *, path: str = "$") -> None:
+ """No slot on the dumped wire form ever carries JSON null — inapplicable slots are ABSENT."""
+ if isinstance(dumped, dict):
+ for key, value in cast("dict[str, Any]", dumped).items():
+ assert value is not None, f"Slot {path}.{key} dumped as null — inapplicable slots must be absent"
+ _assert_no_null_values(value, path=f"{path}.{key}")
+ elif isinstance(dumped, list):
+ for index, value in enumerate(cast("list[Any]", dumped)):
+ _assert_no_null_values(value, path=f"{path}[{index}]")
+
+
[email protected](loop_scope="class")
+class TestBuildInputForm:
+ async def _derive_probe(self, load_empty_library: Callable[[], str]) -> tuple[dict[str, PipeInputFormDescriptor], set[str]]:
+ outer_library_id = load_empty_library()
+ try:
+ result = await validate_bundle(mthds_contents=[_PROBE_BUNDLE_PATH.read_text(encoding="utf-8")])
+ input_form = build_input_form(result.pipes)
+ contract_keys = set(build_pipe_io_contracts(result.pipes))
+ finally:
+ _teardown_validation_library(outer_library_id)
+ return input_form, contract_keys
+
+ async def test_keyed_like_pipe_io_contracts_in_authored_order(self, load_empty_library: Callable[[], str]) -> None:
+ """Same namespaced `pipe_ref` key set as `pipe_io_contracts`; `fields` follow authored slot order."""
+ input_form, contract_keys = await self._derive_probe(load_empty_library)
+
+ assert set(input_form) == contract_keys
+ single = input_form["input_semantics_probe.probe_single"]
+ assert [field.name for field in single.fields] == ["widget", "gadget_q", "note"]
+ markers = input_form["input_semantics_probe.probe_markers"]
+ assert [field.name for field in markers.fields] == ["opt", "many", "two", "forced"]
+
+ async def test_presence_required_and_gating_markers(self, load_empty_library: Callable[[], str]) -> None:
+ """Presence is three-valued (E5); `required` derives from it; `gating` diverges on variable lists."""
+ input_form, _ = await self._derive_probe(load_empty_library)
+ markers = input_form["input_semantics_probe.probe_markers"]
+
+ opt = _field_by_name(markers, "opt")
+ assert opt.presence == "optional"
+ assert opt.required is False
+ assert opt.gating is False
+
+ many = _field_by_name(markers, "many")
+ assert many.kind == FieldKind.LIST
+ assert many.presence == "plain"
+ assert many.required is True
+ assert many.gating is False, "A variable-multiplicity list never gates: `[]` is its legitimate value"
+ assert many.item_count is None
+ assert many.item is not None
+ assert many.item.concept_ref == "input_semantics_probe.Widget"
+ assert many.concept_ref == "input_semantics_probe.Widget", "A list node names the ELEMENT concept"
+
+ two = _field_by_name(markers, "two")
+ assert two.kind == FieldKind.LIST
+ assert two.item_count == 2, "The fixed `[N]` count is a structured fact (E4)"
+ assert two.required is True
+ assert two.gating is True, "A fixed-count list gates like any other slot"
+
+ forced = _field_by_name(markers, "forced")
+ assert forced.presence == "force"
+ assert forced.required is True
+ assert forced.gating is True
+
+ widget = _field_by_name(input_form["input_semantics_probe.probe_single"], "widget")
+ assert widget.presence == "plain"
+ assert widget.required is True
+ assert widget.gating is True
+
+ async def test_concept_identity_and_refinement_chain(self, load_empty_library: Callable[[], str]) -> None:
+ """Every concept node states its namespaced ref (E1); chains are walked to their end (E2)."""
+ input_form, _ = await self._derive_probe(load_empty_library)
+ refined = input_form["input_semantics_probe.probe_refined"]
+
+ refdoc = _field_by_name(refined, "refdoc")
+ assert refdoc.concept_ref == "input_semantics_probe.RefinedDoc"
+ assert refdoc.kind == FieldKind.DOCUMENT, "Document-ness is a chain fact, never `properties.url` sniffing"
+ assert refdoc.refines == ["native.Document"]
+
+ special = _field_by_name(refined, "special")
+ assert special.refines == ["input_semantics_probe.BaseEntity"]
+ assert special.kind == FieldKind.OBJECT
+
+ extra = _field_by_name(refined, "extra")
+ assert extra.refines == ["input_semantics_probe.SpecialEntity", "input_semantics_probe.BaseEntity"]
+
+ classbacked = _field_by_name(refined, "classbacked")
+ assert classbacked.kind == FieldKind.PROSE, "A class-backed text concept flattens to its scalar kind"
+ assert classbacked.description is not None
+ assert "PROBE_desc_concept_ClassBacked" in classbacked.description, "The concept description survives (E6)"
+
+ stringnote = _field_by_name(refined, "stringnote")
+ assert stringnote.kind == FieldKind.PROSE
+ assert stringnote.concept_ref == "input_semantics_probe.StringNote"
+ assert stringnote.refines == ["native.Text"], "A string-described concept is this engine's TextContent fact"
+
+ note = _field_by_name(input_form["input_semantics_probe.probe_single"], "note")
+ assert note.kind == FieldKind.PROSE
+ assert note.description is not None
+ assert "PROBE_desc_concept_PlainNote" in note.description
+
+ async def test_object_fields_carry_authored_facts(self, load_empty_library: Callable[[], str]) -> None:
+ """Nested fields state the blueprint's facts: E3 both-facts, defaults, choices (E10), nesting (E1)."""
+ input_form, _ = await self._derive_probe(load_empty_library)
+ widget = _field_by_name(input_form["input_semantics_probe.probe_single"], "widget")
+ assert widget.kind == FieldKind.OBJECT
+ assert widget.fields is not None
+ by_name = {field.name: field for field in widget.fields}
+
+ # Declared order is preserved.
+ assert [field.name for field in widget.fields][:4] == ["shorthand_note", "title", "subtitle", "summary"]
+
+ titled_default = by_name["titled_default"]
+ assert titled_default.required is True, "Authored required-ness survives beside a default (E3)"
+ assert titled_default.default_value == "PROBE_default_titled"
+
+ assert by_name["shorthand_note"].required is True, "A shorthand string field implies required text"
+ assert by_name["shorthand_note"].kind == FieldKind.TEXT
+ assert by_name["subtitle"].required is False
+ assert by_name["subtitle"].default_value is None, "The optional-field null is an emission artifact, never a default"
+ assert by_name["motto"].default_value == "PROBE_default_motto"
+
+ count = by_name["count"]
+ assert count.kind == FieldKind.NUMBER
+ assert count.integer is True
+ assert count.default_value == 42
+ price = by_name["price"]
+ assert price.kind == FieldKind.NUMBER
+ assert price.integer is False
+ assert by_name["enabled"].kind == FieldKind.BOOLEAN
+
+ assert by_name["released_on"].kind == FieldKind.DATE
+ assert by_name["released_on"].datetime_flag is False
+ assert by_name["launched_at"].kind == FieldKind.DATE
+ assert by_name["launched_at"].datetime_flag is True
+ daily_at = by_name["daily_at"]
+ assert daily_at.kind == FieldKind.TEXT
+ assert daily_at.format == "time"
+
+ tone = by_name["tone"]
+ assert tone.kind == FieldKind.ENUM
+ assert tone.choices == ["PROBE_choice_formal", "PROBE_choice_casual", "PROBE_choice_playful"]
+ assert tone.default_value == "PROBE_choice_casual"
+ only_choice = by_name["only_choice"]
+ assert only_choice.kind == FieldKind.ENUM
+ assert only_choice.choices == ["PROBE_choice_single"], "A single choice is a one-member list, never `const` (E10)"
+ assert by_name["typed_choice"].kind == FieldKind.ENUM, "`choices` win over `type`, matching the generator"
+
+ tags = by_name["tags"]
+ assert tags.kind == FieldKind.LIST
+ assert tags.item is not None
+ assert tags.item.kind == FieldKind.TEXT
+ assert tags.default_value == ["PROBE_tag_a", "PROBE_tag_b"]
+ matrix = by_name["matrix"]
+ assert matrix.kind == FieldKind.LIST
+ assert matrix.item is not None
+ assert matrix.item.kind == FieldKind.UNKNOWN, "The inner item type of a nested list is inexpressible"
+
+ gadgets = by_name["gadgets"]
+ assert gadgets.kind == FieldKind.LIST
+ assert gadgets.item is not None
+ assert gadgets.item.kind == FieldKind.OBJECT
+ assert gadgets.item.concept_ref == "input_semantics_probe.Gadget", "A nested concept node states its ref (E1)"
+ assert gadgets.item.fields is not None
+ trinket = {field.name: field for field in gadgets.item.fields}["trinket"]
+ assert trinket.concept_ref == "input_semantics_probe.Trinket"
+ assert trinket.kind == FieldKind.OBJECT
+
+ assert by_name["attributes"].kind == FieldKind.UNKNOWN, "A dict field has no form kind — raw escape hatch"
+
+ icon = by_name["icon"]
+ assert icon.kind == FieldKind.IMAGE
+ assert icon.concept_ref == "native.Image"
+
+ constrained_count = by_name["constrained_count"]
+ assert constrained_count.kind == FieldKind.NUMBER
+ assert constrained_count.minimum is None, "Unknown blueprint keys died at parse (E7) — nothing to report"
+
+ async def test_native_direct_inputs_kind_assignment(self, load_empty_library: Callable[[], str]) -> None:
+ """Native concepts as direct inputs map by identity, never by shape sniffing."""
+ input_form, _ = await self._derive_probe(load_empty_library)
+ natives = input_form["input_semantics_probe.probe_native_inputs"]
+
+ assert _field_by_name(natives, "text_in").kind == FieldKind.PROSE
+ assert _field_by_name(natives, "image_in").kind == FieldKind.IMAGE
+ assert _field_by_name(natives, "document_in").kind == FieldKind.DOCUMENT
+ assert _field_by_name(natives, "page_in").kind == FieldKind.OBJECT
+ number_in = _field_by_name(natives, "number_in")
+ assert number_in.kind == FieldKind.NUMBER
+ assert number_in.integer is False
+ date_in = _field_by_name(natives, "date_in")
+ assert date_in.kind == FieldKind.DATE
+ assert date_in.datetime_flag is False
+ time_in = _field_by_name(natives, "time_in")
+ assert time_in.kind == FieldKind.TEXT
+ assert time_in.format == "time"
+ assert _field_by_name(natives, "html_in").kind == FieldKind.PROSE
+ assert _field_by_name(natives, "yesno_in").kind == FieldKind.BOOLEAN
+ for field in natives.fields:
+ assert field.concept_ref is not None
+ assert field.concept_ref.startswith("native."), f"{field.name} states its native ref, got {field.concept_ref!r}"
+
+ async def test_no_inputs_pipe_maps_to_empty_fields(self, load_empty_library: Callable[[], str]) -> None:
+ """A pipe with no inputs maps to an empty `fields` list — a valid form, not an omitted entry."""
+ outer_library_id = load_empty_library()
+ try:
+ result = await validate_bundle(mthds_contents=[_NO_INPUTS_MTHDS])
+ input_form = build_input_form(result.pipes)
+ finally:
+ _teardown_validation_library(outer_library_id)
+
+ assert input_form["input_form_empty.generate"].fields == []
+
+ async def test_library_dir_concepts_derive_like_local_ones(self, tmp_path: Path, load_empty_library: Callable[[], str]) -> None:
+ """Concepts loaded through `library_dirs` are in the library's crate: structured, description-only, and refined alike."""
+ (tmp_path / "input_form_lib.mthds").write_text(_LIBRARY_DIR_MTHDS)
+ outer_library_id = load_empty_library()
+ try:
+ result = await validate_bundle(mthds_contents=[_LIBRARY_CONSUMER_MTHDS], library_dirs=[tmp_path])
+ input_form = build_input_form(result.pipes)
+ finally:
+ _teardown_validation_library(outer_library_id)
+
+ descriptor = input_form["input_form_consumer.process"]
+ invoice = _field_by_name(descriptor, "invoice")
+ assert invoice.kind == FieldKind.OBJECT
+ assert invoice.concept_ref == "input_form_lib.Invoice"
+ assert invoice.description == "An invoice"
+ assert invoice.fields is not None
+ number, total = invoice.fields
+ assert (number.name, number.kind, number.required) == ("number", FieldKind.TEXT, True)
+ assert (total.name, total.kind) == ("total", FieldKind.NUMBER)
+
+ memo = _field_by_name(descriptor, "memo")
+ assert memo.kind == FieldKind.PROSE
+ assert memo.description == "A short memo"
+ assert memo.refines == ["native.Text"]
+
+ special = _field_by_name(descriptor, "special")
+ assert special.kind == FieldKind.OBJECT
+ assert special.refines == ["input_form_lib.Invoice"]
+ assert special.fields is not None
+ assert [field.name for field in special.fields] == ["number", "total"]
+ assert special.description == "An invoice flagged for review"
+
+ 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)
+
+ for pipe_ref, descriptor in input_form.items():
+ dumped = descriptor.model_dump(mode="json")
+ _assert_no_null_values(dumped, path=pipe_ref)
+ for dumped_field in dumped["fields"]:
+ # Nested fields never carry pipe-slot facts.
+ nested_fields: list[dict[str, Any]] = dumped_field.get("fields") or []
+ for nested in nested_fields:
+ assert "presence" not in nested
+ assert "gating" not in nested
+
+
+# ---- Phase 3: the rest of the kind-assignment table ---------------------------------------------
+
+
+class InputFormConstrainedPayload(StructuredContent):
+ """A hand-written structure class a bundle names via `structure = "..."`, with engine-stated constraints."""
+
+ width: int = Field(gt=0, le=4096, description="PROBE_desc_reflected_width")
+ code: str = Field(min_length=2, max_length=8, pattern="^[A-Z]+$", description="PROBE_desc_reflected_code")
+ ratio: float | None = Field(default=None, ge=0.0, lt=1.0, description="PROBE_desc_reflected_ratio")
+
+
+class InputFormUnmappablePayload(StructuredContent):
+ """A structure class whose field has no single blueprint shape — reflection must stay absent, never guess."""
+
+ payload: str | int = Field(description="PROBE_desc_reflected_payload")
+
+
+_KIND_TABLE_MTHDS = """
+domain = "input_form_kinds"
+description = "Bundle pinning the rest of the kind-assignment table"
+
+[concept.Constrained]
+description = "PROBE_desc_concept_Constrained: class-backed by a hand-written constrained class"
+structure = "InputFormConstrainedPayload"
+
+[concept.Unmappable]
+description = "PROBE_desc_concept_Unmappable: class-backed by a class reflection cannot map"
+structure = "InputFormUnmappablePayload"
+
+[concept.Gadget]
+description = "PROBE_desc_concept_Gadget"
+
+[concept.Gadget.structure]
+name = { type = "text", description = "PROBE_desc_field_gadget_name", required = true }
+
+[pipe.remaining_natives]
+type = "PipeCompose"
+description = "The native concepts the probe bundle does not exercise as direct inputs"
+inputs = { tai_in = "TextAndImages", search_result_in = "SearchResult", dynamic_in = "Dynamic", anything_in = "Anything", json_in = "JSON" }
+output = "Text"
+template = "$tai_in $search_result_in $dynamic_in $anything_in $json_in"
+
+[pipe.edges]
+type = "PipeLLM"
+description = "Fixed-count-of-one multiplicity and class-backed reflection"
+inputs = { one = "Gadget[1]", constrained = "Constrained", unmappable = "Unmappable" }
+output = "Text"
+prompt = \"\"\"
+@one
+@constrained
+@unmappable
+\"\"\"
+"""
+
+
[email protected](loop_scope="class")
+class TestKindAssignmentTable:
+ async def _derive_kind_table(self, load_empty_library: Callable[[], str]) -> dict[str, PipeInputFormDescriptor]:
+ outer_library_id = load_empty_library()
+ try:
+ registry = get_class_registry()
+ registry.register_class(InputFormConstrainedPayload)
+ registry.register_class(InputFormUnmappablePayload)
+ result = await validate_bundle(mthds_contents=[_KIND_TABLE_MTHDS])
+ return build_input_form(result.pipes)
+ finally:
+ _teardown_validation_library(outer_library_id)
+
+ async def test_remaining_natives_complete_the_table(self, load_empty_library: Callable[[], str]) -> None:
+ """With the probe bundle's natives, every `NativeConceptCode` a pipe can take as input has a pinned kind."""
+ input_form = await self._derive_kind_table(load_empty_library)
+ natives = input_form["input_form_kinds.remaining_natives"]
+
+ text_and_images = _field_by_name(natives, "tai_in")
+ assert text_and_images.kind == FieldKind.OBJECT
+ assert text_and_images.fields is not None
+ assert [field.name for field in text_and_images.fields][:2] == ["text", "images"], "Pinned-blueprint fields, in pinned order"
+ search_result = _field_by_name(natives, "search_result_in")
+ assert search_result.kind == FieldKind.OBJECT
+ assert search_result.fields is not None
+ assert _field_by_name(natives, "dynamic_in").kind == FieldKind.UNKNOWN
+ assert _field_by_name(natives, "anything_in").kind == FieldKind.UNKNOWN
+ assert _field_by_name(natives, "json_in").kind == FieldKind.UNKNOWN
+ for field in natives.fields:
+ assert field.concept_ref is not None
+ assert field.concept_ref.startswith("native.")
+ assert field.description, f"{field.name} carries its pinned native description"
+
+ async def test_fixed_count_of_one_is_a_single_node(self, load_empty_library: Callable[[], str]) -> None:
+ """`Concept[1]` is not multiple to the runtime (`is_multiple()` is `count > 1`), so the form asks for one value."""
+ input_form = await self._derive_kind_table(load_empty_library)
+ one = _field_by_name(input_form["input_form_kinds.edges"], "one")
+
+ assert one.kind == FieldKind.OBJECT
+ assert one.concept_ref == "input_form_kinds.Gadget"
+ assert one.item is None
+ assert one.item_count is None
+ assert one.required is True
+ assert one.gating is True
+
+ async def test_custom_class_reflects_to_object_with_constraints(self, load_empty_library: Callable[[], str]) -> None:
+ """A hand-written structure class is reflected field by field, with the constraints the engine states."""
+ input_form = await self._derive_kind_table(load_empty_library)
+ constrained = _field_by_name(input_form["input_form_kinds.edges"], "constrained")
+
+ assert constrained.kind == FieldKind.OBJECT
+ assert constrained.concept_ref == "input_form_kinds.Constrained"
+ assert constrained.description is not None
+ assert "PROBE_desc_concept_Constrained" in constrained.description, "The concept description survives (E6)"
+ assert constrained.fields is not None
+ by_name = {field.name: field for field in constrained.fields}
+
+ width = by_name["width"]
+ assert width.kind == FieldKind.NUMBER
+ assert width.integer is True
+ assert width.required is True
+ assert width.exclusive_minimum == 0
+ assert width.maximum == 4096
+ assert width.minimum is None
+ assert width.description == "PROBE_desc_reflected_width"
+
+ code = by_name["code"]
+ assert code.kind == FieldKind.TEXT
+ assert code.min_length == 2
+ assert code.max_length == 8
+ assert code.pattern == "^[A-Z]+$"
+
+ ratio = by_name["ratio"]
+ assert ratio.kind == FieldKind.NUMBER
+ assert ratio.integer is False
+ assert ratio.required is False
+ assert ratio.minimum == 0.0
+ assert ratio.exclusive_maximum == 1.0
+
+ async def test_unmappable_class_falls_back_to_unknown(self, load_empty_library: Callable[[], str]) -> None:
+ """Reflection is faithful-or-absent: a class with an unmappable field yields `unknown`, with identity kept."""
+ input_form = await self._derive_kind_table(load_empty_library)
+ unmappable = _field_by_name(input_form["input_form_kinds.edges"], "unmappable")
+
+ assert unmappable.kind == FieldKind.UNKNOWN
+ assert unmappable.concept_ref == "input_form_kinds.Unmappable"
+ assert unmappable.description is not None
+ assert "PROBE_desc_concept_Unmappable" in unmappable.description
+ assert unmappable.fields is None
diff --git a/tests/integration/pipelex/pipeline/test_protocol_validate.py b/tests/integration/pipelex/pipeline/test_protocol_validate.py
index aa32b7de8..fb3e7f642 100644
--- a/tests/integration/pipelex/pipeline/test_protocol_validate.py
+++ b/tests/integration/pipelex/pipeline/test_protocol_validate.py
@@ -102,6 +102,11 @@ class TestProtocolValidate:
assert report.bundle_blueprint.domain == "protocol_validate"
# `pipe_io_contracts` and `validated_pipes` are keyed/identified by namespaced pipe_ref.
assert report.pipe_io_contracts["protocol_validate.summarize"].output.concept_ref == "protocol_validate.Summary"
+ # `input_form` is assembled in the same library window and shares the contracts' key set.
+ assert set(report.input_form) == set(report.pipe_io_contracts)
+ assert [field.name for field in report.input_form["protocol_validate.summarize"].fields] == list(
+ report.pipe_io_contracts["protocol_validate.summarize"].inputs
+ )
assert {(entry["pipe_ref"], entry["status"]) for entry in report.validated_pipes} == {
("protocol_validate.summarize", DryRunStatus.SUCCESS)
}
diff --git a/tests/unit/pipelex/pipeline/test_input_form_deriver.py b/tests/unit/pipelex/pipeline/test_input_form_deriver.py
new file mode 100644
index 000000000..0207bdc97
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_input_form_deriver.py
@@ -0,0 +1,67 @@
+"""Unit-pin the deriver's escape hatches that the library loader keeps out of reach.
+
+The loader rejects concept cycles (`LibraryLoadingError`) and a `structure = "ClassName"` naming an
+unregistered class before a bundle ever reaches `build_input_form`, so those branches are exercised
+directly on a hand-built qualified crate: the derivation must stay total and finite on any crate.
+"""
+
+from __future__ import annotations
+
+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
+
+
+def _concept_field(*, concept_ref: str) -> ConceptStructureBlueprint:
+ return ConceptStructureBlueprint(description="link", type=ConceptStructureBlueprintFieldType.CONCEPT, concept_ref=concept_ref)
+
+
+class TestInputFormDeriverEscapeHatches:
+ def test_cycle_guard_emits_unknown_on_revisit(self) -> None:
+ """A concept path that revisits a ref stops at an `unknown` node carrying the ref — finite, never recursive."""
+ concepts: dict[str, ConceptBlueprint | str] = {
+ "demo.Node": ConceptBlueprint(
+ description="A node",
+ structure={"label": "The label", "child": _concept_field(concept_ref="demo.Node")},
+ ),
+ }
+ node = InputFormDeriver(concepts=concepts).derive_concept(name="root", concept_ref="demo.Node")
+
+ assert node.kind == FieldKind.OBJECT
+ assert node.fields is not None
+ child = node.fields[1]
+ assert child.name == "child"
+ assert child.kind == FieldKind.UNKNOWN
+ assert child.concept_ref == "demo.Node"
+
+ def test_indirect_cycle_is_cut_at_the_revisit(self) -> None:
+ concepts: dict[str, ConceptBlueprint | str] = {
+ "demo.Left": ConceptBlueprint(description="Left", structure={"right": _concept_field(concept_ref="demo.Right")}),
+ "demo.Right": ConceptBlueprint(description="Right", structure={"left": _concept_field(concept_ref="demo.Left")}),
+ }
+ left = InputFormDeriver(concepts=concepts).derive_concept(name="left", concept_ref="demo.Left")
+
+ assert left.fields is not None
+ right = left.fields[0]
+ assert right.kind == FieldKind.OBJECT
+ assert right.fields is not None
+ assert right.fields[0].kind == FieldKind.UNKNOWN
+ assert right.fields[0].concept_ref == "demo.Left"
+
+ def test_unregistered_class_backed_concept_is_unknown(self) -> None:
+ """With no class to reflect, the node keeps its identity and description and reports `unknown`."""
+ concepts: dict[str, ConceptBlueprint | str] = {
+ "demo.Ghost": ConceptBlueprint(description="Backed by a class nobody registered", structure="NoSuchRegisteredClass"),
+ }
+ ghost = InputFormDeriver(concepts=concepts).derive_concept(name="ghost", concept_ref="demo.Ghost")
+
+ assert ghost.kind == FieldKind.UNKNOWN
+ assert ghost.concept_ref == "demo.Ghost"
+ assert ghost.description == "Backed by a class nobody registered"
+
+ def test_concept_absent_from_the_crate_is_unknown_without_a_class(self) -> None:
+ """A slot typed with a concept the crate never saw (a `library_dirs` load) still gets a descriptor."""
+ missing = InputFormDeriver(concepts={}).derive_concept(name="missing", concept_ref="elsewhere.Missing")
+
+ assert missing.kind == FieldKind.UNKNOWN
+ assert missing.concept_ref == "elsewhere.Missing"
diff --git a/tests/unit/pipelex/pipeline/test_input_form_models.py b/tests/unit/pipelex/pipeline/test_input_form_models.py
new file mode 100644
index 000000000..92a64d993
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_input_form_models.py
@@ -0,0 +1,117 @@
+"""Unit-pin the input-form wire models: per-kind slot validators and null-free serialization.
+
+The report's valid arm is dumped WITHOUT `exclude_none` on the HTTP surface, so the field model
+owns its own wire shape: inapplicable slots are dropped at serialization (never emitted as JSON
+null), applicable falsy values (`required: false`, `gating: false`, `integer: false`,
+`item_count` on a fixed list) are kept, and the `datetime` wire slot serializes under its spec
+name regardless of the Python attribute that carries it.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.pipeline.input_form import FieldKind, InputFormField, PipeInputFormDescriptor
+
+
+def _prose_field(name: str = "brief") -> InputFormField:
+ return InputFormField(kind=FieldKind.PROSE, name=name, concept_ref="demo.Brief", required=True, presence=PresenceMarker.PLAIN, gating=True)
+
+
+class TestInputFormFieldValidators:
+ def test_enum_requires_choices(self) -> None:
+ with pytest.raises(ValidationError):
+ InputFormField(kind=FieldKind.ENUM, name="tone", required=False)
+
+ def test_object_requires_fields(self) -> None:
+ with pytest.raises(ValidationError):
+ InputFormField(kind=FieldKind.OBJECT, name="widget", required=True)
+
+ def test_list_requires_item(self) -> None:
+ with pytest.raises(ValidationError):
+ InputFormField(kind=FieldKind.LIST, name="notes", required=True)
+
+ def test_number_requires_integer_flag(self) -> None:
+ with pytest.raises(ValidationError):
+ InputFormField(kind=FieldKind.NUMBER, name="count", required=True)
+
+ def test_date_requires_datetime_flag(self) -> None:
+ with pytest.raises(ValidationError):
+ InputFormField(kind=FieldKind.DATE, name="released_on", required=True)
+
+ def test_scalar_kinds_accept_minimal_slots(self) -> None:
+ field = InputFormField(kind=FieldKind.TEXT, name="title", required=True)
+ assert field.kind == FieldKind.TEXT
+
+
+class TestInputFormSerialization:
+ def test_inapplicable_slots_are_absent_not_null(self) -> None:
+ dumped = _prose_field().model_dump(mode="json")
+ assert dumped["kind"] == "prose"
+ assert dumped["name"] == "brief"
+ assert dumped["concept_ref"] == "demo.Brief"
+ assert dumped["required"] is True
+ assert dumped["presence"] == "plain"
+ assert dumped["gating"] is True
+ for absent in ("title", "refines", "description", "default_value", "examples", "hints", "fields", "item", "item_count", "choices"):
+ assert absent not in dumped, f"Inapplicable slot {absent!r} must be absent, not null"
+ assert None not in dumped.values()
+
+ def test_applicable_falsy_values_are_kept(self) -> None:
+ field = InputFormField(
+ kind=FieldKind.NUMBER,
+ name="count",
+ concept_ref="demo.Count",
+ required=False,
+ presence=PresenceMarker.OPTIONAL,
+ gating=False,
+ integer=False,
+ exclusive_minimum=0,
+ )
+ dumped = field.model_dump(mode="json")
+ assert dumped["required"] is False
+ assert dumped["gating"] is False
+ assert dumped["integer"] is False
+ assert dumped["exclusive_minimum"] == 0
+
+ def test_datetime_slot_serializes_under_its_wire_name(self) -> None:
+ field = InputFormField(kind=FieldKind.DATE, name="released_on", required=True, datetime_flag=False)
+ dumped = field.model_dump(mode="json")
+ assert dumped["datetime"] is False
+ assert "datetime_flag" not in dumped
+
+ def test_single_member_choices_stay_a_list(self) -> None:
+ field = InputFormField(kind=FieldKind.ENUM, name="only", required=False, choices=["single"])
+ assert field.model_dump(mode="json")["choices"] == ["single"]
+
+ def test_descriptor_dump_recurses_the_serializer(self) -> None:
+ descriptor = PipeInputFormDescriptor(
+ fields=[
+ InputFormField(
+ kind=FieldKind.LIST,
+ name="gadgets",
+ concept_ref="demo.Gadget",
+ required=True,
+ presence=PresenceMarker.PLAIN,
+ gating=True,
+ item_count=2,
+ item=InputFormField(
+ kind=FieldKind.OBJECT,
+ name="gadgets",
+ concept_ref="demo.Gadget",
+ required=True,
+ fields=[InputFormField(kind=FieldKind.TEXT, name="label", required=True)],
+ ),
+ )
+ ]
+ )
+ dumped = descriptor.model_dump(mode="json")
+ list_node = dumped["fields"][0]
+ assert list_node["item_count"] == 2
+ item_node = list_node["item"]
+ assert "presence" not in item_node, "Nested fields never carry pipe-slot facts"
+ assert "gating" not in item_node
+ nested = item_node["fields"][0]
+ assert nested == {"kind": "text", "name": "label", "required": True}
diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
index 349f82d79..3050adfb7 100644
--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
@@ -60,6 +60,7 @@ class TestRunnerValidatePlumbing:
# without a real loaded library. Their output shaping is pinned in test_validation_report.py
# and the integration test_protocol_validate.py — this module asserts only the plumbing.
mocker.patch("pipelex.pipeline.validate_in_process.build_pipe_io_contracts", return_value={})
+ mocker.patch("pipelex.pipeline.validate_in_process.build_input_form", return_value={})
mocker.patch("pipelex.pipeline.validate_in_process.select_primary_blueprint")
mocker.patch("pipelex.pipeline.validate_in_process.best_effort_graph_spec", new=mocker.AsyncMock(return_value=None))
mocker.patch("pipelex.pipeline.validate_in_process.build_validation_report")
diff --git a/tests/unit/pipelex/pipeline/test_validation_report.py b/tests/unit/pipelex/pipeline/test_validation_report.py
index ce8437800..eff839334 100644
--- a/tests/unit/pipelex/pipeline/test_validation_report.py
+++ b/tests/unit/pipelex/pipeline/test_validation_report.py
@@ -57,6 +57,7 @@ class TestBuildValidationReport:
report = build_validation_report(
blueprints=blueprints,
pipe_io_contracts=pipe_io_contracts,
+ input_form={},
dry_run_result=dry_run_result,
pending_signatures=["beta.still_pending"],
)
@@ -77,6 +78,7 @@ class TestBuildValidationReport:
report = build_validation_report(
blueprints=blueprints,
pipe_io_contracts={},
+ input_form={},
dry_run_result={},
pending_signatures=[],
)
@@ -102,6 +104,7 @@ class TestBuildValidationReport:
report = build_validation_report(
blueprints=blueprints,
pipe_io_contracts={},
+ input_form={},
dry_run_result={},
pending_signatures=[],
warnings=[warning_item],
diff --git a/wip/input-semantics/audit.md b/wip/input-semantics/audit.md
new file mode 100644
index 000000000..e7719350c
--- /dev/null
+++ b/wip/input-semantics/audit.md
@@ -0,0 +1,52 @@
+# S1 — The input-semantics audit: brief
+
+**Status:** brief written 2026-08-21 by the workspace strategy session, for the `pipelex` session working in this worktree. This is a brief for an audit — the deliverable is a written gap list, not code. Read this, read the two workspace docs below, then conduct the audit and write its findings beside this file. The milestone is **S1** of the input-form roadmap.
+
+**Read first, in order:**
+
+1. `../wip/devx/input-form-projection.md` — the adopted direction. The layer this audit serves is Layer 2: *enrich the semantic layer first, before any UI vocabulary*. The diagnosis that motivates it: information that existed in the method was destroyed by projecting through Pydantic JSON Schema, and every UI downstream is guessing it back.
+2. `../wip/devx/input-form-roadmap.md` — the schedule. S1 starts now, in parallel with work in other repos. Two things wait on your output, which is why this audit should be days, not weeks: **S2** (closing the engine-side gaps, here) takes your engine-side list as its worklist, and **D1** (the descriptor spec, workspace-side) freezes its slots for constraints, defaults, and examples against your list — the spec *drafts* without you, but it will not freeze until you've said what the language and engine actually know.
+
+(Paths are relative to this worktree's root — the workspace root is one level up, same as from any sub-repo.)
+
+## The question
+
+For each piece of knowledge a method author writes — or would obviously want to write — about an input: **does it reach the `json_schema` emitted on `pipe_io_contracts`, and if not, where does it die?**
+
+The chain to trace runs end to end in this repo: `.mthds` structure syntax → `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`) → the generated structure class (`pipelex/core/concepts/structure_generation/generator.py` threads `description` and `default_value` into the emitted `Field(...)`) → Pydantic's `model_json_schema()` → `build_pipe_io_contracts` (`pipelex/pipeline/pipe_io_contracts.py`) → the wire as `PipeInputContract { concept_ref, optional, json_schema }`.
+
+Measure, don't read: the honest way to run this audit is a probe bundle that exercises every expressible construct — every field type, choices, defaults, required and optional, `?` and `[]` markers, concept and native refinements, nesting, lists — run through validate, then a diff of what was authored against what the emitted schema says. Reading the code tells you where to look; only the emitted schema tells you what survived.
+
+## The classification rule — the load-bearing part
+
+Every gap you find gets one of two marks, and the two lists are the deliverable:
+
+- **Engine-side:** the language can say it, and the emission drops or mangles it. Example candidates to verify, not conclusions: does a field's required `description` survive to the schema property? Does the *concept's* own description become the schema's top-level `description`? Does `default_value` appear as the schema's `default`? Do the `date` / `datetime` / `time` field types emit their `format`? Does `choices` arrive as `enum`?
+- **Language-side:** MTHDS cannot express it at all today. The blueprint shows the ceiling: `description`, a type, `choices`, `default_value`, `required` — and nothing else. No numeric ranges, no string lengths or patterns, no examples, no units, no per-input-slot description on a pipe (the `inputs = { … }` declaration names a concept and multiplicity, nothing more). Confirm and complete that list from the parsing layer, not from this paragraph.
+
+The distinction is what keeps the workspace honest downstream: the engine-side list is closable here with zero client changes (S2), while the language-side list feeds the MTHDS design session (Track H) so that **missing semantics get semantic homes and are never smuggled in as UI hints**. When in doubt about a fact's side, the test is: could a `.mthds` author write it today, in any syntax the parser accepts?
+
+## What each entry should carry
+
+For every fact, three things — evidence at `path/file.py:line` where the claim is about code:
+
+- **Where it is authored** (or the demonstration that it cannot be).
+- **Where it is lost**, if it is — the exact hop in the chain above.
+- **Who guesses because of it, today.** The direction doc's evidence from `pipelex-app` is your downstream column: native concepts hardcoded as ref sets because the schema carries no concept identity beyond the top-level `concept_ref`; "is this a document" answered by object-shape sniffing on one surface and description-substring matching on another; prose-vs-label decided by nesting depth. A gap nobody downstream works around is still a gap, but the worked-around ones rank first.
+
+Two wrinkles to place rather than force into the two-sided scheme:
+
+- **Engine-authored semantics on native content classes.** The descriptions on `TextContent`, `DocumentContent` and friends are written in this repo, not by method authors — and at least one is load-bearing far away: the app's upload dropzone keys on the "pipelex storage url" / "document url" wording of `DocumentContent.url`'s description. Catalogue these; changing any of them is S2 work with a blast radius, and the audit should say which ones are contracts-in-disguise.
+- **What a fact *means*, not just whether it travels.** `default_value` today is a structure-level default — the audit should say whether that semantic is "prefill the form with this" or something else, because the descriptor spec (D1) must not adopt a slot whose meaning it guessed. Same question for `required` versus the `?` optional marker, which live at different levels and both reach the wire by different routes.
+
+## Out of scope
+
+- **Fixing anything.** Even a one-line fix — an obviously droppable gap goes on the engine-side list with its evidence, and S2 closes it. The audit stays an audit so it ships fast.
+- **Designing the descriptor or the hints.** D1 and H1 own those; your output is an input to both, written in facts, not proposals. Resist the pull — a sentence of recommendation per entry is fine, a design section is scope creep.
+- **Wire changes of any kind.**
+
+## The gate — S1 is done when
+
+- The gap list is written beside this file, every entry marked engine-side or language-side, with evidence.
+- The engine-side list is phrased so S2 can be scoped directly from it, and the language-side list so the MTHDS session can read it without this repo's context.
+- The workspace roadmap's checkpoint protocol is honored: update `../wip/devx/input-form-roadmap.md` when the milestone closes — the D1 freeze is waiting on the news.
diff --git a/wip/input-semantics/deferred-descriptor-reflection-and-roundtrip.md b/wip/input-semantics/deferred-descriptor-reflection-and-roundtrip.md
new file mode 100644
index 000000000..f5a4532f8
--- /dev/null
+++ b/wip/input-semantics/deferred-descriptor-reflection-and-roundtrip.md
@@ -0,0 +1,11 @@
+# Deferred: two input-form descriptor gaps surfaced by the D2 pre-landing review
+
+Neither is a live bug on the surfaces that exist today; both need a decision before code, so they are recorded here rather than fixed in D2 (`feature/Input-semantics-D2`).
+
+## Reflected classes never read a field's default
+
+`pipelex/codegen/native_expansion.py` derives `required` for a reflected class field from an `X | None` annotation only and never reads `field_info.default`, so a class field such as `count: int = Field(default=0)` lands in the descriptor as `required: true` with no `default_value` (the blueprint-side fields do carry `default_value`). The mechanical fix is small — `field_info.is_required()` for the flag and `field_info.default` unless it is `PydanticUndefined`, stamped in `_with_reflected_constraints` in `pipelex/pipeline/input_form.py` — but it changes what "required" means for reflected classes relative to the schema chain (the S2 finding E3), and the spec says defaults are authored facts. Decide whether a pydantic default counts as an authored fact first; then it is a one-function change plus a row in `TestKindAssignmentTable`.
+
+## The wire descriptor does not round-trip through its own model
+
+`InputFormField` serializes `datetime_flag` under the spec's `datetime` wire name but declares no validation alias, so `InputFormField.model_validate(field.model_dump(mode="json"))` fails on every `date` node, and the FastAPI `response_model` documents the attribute name rather than the wire name. No consumer re-validates the descriptor with the Python model today (neither `pipelex-api`, `pipelex-server`, `mthds-python` nor `pipelex-sdk-python` reference it yet), so this bites only when the Python SDK grows descriptor models — that is D4's concern, where the right move is a `validation_alias` / `populate_by_name` pair or a renamed attribute, chosen together with the SDK types.
diff --git a/wip/input-semantics/deferred-serial-make-test-flake.md b/wip/input-semantics/deferred-serial-make-test-flake.md
new file mode 100644
index 000000000..adfc6ac34
--- /dev/null
+++ b/wip/input-semantics/deferred-serial-make-test-flake.md
@@ -0,0 +1,5 @@
+# Deferred: order-dependent failure under serial `make test`
+
+Seen while closing D2 (`feature/Input-semantics-D2`): the serial `make test` run failed exactly one test, `tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py::TestDirectExecutorWorkdir::test_transported_run_generates_concept_structures`, with `Function 'greet_it' not found in registry`. The same test passes in isolation and under the parallel `make agent-test`, and D2 touches nothing under `pipe_func`. So an earlier test in the serial ordering leaves the func registry in a state this test does not expect — a test-isolation leak on the base branch, not a D2 regression.
+
+Not fixed here: it is outside the D2 diff and the right fix (which fixture resets the func registry, and which earlier test pollutes it) needs its own bisect. Reproduce with the serial `make test` ordering and bisect with `pytest -p no:randomly tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py <suspect earlier module>`.
diff --git a/wip/input-semantics/findings.md b/wip/input-semantics/findings.md
new file mode 100644
index 000000000..ce4ebafe2
--- /dev/null
+++ b/wip/input-semantics/findings.md
@@ -0,0 +1,163 @@
+# S1 — Input-semantics audit: findings
+
+**Status:** written 2026-08-21, closing milestone S1 of the input-form roadmap. Evidence base: the measured survival table ([`survival-table.md`](survival-table.md), captures under [`probe/`](probe/), regenerable with `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`), a read-only sweep of `pipelex-app`'s two input-form stacks, and a trace of where `default_value` is actually consumed at runtime. Per the brief: facts only — at most one sentence of recommendation per entry, no design.
+
+The hop numbering used throughout: **hop 1** parse (TOML → blueprint), **hop 2** generate (blueprint → structure-class source), **hop 3** pydantic (`model_json_schema()`), **hop 4** render (SCHEMA representation), **hop 5** contract (`PipeInputContract`). Measured once and worth repeating: **hop 3 → hop 5 is lossless** (byte-identical for a single input; the render only adds the envelope and the array wrap), so every loss below sits in the language, the parse, or the generator — never in the render or contract plumbing.
+
+---
+
+## A. Engine-side gaps — the S2 worklist
+
+The language can say it; the emission drops or mangles it. Each entry is phrased as a closable work item.
+
+### E1. Concept identity of a field is not recoverable from the schema
+
+- **Authored:** `type = "concept"`, `concept_ref = "domain.Gadget"` (or `item_concept_ref` on lists) on a structure field — `pipelex/core/concepts/concept_structure_blueprint.py:59-60`.
+- **Lost:** hop 2/3 — the generator emits a forward ref to the mangled class name, so the schema inlines the shape under `$defs` keyed by the class-name spelling (`input_semantics_probe__Gadget`); native fields appear as bare content-class names (`ImageContent`). Nothing in the schema states the concept ref.
+- **Who guesses:** the app's primary field dispatch is seven hardcoded native-ref sets (`pipelex-app/src/lib/run-form/field-model.ts:133-139`), with a second *drifted* copy (`src/lib/input-format.ts:27-30` — missing `native.Date`/`native.HTML`, so the two stacks disagree on text wrapping) and a third for the wire wrapper (`src/lib/run-form/run-values.ts:35-48`). The app also deliberately discards `schema.title` because it is "the pydantic model name … and would mask the stuff name" (`field-model.ts:210-215`).
+- **Recommendation:** carry the concept ref for every concept-typed node (top-level and nested) on the descriptor or schema.
+
+### E2. The refinement chain leaves no trace
+
+- **Authored:** `refines = "native.Document"` (or a custom chain) — `pipelex/core/concepts/concept_blueprint.py:20`.
+- **Lost:** between hop 2 and hop 3 — the generated class *inherits* from the refined class, so only inherited field shapes survive; the link itself is gone. Measured on `RefinedDoc` and the `BaseEntity ← SpecialEntity ← ExtraSpecialEntity` chain.
+- **Who guesses:** "does this refine Document" is answered by object-shape sniffing on one surface — `isDocumentObject` is `Boolean(schema.properties?.url)` "and nothing more" (`pipelex-app/src/lib/run-form/field-model.ts:186-197`) — and by description-substring matching on the other (`src/components/method/document-url-widget.tsx:130-136`, matching lowercased `"pipelex storage url"` / `"document url"`). A value-side twin hardcodes `DocumentContent`'s field names as a sniff set (`src/lib/input-format.ts:176-182`).
+- **Measured drift, worth flagging in S2's blast radius:** the current `DocumentContent.url` description is "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL" (`pipelex/core/stuffs/document_content.py:16`) — the `"pipelex storage url"` branch of the app's matcher **already matches nothing** (the app's own test fixture pins the older wording); only `"document url"` still fires. `ImageContent.url` ("The image URL: …", `image_content.py:20`) matches neither substring, so image URL fields never get the RJSF dropzone by this route.
+- **Recommendation:** expose the refinement chain (at least "refines `native.X`") as a fact on the wire. The half-dead matcher is filed app-side as `../wip/inbox/2026-08-21-pipelex-app-document-dropzone-matcher-half-dead.md`.
+
+### E3. `required = true` plus `default_value` silently drops the required-ness
+
+- **Authored:** both keys on one field — legal, validated green (probe field `titled_default`).
+- **Lost:** hop 2 — the generator's parameter ordering emits `default=…` and never the `...` sentinel when a default is present (`pipelex/core/concepts/structure_generation/generator.py:307-313`), so the field leaves pydantic's `required` list.
+- **Who guesses:** nobody compensates; the authored intent is just gone. (At runtime the two are genuinely conflicting instructions — see the meaning note in §C — but today the conflict is resolved silently instead of being rejected or honored.)
+- **Recommendation:** decide the combination's meaning (likely: reject it at validation) rather than resolving it by accident of parameter ordering.
+
+### E4. `[N]` fixed multiplicity dies at the render
+
+- **Authored:** `inputs = { gadgets = "Gadget[2]" }` — parsed to `multiplicity: 2` (`pipelex/core/pipes/variable_multiplicity.py:169-171`).
+- **Lost:** hop 4 — `StuffSpec.is_multiple()` collapses multiplicity to a bool before rendering (`pipelex/core/pipes/stuff_spec/stuff_spec.py:58`), so the schema is a plain `array` with no `minItems`/`maxItems`; the contract memo key `(concept_ref, is_multiple())` (`pipelex/pipeline/pipe_io_contracts.py:104`) makes the count structurally unreachable there.
+- **Who guesses:** nobody — a form cannot enforce "exactly 2" because the wire never says it.
+- **Recommendation:** thread the real multiplicity through the render and memo key, emitting `minItems`/`maxItems`.
+
+### E5. `!` (force) is indistinguishable from plain on the contract
+
+- **Authored:** `inputs = { doc = "Document!" }` — parsed to `presence: force` (`variable_multiplicity.py:26`).
+- **Lost:** hop 5 — `optional=stuff_spec.presence.is_optional` maps force and plain both to `optional: false` (`pipe_io_contracts.py:123`).
+- **Who guesses:** nobody today — for a top-level run form the two are equivalent (the caller must supply the value either way), but the contract cannot express the distinction for any consumer that would care (e.g. a lint or graph surface showing where assertions live).
+- **Recommendation:** a presence enum (or a `force` flag) on the contract if any consumer materializes; low urgency.
+
+### E6. Class-backed concepts lose their description; most native inputs never had one
+
+- **Authored:** the concept's `description` beside `structure = "TextContent"` (probe concept `ClassBacked`).
+- **Lost:** hop 2 — a pre-existing class receives no docstring from the concept, so the schema has no top-level `description` at all. Related, measured on native concepts as direct inputs: only `DateContent` and `TimeContent` carry class docstrings; `Text`, `Image`, `Document`, `Page`, `Number`, `Html`, `YesNo` render schemas with **no top-level description**.
+- **Who guesses:** the RJSF stack *overwrites* the top-level description with the concept ref as a label stand-in (`pipelex-app/src/lib/run-form/run-gate.ts:44-48`), which is also why its dropzone matcher can only ever match nested property descriptions.
+- **Recommendation:** inject the concept description into class-backed and native renders (top-level `description`), same as generated classes already get.
+
+### E7. Unknown keys on a structure field vanish silently at parse
+
+- **Authored:** anything hopeful — `minimum = 0`, `maximum = 10`, `examples = […]`, `unit = "kg"` all author fine and validate green.
+- **Lost:** hop 1 — `ConceptStructureBlueprint` has no `extra="forbid"` (`concept_structure_blueprint.py:50`), so extras are dropped before the blueprint dump; measured absent. The asymmetry is stark: `ConceptBlueprint` itself *does* forbid extras (`concept_blueprint.py:13`), so a typo on a concept fails loudly while a typo (or a hopeful constraint) on a field dies silently.
+- **Who guesses:** the author, who believes they expressed something. Only the (stale) MTHDS lint-hook schema even warns.
+- **Recommendation:** `extra="forbid"` on `ConceptStructureBlueprint` — this also makes the language ceiling (§B) enforceable instead of silent.
+
+### E8. The builder writes `default` instead of `default_value` — the default is silently dropped on re-load
+
+- **Authored:** via the builder / agent-CLI `concept` command — `structure_field_to_dict` emits the TOML key `default` (`pipelex/builder/operations/concept_ops.py:115-116`).
+- **Lost:** hop 1 on the round trip — `ConceptStructureBlueprint` has no alias for `default`, and extras are ignored (E7), so a builder-emitted default validates green and reaches nothing (verified by direct `model_validate`). Docs and fixtures agree the authored spelling is `default_value`; only this writer disagrees.
+- **Who guesses:** any agent or user authoring through the builder — their default evaporates without a signal.
+- **Recommendation:** one-line fix in `concept_ops.py` (write `default_value`); E7's `extra="forbid"` would have caught this as a hard failure. Filed as `../wip/inbox/2026-08-21-pipelex-builder-default-key-dropped.md` so it need not wait for the whole S2 milestone.
+
+### E9. Multiplicity survives only as schema shape, never as a contract field
+
+- **Authored:** the `[]` suffix on the input ref.
+- **Lost:** not lost exactly — transformed at hop 4 into `{type: "array", items: …}` — but the contract's `concept_ref` comes back *without* the suffix and no structured multiplicity field exists, so array-ness is only recoverable by inspecting the schema.
+- **Who guesses:** the app rebuilds `[]` from `json_schema.type === "array"` in three independent places (`pipelex-app/src/lib/input-format.ts:270-284`, `src/lib/pipe-io-contracts.ts:42-44`, `src/lib/run-form/field-model.ts:142-146`), and the divergence between two of those rules produced a real gating bug the app documents at `field-model.ts:398-409`.
+- **Recommendation:** a structured multiplicity field on the contract (which E4's fix would need anyway).
+
+### E10. Single-entry `choices` emit `const`, not `enum` — and the main consumer doesn't read `const`
+
+- **Authored:** `choices = ["only_option"]`.
+- **Transformed:** hop 3 — pydantic renders a one-member `Literal` as `const: "x"` with no `enum` array. Not a loss, but a wire-shape hazard.
+- **Who guesses:** the app branches on `Array.isArray(schema.enum)` only (`field-model.ts:235-238`); `const` is unhandled anywhere in its `src/`, so a single-choice field renders as free text the user can fill wrongly.
+- **Recommendation:** either normalize `const` to a one-member `enum` at the render, or document `const` as part of the contract consumers must read.
+
+---
+
+## B. Language-side ceiling — input to the MTHDS design session (Track H)
+
+MTHDS cannot express these today, in any syntax the parser accepts. The complete authoring surface, for context: a concept carries `description`, `structure` XOR `refines`, and optional `source` (`ConceptBlueprint`, extras forbidden); a structure field carries `description`, `type`, `key_type`/`value_type`, `item_type`, `concept_ref`/`item_concept_ref`, `choices` (strings only), `default_value`, `required` (`ConceptStructureBlueprint` — extras silently ignored, see E7); a pipe's `inputs` values are ref strings whose entire grammar is `concept ref + [] / [N] + ? / !` (`pipelex/pipe_machinery/pipe_blueprint.py:186`; `variable_multiplicity.py:16`). Everything below falls outside that surface:
+
+- **Numeric ranges** (`minimum` / `maximum` / exclusive bounds) — no syntax; note the engine grants *itself* this power (`ImageContent.width` is `gt=0`, `pipelex/core/stuffs/image_content.py:27`), so the schema vocabulary is proven, only the language lacks it. This is the direction doc's slider example.
+- **String constraints** — no length bounds, no pattern.
+- **Examples** — none, at field, concept, or input-slot level. (The inputs template synthesizes placeholders from the *type* instead — `concept_representation_generator.py:143`.)
+- **Units** — no way to say a number is kilograms or euros.
+- **Per-input-slot description on a pipe** — `inputs` values are ref strings only; the table form is rejected (fixture `rejected/per_input_description.mthds_invalid`). A pipe cannot say what *this use* of a concept means.
+- **Per-slot defaults or examples** — same ceiling as above.
+- **Non-string choices** — `choices: list[str]`; `[1, 2, 3]` is rejected.
+- **Choice labels** — a choice is a bare string; no display label or per-choice description.
+- **Inner type of nested lists** — `item_type = "list"` has no syntax for the inner item type; emitted as `list[list[Any]]`, so the wire schema's inner `items` is empty.
+- **Multiple refinement** — `refines` is a single ref (`concept_blueprint.py:20`, TODO recorded at line 19).
+- **Refine-and-extend** — `refines` and `structure` are mutually exclusive (`concept_blueprint.py:95`): a refinement of `native.Document` cannot add fields. Any "Invoice is a Document plus an amount" concept is inexpressible.
+- **Defaults on concept-typed fields** — rejected by design (`concept_structure_blueprint.py:111`); listed for completeness, arguably a correct ceiling.
+- **Rendering intent** (prose vs label, rating, quantity…) — nothing expressible; today the app decides prose-vs-label by nesting depth with a `maxLength > 120` magic number (`field-model.ts:283-289`). This is Layer 3 territory (intent vocabulary), listed here because the *absence* is a language fact.
+
+One asymmetry worth the design session's attention: because of E7, most of this ceiling fails *silently* — an author who writes `minimum = 0` today is told nothing.
+
+---
+
+## C. The two meaning questions, settled by evidence
+
+### What `default_value` means today
+
+It is an **execution-level default applied on absence**, not a form-prefill hint:
+
+- The one runtime ingestion seam for pipe inputs ends at `StuffContentFactory.make_content_from_value` → `stuff_content_subclass.model_validate(obj=value)` (`pipelex/core/stuffs/stuff_content_factory.py:35`), a plain validate — an omitted field with a default gets the default on the instantiated object.
+- The same applies to **LLM structured output**: workers hand the live generated class to instructor as the response model (e.g. `pipelex/providers/google/google_llm_worker.py:268`), so a field the LLM omits is filled by the default too.
+- The **inputs template deliberately omits defaulted fields** rather than prefilling them: the JSON representation is generated with `include_optional=False` (`pipelex/core/concepts/concept.py:183-184`) and the generator skips every non-required field (`concept_representation_generator.py:136-138`) — and a defaulted field is non-required (E3). The template never reads `field_info.default`.
+- The default **is exposed on the wire** (`"default": X` in the hop-3 schema, surviving verbatim to hop 5), so a form *may* render it as a prefill — but that is a consumer's choice layered on the real semantic.
+- Under **dry-run mocks** the default is ignored: polyfactory builds with `__use_defaults__` unset (default `False`), so every field gets a random value (`pipelex/core/memory/working_memory_factory.py:219-225`).
+
+Consequence for D1: the slot's honest name is "value used when the caller omits the field" — prefill is a safe *rendering* of that, but the two are not the same slot. And authoring a default currently *implies* optionality on the wire (E3), which D1 should treat as an engine accident, not a semantic.
+
+### `required` versus `?` — two levels, two routes
+
+They govern different things and travel independently:
+
+- **`required` (structure-field level):** whether a field must be present *within the concept's payload*. Travels inside the `json_schema` as membership in pydantic's `required` array; a non-required field becomes `X | null` with `default: null` (the shape behind the app's flatten-then-repair round trip — `prepareSchemaForRjsf` collapsing the null arm, then `pruneEmptyOptionals` un-blocking untouched optional fields, `pipelex-app/src/lib/input-format.ts:388-421`).
+- **`?` (pipe-slot level):** whether the whole input slot may hold no value. Travels as the `optional: true` flag on the contract (`pipe_io_contracts.py:123`); the `json_schema` itself is unchanged. This is the gating rule — the app stamps its Run gate from the contract flag (`field-model.ts:345-351`).
+- **`!` (pipe-slot level):** a *use-site assertion* that a maybe-absent slot is present at run time — meaningless on outputs (rejected, `pipe_blueprint.py:335`), linted as redundant when every flow guarantees the slot (`pipelex/pipeline/optionality_warnings.py`). On the contract it is flattened into plain (E5).
+
+The two levels never interact in the emission: `?` on a slot does not touch the payload schema, and a field's `required` never bubbles up to the slot.
+
+---
+
+## D. Engine-authored semantics on native content classes — the catalogue
+
+Descriptions and field names written in this repo, not by method authors. The ones marked ⚠ are **contracts-in-disguise**: a downstream surface keys on them today, so changing them is S2 work with a blast radius.
+
+| Class / field | Engine-authored text or shape | Downstream coupling |
+|---|---|---|
+| `DocumentContent.url` (`document_content.py:16`) | "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL" | ⚠ Matched by substring (lowercased `"document url"`) to assign the upload dropzone (`pipelex-app/src/components/method/document-url-widget.tsx:130-136`). The matcher's other branch, `"pipelex storage url"`, **already matches nothing** — the wording drifted and half the contract is dead. Renaming away "document url" silently removes every dropzone in the MethodViewer panel. |
+| `DocumentContent` field names (`url`, `public_url`, `mime_type`, `filename`, `title`, `snippet`) | the model's shape | ⚠ Hardcoded as a value-sniff set (`pipelex-app/src/lib/input-format.ts:176-182`) and `properties.url` alone makes any concept a document with a dropzone (`field-model.ts:186-197`, also `:362-365` for run-gating readiness). Renaming `url` breaks document detection, upload, and gating in both stacks. |
+| `TextContent.text` (`text_content.py:17`) | "The text" + the single-field `{text}` shape | ⚠ The `{text: "…"}` wrapper shape is assumed by the app's wrapping sets (`run-values.ts:35-48`, applied at `:129`), the deflate/inflate rules (`input-format.ts:78-136`), and `healStringWrappers` (`input-format.ts:312-369`). Renaming `text` breaks text round-tripping everywhere. |
+| `ImageContent.url` (`image_content.py:20`) | "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL" | Matches neither dropzone substring (measured) — image upload in the runner stack works only via the hardcoded concept sets (E1); shape-wise, `properties.url` makes images sniff as documents. |
+| `ImageContent.width` / `.height` (`image_content.py:27-28`) | `gt=0` constraints + descriptions | Proof the engine can emit numeric bounds the language cannot author (§B). |
+| `DateContent` / `TimeContent` docstrings (`date_content.py:17`, `time_content.py:16`) | the only two native classes whose schemas carry a top-level description | `DateContent.time` (optional, `format: time`) is the app's canonical flatten-then-repair casualty, cited in `pruneEmptyOptionals`' docstring (`input-format.ts:371-386`). |
+| `PageContent.text_and_images` / `.page_view` (`page_content.py:14-15`) | extraction-oriented descriptions | No known coupling; `native.Page` is folded into the app's document branch by concept set, not by these. |
+| `NumberContent.number`, `HtmlContent.inner_html`/`.css_class`, `YesNoContent.yes_no`, `TextAndImagesContent.*` | plain descriptive prose | No known coupling beyond the generic wrapper handling. |
+
+Sweep method note: couplings were found by searching `pipelex-app` for description substrings, field-name sniff sets, and wrapper-shape assumptions; `base_64` / `source_prompt` sniffing was explicitly checked for and does not exist — those shapes fall through to the raw-JSON field, i.e. they are uncompensated gaps, not contracts.
+
+---
+
+## E. Ranking for S2
+
+Worked-around gaps first, per the brief:
+
+1. **E1 + E2** (concept identity, refinement chain) — compensated by three drifted hardcoded ref-set copies, two shape sniffs, and a half-dead description matcher; every one of the app's heaviest heuristics traces to these two.
+2. **E6** (missing top-level descriptions) — compensated by clobbering description with the concept ref.
+3. **E9** (multiplicity as shape only) — compensated three times, with one documented gating bug.
+4. **E7 + E8** (silent extras; builder `default` key) — nobody *can* work around silent loss; E8 is a live data-loss bug in the authoring path.
+5. **E3** (`required` + `default_value`) — silent semantic rewrite, uncompensated.
+6. **E10** (`const` unread) — a real form-correctness hole, one-line-ish on either side.
+7. **E4, E5** (`[N]`, `!`) — uncompensated and currently consequence-free; close them when touching the adjacent code (E4 rides E9's contract change).
diff --git a/wip/input-semantics/probe/hop1_bundle_blueprints.json b/wip/input-semantics/probe/hop1_bundle_blueprints.json
new file mode 100644
index 000000000..e1df6e3dc
--- /dev/null
+++ b/wip/input-semantics/probe/hop1_bundle_blueprints.json
@@ -0,0 +1,493 @@
+[
+ {
+ "source": "tests/data/input_semantics/probe_bundle.mthds",
+ "domain": "input_semantics_probe",
+ "description": "PROBE_bundle_desc: probe bundle for the input-semantics audit — every authored fact carries a PROBE_ sentinel so its survival is greppable in every capture",
+ "system_prompt": null,
+ "main_pipe": "probe_single",
+ "concept": {
+ "StringNote": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
+ "Trinket": {
+ "source": null,
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "structure": {
+ "label": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf"
+ },
+ "refines": null
+ },
+ "Gadget": {
+ "source": null,
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "structure": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": true
+ },
+ "trinket": {
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "type": "concept",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": "Trinket",
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ }
+ },
+ "refines": null
+ },
+ "Widget": {
+ "source": null,
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "structure": {
+ "shorthand_note": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": true
+ },
+ "subtitle": {
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "summary": {
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "motto": {
+ "description": "PROBE_desc_field_motto: text with default",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": "PROBE_default_motto",
+ "required": false
+ },
+ "titled_default": {
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": "PROBE_default_titled",
+ "required": true
+ },
+ "count": {
+ "description": "PROBE_desc_field_count: integer with default",
+ "type": "integer",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": 42,
+ "required": false
+ },
+ "enabled": {
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "type": "boolean",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": true,
+ "required": false
+ },
+ "price": {
+ "description": "PROBE_desc_field_price: number with default",
+ "type": "number",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": 9.99,
+ "required": false
+ },
+ "released_on": {
+ "description": "PROBE_desc_field_released_on: date with default",
+ "type": "date",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": "2026-01-15",
+ "required": false
+ },
+ "launched_at": {
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "type": "datetime",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": "2026-01-15T12:30:00",
+ "required": false
+ },
+ "daily_at": {
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "type": "time",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": "12:30:00",
+ "required": false
+ },
+ "tags": {
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "type": "list",
+ "key_type": null,
+ "value_type": null,
+ "item_type": "text",
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "required": false
+ },
+ "ratings": {
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "type": "list",
+ "key_type": null,
+ "value_type": null,
+ "item_type": "integer",
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "matrix": {
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "type": "list",
+ "key_type": null,
+ "value_type": null,
+ "item_type": "list",
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "gadgets": {
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "type": "list",
+ "key_type": null,
+ "value_type": null,
+ "item_type": "concept",
+ "concept_ref": null,
+ "item_concept_ref": "Gadget",
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "attributes": {
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "type": "dict",
+ "key_type": "text",
+ "value_type": "text",
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "scores": {
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "type": "dict",
+ "key_type": "text",
+ "value_type": "number",
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": {
+ "speed": 5
+ },
+ "required": false
+ },
+ "milestones": {
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "type": "dict",
+ "key_type": "text",
+ "value_type": "date",
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "main_gadget": {
+ "description": "PROBE_desc_field_main_gadget: required concept field",
+ "type": "concept",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": "Gadget",
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": true
+ },
+ "icon": {
+ "description": "PROBE_desc_field_icon: native concept field",
+ "type": "concept",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": "native.Image",
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ },
+ "tone": {
+ "description": "PROBE_desc_field_tone: choices with default",
+ "type": null,
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "default_value": "PROBE_choice_casual",
+ "required": false
+ },
+ "only_choice": {
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "type": null,
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": [
+ "PROBE_choice_single"
+ ],
+ "default_value": null,
+ "required": false
+ },
+ "typed_choice": {
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "default_value": null,
+ "required": false
+ },
+ "constrained_count": {
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "type": "integer",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": false
+ }
+ },
+ "refines": null
+ },
+ "PlainNote": {
+ "source": null,
+ "description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
+ "structure": null,
+ "refines": null
+ },
+ "RefinedDoc": {
+ "source": null,
+ "description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
+ "structure": null,
+ "refines": "native.Document"
+ },
+ "BaseEntity": {
+ "source": null,
+ "description": "PROBE_desc_concept_BaseEntity: base of a custom refinement chain",
+ "structure": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "type": "text",
+ "key_type": null,
+ "value_type": null,
+ "item_type": null,
+ "concept_ref": null,
+ "item_concept_ref": null,
+ "choices": null,
+ "default_value": null,
+ "required": true
+ }
+ },
+ "refines": null
+ },
+ "SpecialEntity": {
+ "source": null,
+ "description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
+ "structure": null,
+ "refines": "BaseEntity"
+ },
+ "ExtraSpecialEntity": {
+ "source": null,
+ "description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
+ "structure": null,
+ "refines": "SpecialEntity"
+ },
+ "ClassBacked": {
+ "source": null,
+ "description": "PROBE_desc_concept_ClassBacked: structure declared as an existing class name",
+ "structure": "TextContent",
+ "refines": null
+ }
+ },
+ "pipe": {
+ "probe_single": {
+ "source": null,
+ "pipe_category": "PipeOperator",
+ "type": "PipeLLM",
+ "description": "PROBE_pipe_probe_single: plain structured, qualified, and description-only inputs",
+ "inputs": {
+ "widget": "Widget",
+ "gadget_q": "input_semantics_probe.Gadget",
+ "note": "PlainNote"
+ },
+ "output": "Text",
+ "model": null,
+ "model_to_structure": null,
+ "system_prompt": null,
+ "prompt": "Consider the widget:\n@widget\nAnd the gadget:\n@gadget_q\nAnd the note:\n@note\n",
+ "structuring_method": null,
+ "templating_style": null
+ },
+ "probe_native_inputs": {
+ "source": null,
+ "pipe_category": "PipeOperator",
+ "type": "PipeLLM",
+ "description": "PROBE_pipe_probe_native_inputs: native concepts as direct inputs",
+ "inputs": {
+ "text_in": "Text",
+ "image_in": "Image",
+ "document_in": "Document",
+ "page_in": "Page",
+ "number_in": "Number",
+ "date_in": "Date",
+ "time_in": "Time",
+ "html_in": "Html",
+ "yesno_in": "YesNo"
+ },
+ "output": "Text",
+ "model": null,
+ "model_to_structure": null,
+ "system_prompt": null,
+ "prompt": "@text_in\n@image_in\n@document_in\n@page_in\n@number_in\n@date_in\n@time_in\n@html_in\n@yesno_in\n",
+ "structuring_method": null,
+ "templating_style": null
+ },
+ "probe_markers": {
+ "source": null,
+ "pipe_category": "PipeOperator",
+ "type": "PipeLLM",
+ "description": "PROBE_pipe_probe_markers: optional, list, fixed-count, and force markers",
+ "inputs": {
+ "opt": "Widget?",
+ "many": "Widget[]",
+ "two": "Gadget[2]",
+ "forced": "Text!"
+ },
+ "output": "Text",
+ "model": null,
+ "model_to_structure": null,
+ "system_prompt": null,
+ "prompt": "@?opt\nMany widgets:\n@many\nTwo gadgets:\n@two\nForced text:\n@forced\n",
+ "structuring_method": null,
+ "templating_style": null
+ },
+ "probe_refined": {
+ "source": null,
+ "pipe_category": "PipeOperator",
+ "type": "PipeLLM",
+ "description": "PROBE_pipe_probe_refined: refinements and class-backed concepts as inputs",
+ "inputs": {
+ "refdoc": "RefinedDoc",
+ "special": "SpecialEntity",
+ "extra": "ExtraSpecialEntity",
+ "classbacked": "ClassBacked",
+ "stringnote": "StringNote"
+ },
+ "output": "Text",
+ "model": null,
+ "model_to_structure": null,
+ "system_prompt": null,
+ "prompt": "@refdoc\n@special\n@extra\n@classbacked\n@stringnote\n",
+ "structuring_method": null,
+ "templating_style": null
+ }
+ }
+ }
+]
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.BaseEntity.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.BaseEntity.py.txt
new file mode 100644
index 000000000..41982cf5c
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.BaseEntity.py.txt
@@ -0,0 +1,22 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__BaseEntity(StructuredContent):
+ """PROBE_desc_concept_BaseEntity: base of a custom refinement chain"""
+
+ ident: str = Field(..., description="PROBE_desc_field_base_ident: inherited field")
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.ExtraSpecialEntity.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.ExtraSpecialEntity.py.txt
new file mode 100644
index 000000000..397db4cd1
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.ExtraSpecialEntity.py.txt
@@ -0,0 +1,21 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__ExtraSpecialEntity(input_semantics_probe__SpecialEntity):
+ """PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain"""
+
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Gadget.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Gadget.py.txt
new file mode 100644
index 000000000..8c98da57e
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Gadget.py.txt
@@ -0,0 +1,23 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__Gadget(StructuredContent):
+ """PROBE_desc_concept_Gadget: mid-level structure nested inside Widget"""
+
+ name: str = Field(..., description="PROBE_desc_field_gadget_name")
+ trinket: "input_semantics_probe__Trinket | None" = Field(default=None, description="PROBE_desc_field_gadget_trinket: nested concept, level two")
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.PlainNote.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.PlainNote.py.txt
new file mode 100644
index 000000000..90c9178db
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.PlainNote.py.txt
@@ -0,0 +1,22 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pipelex.core.stuffs.text_content import TextContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__PlainNote(TextContent):
+ """PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)"""
+
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.RefinedDoc.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.RefinedDoc.py.txt
new file mode 100644
index 000000000..c30b9f8f4
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.RefinedDoc.py.txt
@@ -0,0 +1,22 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.document_content import DocumentContent
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__RefinedDoc(DocumentContent):
+ """PROBE_desc_concept_RefinedDoc: refinement of a native concept"""
+
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.SpecialEntity.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.SpecialEntity.py.txt
new file mode 100644
index 000000000..9efc8cfd3
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.SpecialEntity.py.txt
@@ -0,0 +1,21 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__SpecialEntity(input_semantics_probe__BaseEntity):
+ """PROBE_desc_concept_SpecialEntity: refines a custom concept"""
+
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.StringNote.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.StringNote.py.txt
new file mode 100644
index 000000000..32319633e
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.StringNote.py.txt
@@ -0,0 +1,22 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pipelex.core.stuffs.text_content import TextContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__StringNote(TextContent):
+ """PROBE_desc_concept_StringNote: a concept declared as a bare string"""
+
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Trinket.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Trinket.py.txt
new file mode 100644
index 000000000..fb7fad11f
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Trinket.py.txt
@@ -0,0 +1,22 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from enum import Enum
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__Trinket(StructuredContent):
+ """PROBE_desc_concept_Trinket: leaf structure for two-level nesting"""
+
+ label: str = Field(..., description="PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf")
diff --git a/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Widget.py.txt b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Widget.py.txt
new file mode 100644
index 000000000..7db811df0
--- /dev/null
+++ b/wip/input-semantics/probe/hop2_generated_sources/input_semantics_probe.Widget.py.txt
@@ -0,0 +1,50 @@
+"""
+AUTOGENERATED CODE - DO NOT EDIT
+
+If you want to customize this structure:
+ 1. Copy this file to your own module
+ 2. Remove the 'structure' or 'refines' declaration from the concept in the MTHDS file
+ and declare it in inline mode (see https://docs.pipelex.com/latest/building-methods/concepts/define_your_concepts/#basic-concept-definition)
+ 3. Make sure your custom class is importable and registered
+
+To regenerate: pipelex build structures <target_directory>
+"""
+
+from datetime import date
+from datetime import datetime
+from datetime import time
+from enum import Enum
+from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.core.stuffs.structured_content import StructuredContent
+from pydantic import Field
+from typing import Any, Literal
+
+
+class input_semantics_probe__Widget(StructuredContent):
+ """PROBE_desc_concept_Widget: the full-matrix structure under audit"""
+
+ shorthand_note: str = Field(..., description="PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)")
+ title: str = Field(..., description="PROBE_desc_field_title: required text")
+ subtitle: str | None = Field(default=None, description="PROBE_desc_field_subtitle: optional text (required omitted)")
+ summary: str | None = Field(default=None, description="PROBE_desc_field_summary: optional text (required explicit false)")
+ motto: str | None = Field(default="PROBE_default_motto", description="PROBE_desc_field_motto: text with default")
+ titled_default: str = Field(default="PROBE_default_titled", description="PROBE_desc_field_titled_default: required AND default together")
+ count: int | None = Field(default=42, description="PROBE_desc_field_count: integer with default")
+ enabled: bool | None = Field(default=True, description="PROBE_desc_field_enabled: boolean with default")
+ price: float | None = Field(default=9.99, description="PROBE_desc_field_price: number with default")
+ released_on: date | None = Field(default=date.fromisoformat("2026-01-15"), description="PROBE_desc_field_released_on: date with default")
+ launched_at: datetime | None = Field(default=datetime.fromisoformat("2026-01-15T12:30:00"), description="PROBE_desc_field_launched_at: datetime with default")
+ daily_at: time | None = Field(default=time.fromisoformat("12:30:00"), description="PROBE_desc_field_daily_at: time with default")
+ tags: list[str] | None = Field(default=["PROBE_tag_a", "PROBE_tag_b"], description="PROBE_desc_field_tags: list of text with default")
+ ratings: list[int] | None = Field(default=None, description="PROBE_desc_field_ratings: list of integer")
+ matrix: list[list[Any]] | None = Field(default=None, description="PROBE_desc_field_matrix: nested list with unspecified inner item")
+ gadgets: list["input_semantics_probe__Gadget"] | None = Field(default=None, description="PROBE_desc_field_gadgets: list of concept")
+ attributes: dict[str, str] | None = Field(default=None, description="PROBE_desc_field_attributes: dict text to text")
+ scores: dict[str, float] | None = Field(default={"speed": 5}, description="PROBE_desc_field_scores: dict text to number with default")
+ milestones: dict[str, date] | None = Field(default=None, description="PROBE_desc_field_milestones: dict text to date")
+ main_gadget: "input_semantics_probe__Gadget" = Field(..., description="PROBE_desc_field_main_gadget: required concept field")
+ icon: ImageContent | None = Field(default=None, description="PROBE_desc_field_icon: native concept field")
+ tone: Literal["PROBE_choice_formal", "PROBE_choice_casual", "PROBE_choice_playful"] | None = Field(default="PROBE_choice_casual", description="PROBE_desc_field_tone: choices with default")
+ only_choice: Literal["PROBE_choice_single"] | None = Field(default=None, description="PROBE_desc_field_only_choice: single-entry choice list")
+ typed_choice: Literal["PROBE_choice_typed_a", "PROBE_choice_typed_b"] | None = Field(default=None, description="PROBE_desc_field_typed_choice: type AND choices together")
+ constrained_count: int | None = Field(default=None, description="PROBE_desc_field_constrained_count: integer carrying unknown constraint keys")
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.BaseEntity.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.BaseEntity.json
new file mode 100644
index 000000000..958247548
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.BaseEntity.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_BaseEntity: base of a custom refinement chain",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__BaseEntity",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ClassBacked.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ClassBacked.json
new file mode 100644
index 000000000..1020c00aa
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ClassBacked.json
@@ -0,0 +1,14 @@
+{
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ExtraSpecialEntity.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ExtraSpecialEntity.json
new file mode 100644
index 000000000..335f03b25
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.ExtraSpecialEntity.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__ExtraSpecialEntity",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Gadget.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Gadget.json
new file mode 100644
index 000000000..edad748a0
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Gadget.json
@@ -0,0 +1,44 @@
+{
+ "$defs": {
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.PlainNote.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.PlainNote.json
new file mode 100644
index 000000000..fc293e0f6
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.PlainNote.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__PlainNote",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.RefinedDoc.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.RefinedDoc.json
new file mode 100644
index 000000000..6c3793e79
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.RefinedDoc.json
@@ -0,0 +1,80 @@
+{
+ "description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "input_semantics_probe__RefinedDoc",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.SpecialEntity.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.SpecialEntity.json
new file mode 100644
index 000000000..7e5c4aa80
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.SpecialEntity.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__SpecialEntity",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.StringNote.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.StringNote.json
new file mode 100644
index 000000000..7c3d3b33e
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.StringNote.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__StringNote",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Trinket.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Trinket.json
new file mode 100644
index 000000000..707d94a36
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Trinket.json
@@ -0,0 +1,15 @@
+{
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Widget.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Widget.json
new file mode 100644
index 000000000..458762f02
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/input_semantics_probe.Widget.json
@@ -0,0 +1,509 @@
+{
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Date.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Date.json
new file mode 100644
index 000000000..76cd0a7fb
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Date.json
@@ -0,0 +1,30 @@
+{
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.\n\nThe optional ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). Invalid states are unrepresentable by construction: no time\nwithout a date, no offset without a time.",
+ "properties": {
+ "date": {
+ "description": "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.",
+ "format": "date",
+ "title": "Date",
+ "type": "string"
+ },
+ "time": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset). Include it only when the source states a time — never invent a time. Keep the UTC offset exactly when the source states one.",
+ "title": "Time"
+ }
+ },
+ "required": [
+ "date"
+ ],
+ "title": "DateContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Document.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Document.json
new file mode 100644
index 000000000..3dc39647d
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Document.json
@@ -0,0 +1,79 @@
+{
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "DocumentContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Html.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Html.json
new file mode 100644
index 000000000..e73e5c975
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Html.json
@@ -0,0 +1,20 @@
+{
+ "properties": {
+ "inner_html": {
+ "description": "The inner HTML of the content",
+ "title": "Inner Html",
+ "type": "string"
+ },
+ "css_class": {
+ "description": "The CSS class of the content",
+ "title": "Css Class",
+ "type": "string"
+ }
+ },
+ "required": [
+ "inner_html",
+ "css_class"
+ ],
+ "title": "HtmlContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Image.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Image.json
new file mode 100644
index 000000000..6b399a78a
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Image.json
@@ -0,0 +1,120 @@
+{
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Number.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Number.json
new file mode 100644
index 000000000..cecae614b
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Number.json
@@ -0,0 +1,21 @@
+{
+ "properties": {
+ "number": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "number"
+ }
+ ],
+ "description": "The number",
+ "title": "Number"
+ }
+ },
+ "required": [
+ "number"
+ ],
+ "title": "NumberContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Page.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Page.json
new file mode 100644
index 000000000..a2846983c
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Page.json
@@ -0,0 +1,208 @@
+{
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "TextAndImagesContent": {
+ "properties": {
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/TextContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text content"
+ },
+ "images": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/ImageContent"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A list of images that were extracted from the text",
+ "title": "Images"
+ },
+ "raw_html": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The raw HTML of the fetched page, if requested",
+ "title": "Raw Html"
+ }
+ },
+ "title": "TextAndImagesContent",
+ "type": "object"
+ },
+ "TextContent": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ },
+ "properties": {
+ "text_and_images": {
+ "$ref": "#/$defs/TextAndImagesContent",
+ "description": "The text and images content extracted from the page"
+ },
+ "page_view": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The screenshot of the page"
+ }
+ },
+ "required": [
+ "text_and_images"
+ ],
+ "title": "PageContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Text.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Text.json
new file mode 100644
index 000000000..1020c00aa
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Text.json
@@ -0,0 +1,14 @@
+{
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Time.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Time.json
new file mode 100644
index 000000000..ae627eca4
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Time.json
@@ -0,0 +1,16 @@
+{
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.\n\nThe ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). A time of day is not an instant: it has no date to\nattach to, so it never converts to a datetime on its own.",
+ "properties": {
+ "time": {
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset).",
+ "format": "time",
+ "title": "Time",
+ "type": "string"
+ }
+ },
+ "required": [
+ "time"
+ ],
+ "title": "TimeContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.YesNo.json b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.YesNo.json
new file mode 100644
index 000000000..b21293654
--- /dev/null
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.YesNo.json
@@ -0,0 +1,14 @@
+{
+ "properties": {
+ "yes_no": {
+ "description": "Whether the answer is yes (true) or no (false).",
+ "title": "Yes No",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "yes_no"
+ ],
+ "title": "YesNoContent",
+ "type": "object"
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__forced.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__forced.json
new file mode 100644
index 000000000..2fe21f3c4
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__forced.json
@@ -0,0 +1,17 @@
+{
+ "concept": "native.Text",
+ "content": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__many.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__many.json
new file mode 100644
index 000000000..dc46ffe64
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__many.json
@@ -0,0 +1,515 @@
+{
+ "concept": "input_semantics_probe.Widget",
+ "content": {
+ "type": "array",
+ "items": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__opt.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__opt.json
new file mode 100644
index 000000000..0f1930229
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__opt.json
@@ -0,0 +1,512 @@
+{
+ "concept": "input_semantics_probe.Widget",
+ "content": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__two.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__two.json
new file mode 100644
index 000000000..82fb9e896
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_markers__two.json
@@ -0,0 +1,50 @@
+{
+ "concept": "input_semantics_probe.Gadget",
+ "content": {
+ "type": "array",
+ "items": {
+ "$defs": {
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ }
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__date_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__date_in.json
new file mode 100644
index 000000000..529a8fe03
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__date_in.json
@@ -0,0 +1,33 @@
+{
+ "concept": "native.Date",
+ "content": {
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.\n\nThe optional ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). Invalid states are unrepresentable by construction: no time\nwithout a date, no offset without a time.",
+ "properties": {
+ "date": {
+ "description": "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.",
+ "format": "date",
+ "title": "Date",
+ "type": "string"
+ },
+ "time": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset). Include it only when the source states a time — never invent a time. Keep the UTC offset exactly when the source states one.",
+ "title": "Time"
+ }
+ },
+ "required": [
+ "date"
+ ],
+ "title": "DateContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__document_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__document_in.json
new file mode 100644
index 000000000..e3805f734
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__document_in.json
@@ -0,0 +1,82 @@
+{
+ "concept": "native.Document",
+ "content": {
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "DocumentContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__html_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__html_in.json
new file mode 100644
index 000000000..fcccee0ae
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__html_in.json
@@ -0,0 +1,23 @@
+{
+ "concept": "native.Html",
+ "content": {
+ "properties": {
+ "inner_html": {
+ "description": "The inner HTML of the content",
+ "title": "Inner Html",
+ "type": "string"
+ },
+ "css_class": {
+ "description": "The CSS class of the content",
+ "title": "Css Class",
+ "type": "string"
+ }
+ },
+ "required": [
+ "inner_html",
+ "css_class"
+ ],
+ "title": "HtmlContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__image_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__image_in.json
new file mode 100644
index 000000000..cb8b56296
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__image_in.json
@@ -0,0 +1,123 @@
+{
+ "concept": "native.Image",
+ "content": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__number_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__number_in.json
new file mode 100644
index 000000000..2fe035890
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__number_in.json
@@ -0,0 +1,24 @@
+{
+ "concept": "native.Number",
+ "content": {
+ "properties": {
+ "number": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "number"
+ }
+ ],
+ "description": "The number",
+ "title": "Number"
+ }
+ },
+ "required": [
+ "number"
+ ],
+ "title": "NumberContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__page_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__page_in.json
new file mode 100644
index 000000000..e5d3185ac
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__page_in.json
@@ -0,0 +1,211 @@
+{
+ "concept": "native.Page",
+ "content": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "TextAndImagesContent": {
+ "properties": {
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/TextContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text content"
+ },
+ "images": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/ImageContent"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A list of images that were extracted from the text",
+ "title": "Images"
+ },
+ "raw_html": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The raw HTML of the fetched page, if requested",
+ "title": "Raw Html"
+ }
+ },
+ "title": "TextAndImagesContent",
+ "type": "object"
+ },
+ "TextContent": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ },
+ "properties": {
+ "text_and_images": {
+ "$ref": "#/$defs/TextAndImagesContent",
+ "description": "The text and images content extracted from the page"
+ },
+ "page_view": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The screenshot of the page"
+ }
+ },
+ "required": [
+ "text_and_images"
+ ],
+ "title": "PageContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__text_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__text_in.json
new file mode 100644
index 000000000..2fe21f3c4
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__text_in.json
@@ -0,0 +1,17 @@
+{
+ "concept": "native.Text",
+ "content": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__time_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__time_in.json
new file mode 100644
index 000000000..f0268668c
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__time_in.json
@@ -0,0 +1,19 @@
+{
+ "concept": "native.Time",
+ "content": {
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.\n\nThe ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). A time of day is not an instant: it has no date to\nattach to, so it never converts to a datetime on its own.",
+ "properties": {
+ "time": {
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset).",
+ "format": "time",
+ "title": "Time",
+ "type": "string"
+ }
+ },
+ "required": [
+ "time"
+ ],
+ "title": "TimeContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__yesno_in.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__yesno_in.json
new file mode 100644
index 000000000..ee06c2a86
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_native_inputs__yesno_in.json
@@ -0,0 +1,17 @@
+{
+ "concept": "native.YesNo",
+ "content": {
+ "properties": {
+ "yes_no": {
+ "description": "Whether the answer is yes (true) or no (false).",
+ "title": "Yes No",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "yes_no"
+ ],
+ "title": "YesNoContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__classbacked.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__classbacked.json
new file mode 100644
index 000000000..1acf67d0a
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__classbacked.json
@@ -0,0 +1,17 @@
+{
+ "concept": "input_semantics_probe.ClassBacked",
+ "content": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__extra.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__extra.json
new file mode 100644
index 000000000..36dc9b616
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__extra.json
@@ -0,0 +1,18 @@
+{
+ "concept": "input_semantics_probe.ExtraSpecialEntity",
+ "content": {
+ "description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__ExtraSpecialEntity",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__refdoc.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__refdoc.json
new file mode 100644
index 000000000..42964bbab
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__refdoc.json
@@ -0,0 +1,83 @@
+{
+ "concept": "input_semantics_probe.RefinedDoc",
+ "content": {
+ "description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "input_semantics_probe__RefinedDoc",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__special.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__special.json
new file mode 100644
index 000000000..d06772ae8
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__special.json
@@ -0,0 +1,18 @@
+{
+ "concept": "input_semantics_probe.SpecialEntity",
+ "content": {
+ "description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__SpecialEntity",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__stringnote.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__stringnote.json
new file mode 100644
index 000000000..7f6bdf728
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_refined__stringnote.json
@@ -0,0 +1,18 @@
+{
+ "concept": "input_semantics_probe.StringNote",
+ "content": {
+ "description": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__StringNote",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__gadget_q.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__gadget_q.json
new file mode 100644
index 000000000..ff263d941
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__gadget_q.json
@@ -0,0 +1,47 @@
+{
+ "concept": "input_semantics_probe.Gadget",
+ "content": {
+ "$defs": {
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__note.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__note.json
new file mode 100644
index 000000000..7dba7d9ad
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__note.json
@@ -0,0 +1,18 @@
+{
+ "concept": "input_semantics_probe.PlainNote",
+ "content": {
+ "description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__PlainNote",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__widget.json b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__widget.json
new file mode 100644
index 000000000..0f1930229
--- /dev/null
+++ b/wip/input-semantics/probe/hop4_schema_renders/input_semantics_probe.probe_single__widget.json
@@ -0,0 +1,512 @@
+{
+ "concept": "input_semantics_probe.Widget",
+ "content": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+}
diff --git a/wip/input-semantics/probe/hop5_pipe_io_contracts.json b/wip/input-semantics/probe/hop5_pipe_io_contracts.json
new file mode 100644
index 000000000..ebd2d986d
--- /dev/null
+++ b/wip/input-semantics/probe/hop5_pipe_io_contracts.json
@@ -0,0 +1,2433 @@
+{
+ "input_semantics_probe.probe_single": {
+ "inputs": {
+ "widget": {
+ "concept_ref": "input_semantics_probe.Widget",
+ "optional": false,
+ "json_schema": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+ },
+ "gadget_q": {
+ "concept_ref": "input_semantics_probe.Gadget",
+ "optional": false,
+ "json_schema": {
+ "$defs": {
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ }
+ },
+ "note": {
+ "concept_ref": "input_semantics_probe.PlainNote",
+ "optional": false,
+ "json_schema": {
+ "description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__PlainNote",
+ "type": "object"
+ }
+ }
+ },
+ "output": {
+ "concept_ref": "native.Text",
+ "multiplicity": "single",
+ "optional": false
+ }
+ },
+ "input_semantics_probe.probe_native_inputs": {
+ "inputs": {
+ "text_in": {
+ "concept_ref": "native.Text",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ },
+ "image_in": {
+ "concept_ref": "native.Image",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ }
+ },
+ "document_in": {
+ "concept_ref": "native.Document",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "DocumentContent",
+ "type": "object"
+ }
+ },
+ "page_in": {
+ "concept_ref": "native.Page",
+ "optional": false,
+ "json_schema": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "TextAndImagesContent": {
+ "properties": {
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/TextContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text content"
+ },
+ "images": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/ImageContent"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A list of images that were extracted from the text",
+ "title": "Images"
+ },
+ "raw_html": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The raw HTML of the fetched page, if requested",
+ "title": "Raw Html"
+ }
+ },
+ "title": "TextAndImagesContent",
+ "type": "object"
+ },
+ "TextContent": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ },
+ "properties": {
+ "text_and_images": {
+ "$ref": "#/$defs/TextAndImagesContent",
+ "description": "The text and images content extracted from the page"
+ },
+ "page_view": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The screenshot of the page"
+ }
+ },
+ "required": [
+ "text_and_images"
+ ],
+ "title": "PageContent",
+ "type": "object"
+ }
+ },
+ "number_in": {
+ "concept_ref": "native.Number",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "number": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "number"
+ }
+ ],
+ "description": "The number",
+ "title": "Number"
+ }
+ },
+ "required": [
+ "number"
+ ],
+ "title": "NumberContent",
+ "type": "object"
+ }
+ },
+ "date_in": {
+ "concept_ref": "native.Date",
+ "optional": false,
+ "json_schema": {
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.\n\nThe optional ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). Invalid states are unrepresentable by construction: no time\nwithout a date, no offset without a time.",
+ "properties": {
+ "date": {
+ "description": "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.",
+ "format": "date",
+ "title": "Date",
+ "type": "string"
+ },
+ "time": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset). Include it only when the source states a time — never invent a time. Keep the UTC offset exactly when the source states one.",
+ "title": "Time"
+ }
+ },
+ "required": [
+ "date"
+ ],
+ "title": "DateContent",
+ "type": "object"
+ }
+ },
+ "time_in": {
+ "concept_ref": "native.Time",
+ "optional": false,
+ "json_schema": {
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.\n\nThe ``time`` carries the UTC offset on its ``tzinfo`` when the source states one\n(fidelity, not normalization). A time of day is not an instant: it has no date to\nattach to, so it never converts to a datetime on its own.",
+ "properties": {
+ "time": {
+ "description": "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset).",
+ "format": "time",
+ "title": "Time",
+ "type": "string"
+ }
+ },
+ "required": [
+ "time"
+ ],
+ "title": "TimeContent",
+ "type": "object"
+ }
+ },
+ "html_in": {
+ "concept_ref": "native.Html",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "inner_html": {
+ "description": "The inner HTML of the content",
+ "title": "Inner Html",
+ "type": "string"
+ },
+ "css_class": {
+ "description": "The CSS class of the content",
+ "title": "Css Class",
+ "type": "string"
+ }
+ },
+ "required": [
+ "inner_html",
+ "css_class"
+ ],
+ "title": "HtmlContent",
+ "type": "object"
+ }
+ },
+ "yesno_in": {
+ "concept_ref": "native.YesNo",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "yes_no": {
+ "description": "Whether the answer is yes (true) or no (false).",
+ "title": "Yes No",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "yes_no"
+ ],
+ "title": "YesNoContent",
+ "type": "object"
+ }
+ }
+ },
+ "output": {
+ "concept_ref": "native.Text",
+ "multiplicity": "single",
+ "optional": false
+ }
+ },
+ "input_semantics_probe.probe_markers": {
+ "inputs": {
+ "opt": {
+ "concept_ref": "input_semantics_probe.Widget",
+ "optional": true,
+ "json_schema": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+ },
+ "many": {
+ "concept_ref": "input_semantics_probe.Widget",
+ "optional": false,
+ "json_schema": {
+ "type": "array",
+ "items": {
+ "$defs": {
+ "ImageContent": {
+ "properties": {
+ "url": {
+ "description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public URL of the image",
+ "title": "Public Url"
+ },
+ "source_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source prompt of the image",
+ "title": "Source Prompt"
+ },
+ "source_negative_prompt": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The source negative prompt of the image",
+ "title": "Source Negative Prompt"
+ },
+ "caption": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The caption of the image",
+ "title": "Caption"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the image",
+ "title": "Mime Type"
+ },
+ "width": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The width of the image, in pixels",
+ "title": "Width"
+ },
+ "height": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The height of the image, in pixels",
+ "title": "Height"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the image",
+ "title": "Filename"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "ImageContent",
+ "type": "object"
+ },
+ "input_semantics_probe__Gadget": {
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ },
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "properties": {
+ "shorthand_note": {
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "title": "Shorthand Note",
+ "type": "string"
+ },
+ "title": {
+ "description": "PROBE_desc_field_title: required text",
+ "title": "Title",
+ "type": "string"
+ },
+ "subtitle": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "title": "Subtitle"
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "title": "Summary"
+ },
+ "motto": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_default_motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "title": "Motto"
+ },
+ "titled_default": {
+ "default": "PROBE_default_titled",
+ "description": "PROBE_desc_field_titled_default: required AND default together",
+ "title": "Titled Default",
+ "type": "string"
+ },
+ "count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 42,
+ "description": "PROBE_desc_field_count: integer with default",
+ "title": "Count"
+ },
+ "enabled": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": true,
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "title": "Enabled"
+ },
+ "price": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": 9.99,
+ "description": "PROBE_desc_field_price: number with default",
+ "title": "Price"
+ },
+ "released_on": {
+ "anyOf": [
+ {
+ "format": "date",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "title": "Released On"
+ },
+ "launched_at": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "2026-01-15T12:30:00",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "title": "Launched At"
+ },
+ "daily_at": {
+ "anyOf": [
+ {
+ "format": "time",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "12:30:00",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "title": "Daily At"
+ },
+ "tags": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "title": "Tags"
+ },
+ "ratings": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "title": "Ratings"
+ },
+ "matrix": {
+ "anyOf": [
+ {
+ "items": {
+ "items": {},
+ "type": "array"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "title": "Matrix"
+ },
+ "gadgets": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "title": "Gadgets"
+ },
+ "attributes": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "title": "Attributes"
+ },
+ "scores": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": {
+ "speed": 5
+ },
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "title": "Scores"
+ },
+ "milestones": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "format": "date",
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "title": "Milestones"
+ },
+ "main_gadget": {
+ "$ref": "#/$defs/input_semantics_probe__Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field"
+ },
+ "icon": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ImageContent"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_icon: native concept field"
+ },
+ "tone": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": "PROBE_choice_casual",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "title": "Tone"
+ },
+ "only_choice": {
+ "anyOf": [
+ {
+ "const": "PROBE_choice_single",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "title": "Only Choice"
+ },
+ "typed_choice": {
+ "anyOf": [
+ {
+ "enum": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "title": "Typed Choice"
+ },
+ "constrained_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "title": "Constrained Count"
+ }
+ },
+ "required": [
+ "shorthand_note",
+ "title",
+ "main_gadget"
+ ],
+ "title": "input_semantics_probe__Widget",
+ "type": "object"
+ }
+ }
+ },
+ "two": {
+ "concept_ref": "input_semantics_probe.Gadget",
+ "optional": false,
+ "json_schema": {
+ "type": "array",
+ "items": {
+ "$defs": {
+ "input_semantics_probe__Trinket": {
+ "description": "PROBE_desc_concept_Trinket: leaf structure for two-level nesting",
+ "properties": {
+ "label": {
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "title": "Label",
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "title": "input_semantics_probe__Trinket",
+ "type": "object"
+ }
+ },
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "properties": {
+ "name": {
+ "description": "PROBE_desc_field_gadget_name",
+ "title": "Name",
+ "type": "string"
+ },
+ "trinket": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/input_semantics_probe__Trinket"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "title": "input_semantics_probe__Gadget",
+ "type": "object"
+ }
+ }
+ },
+ "forced": {
+ "concept_ref": "native.Text",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ }
+ },
+ "output": {
+ "concept_ref": "native.Text",
+ "multiplicity": "single",
+ "optional": false
+ }
+ },
+ "input_semantics_probe.probe_refined": {
+ "inputs": {
+ "refdoc": {
+ "concept_ref": "input_semantics_probe.RefinedDoc",
+ "optional": false,
+ "json_schema": {
+ "description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
+ "properties": {
+ "url": {
+ "description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
+ "title": "Url",
+ "type": "string"
+ },
+ "public_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The public HTTPS URL of the document",
+ "title": "Public Url"
+ },
+ "mime_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The MIME type of the document",
+ "title": "Mime Type"
+ },
+ "filename": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The original filename of the document",
+ "title": "Filename"
+ },
+ "title": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The title of the document or source",
+ "title": "Title"
+ },
+ "snippet": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A text snippet or excerpt from the document",
+ "title": "Snippet"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "title": "input_semantics_probe__RefinedDoc",
+ "type": "object"
+ }
+ },
+ "special": {
+ "concept_ref": "input_semantics_probe.SpecialEntity",
+ "optional": false,
+ "json_schema": {
+ "description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__SpecialEntity",
+ "type": "object"
+ }
+ },
+ "extra": {
+ "concept_ref": "input_semantics_probe.ExtraSpecialEntity",
+ "optional": false,
+ "json_schema": {
+ "description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
+ "properties": {
+ "ident": {
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "title": "Ident",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ident"
+ ],
+ "title": "input_semantics_probe__ExtraSpecialEntity",
+ "type": "object"
+ }
+ },
+ "classbacked": {
+ "concept_ref": "input_semantics_probe.ClassBacked",
+ "optional": false,
+ "json_schema": {
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "TextContent",
+ "type": "object"
+ }
+ },
+ "stringnote": {
+ "concept_ref": "input_semantics_probe.StringNote",
+ "optional": false,
+ "json_schema": {
+ "description": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
+ "properties": {
+ "text": {
+ "description": "The text",
+ "title": "Text",
+ "type": "string"
+ }
+ },
+ "required": [
+ "text"
+ ],
+ "title": "input_semantics_probe__StringNote",
+ "type": "object"
+ }
+ }
+ },
+ "output": {
+ "concept_ref": "native.Text",
+ "multiplicity": "single",
+ "optional": false
+ }
+ }
+}
diff --git a/wip/input-semantics/probe/trace_manifest.json b/wip/input-semantics/probe/trace_manifest.json
new file mode 100644
index 000000000..8faed807f
--- /dev/null
+++ b/wip/input-semantics/probe/trace_manifest.json
@@ -0,0 +1,255 @@
+{
+ "bundle_paths": [
+ "tests/data/input_semantics/probe_bundle.mthds"
+ ],
+ "hop1_bundle_blueprints": "hop1_bundle_blueprints.json",
+ "hop2_generated_sources": {
+ "input_semantics_probe.StringNote": "hop2_generated_sources/input_semantics_probe.StringNote.py.txt",
+ "input_semantics_probe.Trinket": "hop2_generated_sources/input_semantics_probe.Trinket.py.txt",
+ "input_semantics_probe.Gadget": "hop2_generated_sources/input_semantics_probe.Gadget.py.txt",
+ "input_semantics_probe.Widget": "hop2_generated_sources/input_semantics_probe.Widget.py.txt",
+ "input_semantics_probe.PlainNote": "hop2_generated_sources/input_semantics_probe.PlainNote.py.txt",
+ "input_semantics_probe.RefinedDoc": "hop2_generated_sources/input_semantics_probe.RefinedDoc.py.txt",
+ "input_semantics_probe.BaseEntity": "hop2_generated_sources/input_semantics_probe.BaseEntity.py.txt",
+ "input_semantics_probe.SpecialEntity": "hop2_generated_sources/input_semantics_probe.SpecialEntity.py.txt",
+ "input_semantics_probe.ExtraSpecialEntity": "hop2_generated_sources/input_semantics_probe.ExtraSpecialEntity.py.txt",
+ "input_semantics_probe.ClassBacked": null
+ },
+ "hop3_raw_pydantic_schemas": {
+ "input_semantics_probe.StringNote": "hop3_raw_pydantic_schemas/input_semantics_probe.StringNote.json",
+ "input_semantics_probe.Trinket": "hop3_raw_pydantic_schemas/input_semantics_probe.Trinket.json",
+ "input_semantics_probe.Gadget": "hop3_raw_pydantic_schemas/input_semantics_probe.Gadget.json",
+ "input_semantics_probe.Widget": "hop3_raw_pydantic_schemas/input_semantics_probe.Widget.json",
+ "input_semantics_probe.PlainNote": "hop3_raw_pydantic_schemas/input_semantics_probe.PlainNote.json",
+ "input_semantics_probe.RefinedDoc": "hop3_raw_pydantic_schemas/input_semantics_probe.RefinedDoc.json",
+ "input_semantics_probe.BaseEntity": "hop3_raw_pydantic_schemas/input_semantics_probe.BaseEntity.json",
+ "input_semantics_probe.SpecialEntity": "hop3_raw_pydantic_schemas/input_semantics_probe.SpecialEntity.json",
+ "input_semantics_probe.ExtraSpecialEntity": "hop3_raw_pydantic_schemas/input_semantics_probe.ExtraSpecialEntity.json",
+ "input_semantics_probe.ClassBacked": "hop3_raw_pydantic_schemas/input_semantics_probe.ClassBacked.json",
+ "native.Text": "hop3_raw_pydantic_schemas/native.Text.json",
+ "native.Image": "hop3_raw_pydantic_schemas/native.Image.json",
+ "native.Document": "hop3_raw_pydantic_schemas/native.Document.json",
+ "native.Page": "hop3_raw_pydantic_schemas/native.Page.json",
+ "native.Number": "hop3_raw_pydantic_schemas/native.Number.json",
+ "native.Date": "hop3_raw_pydantic_schemas/native.Date.json",
+ "native.Time": "hop3_raw_pydantic_schemas/native.Time.json",
+ "native.Html": "hop3_raw_pydantic_schemas/native.Html.json",
+ "native.YesNo": "hop3_raw_pydantic_schemas/native.YesNo.json"
+ },
+ "hop3_skipped": [],
+ "hop4_schema_renders": {
+ "input_semantics_probe.probe_single.widget": "hop4_schema_renders/input_semantics_probe.probe_single__widget.json",
+ "input_semantics_probe.probe_single.gadget_q": "hop4_schema_renders/input_semantics_probe.probe_single__gadget_q.json",
+ "input_semantics_probe.probe_single.note": "hop4_schema_renders/input_semantics_probe.probe_single__note.json",
+ "input_semantics_probe.probe_native_inputs.text_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__text_in.json",
+ "input_semantics_probe.probe_native_inputs.image_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__image_in.json",
+ "input_semantics_probe.probe_native_inputs.document_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__document_in.json",
+ "input_semantics_probe.probe_native_inputs.page_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__page_in.json",
+ "input_semantics_probe.probe_native_inputs.number_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__number_in.json",
+ "input_semantics_probe.probe_native_inputs.date_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__date_in.json",
+ "input_semantics_probe.probe_native_inputs.time_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__time_in.json",
+ "input_semantics_probe.probe_native_inputs.html_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__html_in.json",
+ "input_semantics_probe.probe_native_inputs.yesno_in": "hop4_schema_renders/input_semantics_probe.probe_native_inputs__yesno_in.json",
+ "input_semantics_probe.probe_markers.opt": "hop4_schema_renders/input_semantics_probe.probe_markers__opt.json",
+ "input_semantics_probe.probe_markers.many": "hop4_schema_renders/input_semantics_probe.probe_markers__many.json",
+ "input_semantics_probe.probe_markers.two": "hop4_schema_renders/input_semantics_probe.probe_markers__two.json",
+ "input_semantics_probe.probe_markers.forced": "hop4_schema_renders/input_semantics_probe.probe_markers__forced.json",
+ "input_semantics_probe.probe_refined.refdoc": "hop4_schema_renders/input_semantics_probe.probe_refined__refdoc.json",
+ "input_semantics_probe.probe_refined.special": "hop4_schema_renders/input_semantics_probe.probe_refined__special.json",
+ "input_semantics_probe.probe_refined.extra": "hop4_schema_renders/input_semantics_probe.probe_refined__extra.json",
+ "input_semantics_probe.probe_refined.classbacked": "hop4_schema_renders/input_semantics_probe.probe_refined__classbacked.json",
+ "input_semantics_probe.probe_refined.stringnote": "hop4_schema_renders/input_semantics_probe.probe_refined__stringnote.json"
+ },
+ "hop5_pipe_io_contracts": "hop5_pipe_io_contracts.json",
+ "wire_framing": [
+ {
+ "pipe_ref": "input_semantics_probe.probe_single",
+ "input_name": "widget",
+ "authored_spec": "Widget",
+ "concept_ref": "input_semantics_probe.Widget",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_single",
+ "input_name": "gadget_q",
+ "authored_spec": "input_semantics_probe.Gadget",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_single",
+ "input_name": "note",
+ "authored_spec": "PlainNote",
+ "concept_ref": "input_semantics_probe.PlainNote",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "text_in",
+ "authored_spec": "Text",
+ "concept_ref": "native.Text",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "image_in",
+ "authored_spec": "Image",
+ "concept_ref": "native.Image",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "document_in",
+ "authored_spec": "Document",
+ "concept_ref": "native.Document",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "page_in",
+ "authored_spec": "Page",
+ "concept_ref": "native.Page",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "number_in",
+ "authored_spec": "Number",
+ "concept_ref": "native.Number",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "date_in",
+ "authored_spec": "Date",
+ "concept_ref": "native.Date",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "time_in",
+ "authored_spec": "Time",
+ "concept_ref": "native.Time",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "html_in",
+ "authored_spec": "Html",
+ "concept_ref": "native.Html",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_native_inputs",
+ "input_name": "yesno_in",
+ "authored_spec": "YesNo",
+ "concept_ref": "native.YesNo",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_markers",
+ "input_name": "opt",
+ "authored_spec": "Widget?",
+ "concept_ref": "input_semantics_probe.Widget",
+ "multiplicity": null,
+ "presence": "optional",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_markers",
+ "input_name": "many",
+ "authored_spec": "Widget[]",
+ "concept_ref": "input_semantics_probe.Widget",
+ "multiplicity": true,
+ "presence": "plain",
+ "is_multiple": true
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_markers",
+ "input_name": "two",
+ "authored_spec": "Gadget[2]",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "multiplicity": 2,
+ "presence": "plain",
+ "is_multiple": true
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_markers",
+ "input_name": "forced",
+ "authored_spec": "Text!",
+ "concept_ref": "native.Text",
+ "multiplicity": null,
+ "presence": "force",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_refined",
+ "input_name": "refdoc",
+ "authored_spec": "RefinedDoc",
+ "concept_ref": "input_semantics_probe.RefinedDoc",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_refined",
+ "input_name": "special",
+ "authored_spec": "SpecialEntity",
+ "concept_ref": "input_semantics_probe.SpecialEntity",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_refined",
+ "input_name": "extra",
+ "authored_spec": "ExtraSpecialEntity",
+ "concept_ref": "input_semantics_probe.ExtraSpecialEntity",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_refined",
+ "input_name": "classbacked",
+ "authored_spec": "ClassBacked",
+ "concept_ref": "input_semantics_probe.ClassBacked",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ },
+ {
+ "pipe_ref": "input_semantics_probe.probe_refined",
+ "input_name": "stringnote",
+ "authored_spec": "StringNote",
+ "concept_ref": "input_semantics_probe.StringNote",
+ "multiplicity": null,
+ "presence": "plain",
+ "is_multiple": false
+ }
+ ]
+}
diff --git a/wip/input-semantics/s1-audit-plan-DONE.md b/wip/input-semantics/s1-audit-plan-DONE.md
new file mode 100644
index 000000000..1e2e80040
--- /dev/null
+++ b/wip/input-semantics/s1-audit-plan-DONE.md
@@ -0,0 +1,95 @@
+# S1 — The input-semantics audit: plan (✅ done — S1 closed 2026-08-21)
+
+**Status:** ✅ **Done.** Every phase below is complete and both checkpoints were reached; the milestone closed on 2026-08-21 with the deliverable in [`findings.md`](findings.md). This file is kept as the as-built record of how the audit was run — plan written 2026-08-21, companion to [`audit.md`](audit.md) (the brief — read it first; this document schedules the audit, it does not re-argue it). Progress is tracked here with checkboxes. The deliverable is `findings.md`, written beside this file when Phase 4 completes. Per the brief: audit only — no fixes, no descriptor design, no wire changes.
+
+## The method, in one sentence
+
+Author a probe bundle that exercises every construct the language accepts, capture what each hop of the emission chain does to every authored fact, and let the diff — not the code — say what survives to the wire.
+
+## The harness is a keeper, not a scratch script
+
+Decision (Louis, 2026-08-21): the capture harness is built as a durable internal tool, not throwaway scaffolding. It lands as a `pipelex-dev` command (home: `pipelex/cli/dev_cli/commands/`, like `generate-mthds-schema` and friends) — call it `trace-input-semantics`: given a bundle, it dumps one artifact per hop of the chain below into an output directory. The probe bundle rides along as a committed fixture the audit (and any future re-run) points the tool at. Scope discipline: build exactly what this audit needs — per-hop captures for a given bundle — and nothing more generic; if another project needs more, it evolves the tool then. When the audit closes, the tool stays, with a short entry in the repo docs so it is findable. The survival *table* stays audit-side (built from the captures), so the tool stays a tracer, not a report generator.
+
+## The chain under audit
+
+Five hops, end to end in this repo. Every probe capture happens at each hop so a lost fact is localized to exactly one:
+
+1. **Parse:** `.mthds` structure syntax → `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`; the parser that builds it lives in `pipelex/mthds_parsing/` — exact site pinned in Phase 0).
+2. **Resolve + generate:** blueprint → generated structure class source (`pipelex/core/concepts/resolved_fields.py` → `pipelex/core/concepts/structure_generation/generator.py`, which threads `description` and `default_value` into the emitted `Field(...)` and renders `choices` as a `Literal`).
+3. **Schema:** generated class → `model_json_schema()` via the SCHEMA representation (`pipelex/core/concepts/concept_representation_generator.py`, `ConceptRepresentationFormat.SCHEMA`) — including whatever wrapping or stripping that render path applies after pydantic.
+4. **Contract:** schema → `PipeInputContract { concept_ref, optional, json_schema }` in `build_pipe_io_contracts` (`pipelex/pipeline/pipe_io_contracts.py`) — note the memo key is `(concept_ref, is_multiple())`, so multiplicity changes the rendered schema.
+5. **Wire framing:** what the pipe's `inputs = { … }` declaration itself contributes — concept ref, `?` optional, `[]` multiplicity — and nothing else.
+
+## Facts to verify by measurement, not settle by reading
+
+Candidates gathered from the brief and a first pass over the chain code. Each is a question the survival table must answer; none is a conclusion yet:
+
+- Does a field's `description` survive to the schema property's `description`?
+- Does the *concept's* own description become the schema's top-level `description` (it is emitted as the generated class docstring — does pydantic carry a docstring into the schema, and does the SCHEMA render keep it)?
+- Does `default_value` appear as the schema's `default` — for every type it can be authored on (text, integer, boolean, number, date, datetime, time, list, dict, choice)?
+- Do `date` / `datetime` / `time` fields emit their JSON-Schema `format`?
+- Does `choices` arrive as `enum` — and what does a single-entry choice list become (pydantic renders one-member `Literal` as `const`)?
+- What does a non-`required` field look like on the wire — `anyOf: [X, null]` plus `default: null`? This is the shape behind the app's flatten-then-repair round trip; the audit should state it precisely.
+- What survives of a **concept-typed field** (`type = "concept"`): does the nested structure inline via `$defs`, what are the `$defs` keys, and is the nested concept's *identity* (its concept ref) recoverable from the schema or only its shape?
+- What survives of **`refines`**: does the refinement chain (e.g. a refinement of `native.Document`) leave any trace in the emitted schema beyond inherited fields?
+- What do **native concepts as direct inputs** render as — `Text`, `Image`, `Document`, `PDF`, `Page`, and friends — and is anything in those schemas concept-identifying beyond the top-level `concept_ref`?
+- How does `[]` multiplicity change the emitted `json_schema` (array wrapping? at which hop?), given the memo keys on `is_multiple()`?
+- Do the dict constraints (`key_type` restricted to text, `value_type`) render faithfully (`additionalProperties`)?
+- Does anything in the SCHEMA render path strip or rewrite what pydantic emitted (title, `$defs`, metadata fields)?
+
+## Phase 0 — Rig the audit
+
+- [x] Read the direction doc and the roadmap (`../wip/devx/input-form-projection.md`, `../wip/devx/input-form-roadmap.md`) and the chain files named above.
+- [x] Pin the parse hop: TOML structure syntax lands on `PipelexBundleBlueprint.concept: dict[str, ConceptBlueprint | str]` (`pipelex/mthds_parsing/pipelex_bundle_blueprint.py:100`); a concept's `structure` is `str | dict[str, str | ConceptStructureBlueprint]` (`pipelex/core/concepts/concept_blueprint.py:18`), and the shorthand string field normalizes to a required text field in `normalize_structure_blueprint` (`pipelex/core/concepts/helpers.py:70`). The full per-field ceiling is `ConceptStructureBlueprint`'s field list (`concept_structure_blueprint.py:50-64`); the five declaration shapes are `ConceptDeclarationType` (`concept_factory.py:47-86`). ⚠ `ConceptStructureBlueprint` does NOT forbid extras — unknown keys on a field are silently dropped at parse.
+- [x] Pin the schema hop: `StuffSpec.render_stuff_spec` (`pipelex/core/pipes/stuff_spec/stuff_spec.py:42`) → `Concept.render_concept_representation` → `_render_schema_representation` (`pipelex/core/concepts/concept.py:193-214`): raw `model_json_schema()`, wrapped `{type: array, items: …}` when `is_multiple()`, inside a `{"concept", "content"}` envelope — no other transform, measured byte-identical hop 3 → hop 5.
+- [x] Build the capture harness as the `pipelex-dev trace-input-semantics` command: `pipelex/cli/dev_cli/commands/trace_input_semantics_cmd.py`, registered in `_dev_cli.py`. Dumps hop1 blueprint JSON, hop2 regenerated class sources (as `.py.txt` so captures stay inert to linters), hop3 raw pydantic schemas, hop4 SCHEMA renders per pipe input, hop5 contracts, plus `trace_manifest.json` with per-input wire framing (authored spec string, resolved ref, multiplicity, presence). Tests: `tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py` (per-hop assertions on a small bundle + a run over the committed probe).
+- [x] Probe matrix enumerated from the parsing layer and encoded directly in the probe bundle (see Phase 1).
+
+## Phase 1 — The probe bundle
+
+- [x] Probe bundle authored at `tests/data/input_semantics/probe_bundle.mthds` with `PROBE_` sentinels on every authored fact: all field types, choices (multi/single/typed), defaults on every type that allows one, required both ways and required+default together, shorthand fields, dicts (text/number/date values), lists (scalar/concept/nested), two-level concept nesting, a native concept field, refines of a native and a two-link custom chain, class-backed structure, string/basic concept declarations, and pipes covering `?`, `[]`, `[2]`, `!`, bare vs qualified refs, and native concepts as direct inputs.
+- [x] The bundle validates cleanly (pinned by a test). Rejected constructs live in `tests/data/input_semantics/rejected/*.mthds_invalid` (repo convention for deliberately-invalid fixtures): default on a concept field, non-string choices, per-input-slot description, refines+structure, multiple refines — each refusal verified against the real validator.
+
+## Phase 2 — Measure
+
+- [x] Trace run on the probe bundle; captures under `wip/input-semantics/probe/`. Regenerate with `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`.
+- [x] Survival table written at [`survival-table.md`](survival-table.md): one row per authored fact, per-hop verdicts, plus the rejected-constructs ceiling evidence and the measurement surprises.
+
+**Checkpoint CP1 — measurements in hand. ✅ Reached 2026-08-21.** The probe bundle, harness, and survival table exist; classification (Phase 3) has not started. Surprises the measurement produced, so the next session classifies without re-running anything:
+
+- **Unknown keys on a structure field are silently dropped at parse** (`ConceptStructureBlueprint` has no `extra="forbid"`): `minimum`/`maximum`/`examples`/`unit` authored fine, validated green, and were absent from the hop-1 blueprint dump. The MTHDS lint hook's generated schema flags some of these, the runtime never does.
+- **`required = true` plus `default_value` drops the required-ness at hop 2**: the generator emits `default=…` instead of `...` (`generator.py:308-311`), so the field leaves pydantic's `required` list.
+- **`[N]` fixed count dies at the render**: `stuff_spec.is_multiple()` collapses multiplicity to a bool before rendering, so `Gadget[2]` emits a plain `array` with no `minItems`/`maxItems`; the contract memo key `(concept_ref, is_multiple())` (`pipe_io_contracts.py:104`) makes the count structurally unreachable there.
+- **`!` force marker dies at the contract**: `optional=presence.is_optional` (`pipe_io_contracts.py:123`) maps force and plain to the same `optional: false`.
+- **Hop 3 → hop 5 is lossless** (measured equality of the widget schema at both hops): every gap is upstream — language, blueprint, or generator — never the render or contract plumbing.
+- **Class-backed concepts (`structure = "ClassName"`) lose their concept description entirely**: the pre-existing class carries no docstring from the concept, so the schema has no top-level `description` (measured on `ClassBacked` → `TextContent`).
+- **The stale check-mthds hook schema false-positives on `structure = "TextContent"`** (known issue — trust `make plxt-lint` / the real validator).
+- Sigil constraint worth knowing when authoring probes: `@var` must sit alone on its own line in prompts; inline use is a validation error (use `$var` inline).
+
+## Phase 3 — Classify and place the wrinkles
+
+- [x] Mark every gap **engine-side** or **language-side** using the brief's test: could a `.mthds` author write it today, in any syntax the parser accepts? Evidence as `path/file.py:line` for every engine-side claim. Result: ten engine-side entries (E1–E10 in `findings.md` §A), each a closable work item.
+- [x] Confirm and complete the language-side ceiling from the Phase 0 parser findings — thirteen entries (`findings.md` §B), including three the brief missed: choice labels, inner types of nested lists, and refine-and-extend (`refines` XOR `structure` means a refinement can never add fields, `concept_blueprint.py:95`).
+- [x] Catalogue the engine-authored descriptions on the native content classes (`findings.md` §D). The known contract-in-disguise was verified read-only in `pipelex-app` — and found *already half-drifted*: the app's matcher checks `"pipelex storage url"` and `"document url"`, but the current `DocumentContent.url` wording ("a storage URI") only matches the second. Two more contract families surfaced: `DocumentContent`'s field *names* (a value-sniff set in the app) and `TextContent`'s `{text}` wrapper shape.
+- [x] Settle the two meaning questions (`findings.md` §C). `default_value` is an execution-level default applied on absence at the one input-ingestion seam (`stuff_content_factory.py:35`) and for LLM structured output; the inputs template deliberately omits defaulted fields; dry-run mocks ignore defaults. `required` (payload-level, travels inside the schema) and `?` (slot-level, travels as the contract flag) never interact; `!` is a use-site assertion flattened into plain at the contract.
+- [x] Fill the downstream column — every one of the direction doc's four workaround families pinned to file:line in `pipelex-app`, plus finds the direction doc missed: `const` (single-entry choices) unhandled anywhere in the app, multiplicity rebuilt from `type: "array"` in three independent places (one documented gating bug), and the pydantic `title` discarded/overwritten because it is the class name.
+
+## Phase 4 — Write the findings and close the milestone
+
+- [x] `findings.md` written beside this file: the two lists with *where authored* / *where lost* / *who guesses today* per entry, one sentence of recommendation each, no design sections.
+- [x] Engine-side list phrased as S2 work items with a ranking section (§E, worked-around gaps first); language-side list written repo-context-free for Track H.
+- [x] Native-description catalogue (§D) and the two meaning answers (§C) placed as their own sections.
+
+**Checkpoint CP2 — milestone gate. ✅ Reached 2026-08-21, S1 closed.**
+
+- [x] Tool kept and documented: `docs/contribute/trace-input-semantics.md` (in both mkdocs navs), a `trace-input-semantics` bullet in the kit agent-rules templates (`commands.md` / `codex_commands.md`, regenerated via `make rules`), and a changelog entry under Unreleased.
+- [x] Plan checkboxes updated; decisions and surprises recorded below.
+- [x] `../wip/devx/input-form-roadmap.md` updated per its checkpoint protocol — S1 marked closed with what D1, S2, H1, and K1/M1 each need from the findings.
+
+**Decisions taken and surprises found in Phases 3–4** (beyond the CP1 list, which still stands):
+
+- **A live authoring-path data-loss bug surfaced during the `default_value` trace** (findings E8): the builder's TOML writer emits the key `default` instead of `default_value` (`pipelex/builder/operations/concept_ops.py:115-116`), and because `ConceptStructureBlueprint` ignores extras, a builder-emitted default validates green and evaporates on re-load. Per the brief, not fixed here — it is on the S2 list, and E7's `extra="forbid"` would have caught it.
+- **The app's description-substring contract has already half-broken in the wild**: the `"pipelex storage url"` branch of `document-url-widget.tsx:130-136` matches nothing against the current `DocumentContent.url` wording — the drift the brief warned about had already happened, silently. `ImageContent.url` matches neither substring, so image inputs never get the RJSF dropzone by that route.
+- **The parse-layer extras asymmetry is the ceiling's enforcement gap**: `ConceptBlueprint` forbids unknown keys, `ConceptStructureBlueprint` silently drops them — so almost the whole language-side ceiling fails silently at the field level. Classified engine-side (E7) because the silence, not the ceiling, is the engine's.
+- **Classification judgment call:** `[]` multiplicity was given an engine-side entry (E9) even though it "survives" as array wrapping, because the contract carries no structured multiplicity field and the app rebuilds it from schema shape in three places — the brief's who-guesses test decided it.
+- **Scope discipline held:** no fixes, no descriptor design; the only repo changes besides `wip/` documents are the tool docs, the kit-template bullets, and the changelog entry required by this gate.
diff --git a/wip/input-semantics/survival-table.md b/wip/input-semantics/survival-table.md
new file mode 100644
index 000000000..58502672f
--- /dev/null
+++ b/wip/input-semantics/survival-table.md
@@ -0,0 +1,73 @@
+# S1 — Survival table: what each authored input fact becomes at each hop
+
+**Status:** measured 2026-08-21 from the probe captures under [`probe/`](probe/) (regenerate with `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`). The probe bundle is the committed fixture `tests/data/input_semantics/probe_bundle.mthds`; the deliberately-rejected constructs live in `tests/data/input_semantics/rejected/` (extension `.mthds_invalid`, the repo convention that keeps them out of `plxt lint`). This table is evidence, not classification — Phase 3 marks each loss engine-side or language-side.
+
+## The hops
+
+1. **Parse** — `hop1_bundle_blueprints.json`: TOML → `PipelexBundleBlueprint` (`ConceptBlueprint` / `ConceptStructureBlueprint`).
+2. **Generate** — `hop2_generated_sources/`: blueprint → generated structure-class source (`StructureGenerator`).
+3. **Pydantic** — `hop3_raw_pydantic_schemas/`: generated class → raw `model_json_schema()`.
+4. **Render** — `hop4_schema_renders/`: the SCHEMA render per pipe input (`{"concept", "content"}` envelope; array wrap when multiple). Measured: for a single input, `content` is byte-identical to hop 3 — the render adds the envelope and the array wrap, nothing else.
+5. **Contract** — `hop5_pipe_io_contracts.json`: `PipeInputContract { concept_ref, optional, json_schema }` where `json_schema` is hop 4's `content` verbatim.
+
+## Structure-field facts
+
+| Authored fact | Hop 1 parse | Hop 2 generate | Hop 3 pydantic | Hop 4/5 wire | Verdict |
+|---|---|---|---|---|---|
+| Field `description` | survived | survived (`Field(description=…)`) | survived (property `description`) | survived | **survives** |
+| Concept's own `description` | survived | survived (class docstring) | survived (schema top-level `description`) | survived | **survives** (except class-backed concepts, below) |
+| `required = true` | survived | survived (`Field(...)`, no `\| None`) | survived (in `required`, no null arm) | survived | **survives** |
+| `required` omitted / `false` (table form) | survived (`required=False` default) | transformed: `X \| None` + `default=None` | `anyOf: [X, null]` + `default: null`, absent from `required` | survived | **survives, transformed** — this is the shape behind the app's flatten-then-repair round trip |
+| Shorthand string field (`field = "desc"`) | transformed: text + `required=True` | survived | survived | survived | **survives** (shorthand implies required text) |
+| `default_value` (text, integer, boolean, number) | survived | survived (`Field(default=…)`) | survived (`default`) | survived | **survives** |
+| `default_value` (date / datetime / time) | survived (TOML temporal literals parse to real `date`/`datetime`/`time`) | survived (`date.fromisoformat("…")` etc.) | survived (`default` as ISO string) | survived | **survives** |
+| `default_value` (list, dict) | survived | survived | survived | survived | **survives** |
+| `required = true` **and** `default_value` together | both survived on the blueprint | transformed: generator emits `default=…` and drops the `...` marker (`titled_default`) | field is **not** in `required` — the authored `required=true` is gone | same | **`required` dropped at hop 2** when a default is present |
+| `type = "date"` / `"datetime"` / `"time"` format | survived | survived (`date`/`datetime`/`time` annotations) | survived (`format: date` / `date-time` / `time`) | survived | **survives** |
+| `choices` (multi) | survived | transformed: `Literal[…]` | `enum: […]` with `type: string` | survived | **survives** |
+| `choices` single entry | survived | `Literal["x"]` | **`const: "x"`**, not `enum` | survived | **survives, shape shifts** — consumers must read both `enum` and `const` |
+| `type` + `choices` together | both survived on the blueprint | transformed: choices win, `type` ignored (`resolved_fields.py:124`) | as choices | survived | `type` is **redundant/dropped** when choices present |
+| `type = "dict"` with `key_type`/`value_type` | survived | `dict[str, X]` | `additionalProperties: {…value type…}`; `key_type` implicit (JSON keys are strings) | survived | **survives** (value type faithful, incl. `format` on `date` values) |
+| `type = "list"`, `item_type` scalar | survived | `list[X]` | `items: {…}` | survived | **survives** |
+| Nested list (`item_type = "list"`) | survived | `list[list[Any]]` with imprecision marker | `items: {items: {}}` — inner shape empty | survived | inner item type **not expressible** → empty schema |
+| `type = "concept"` field | survived (`concept_ref`) | forward ref to qualified class name | inlined via `$refs` into `$defs` keyed by the **class-name spelling** (`input_semantics_probe__Gadget`) | survived | shape survives; **concept identity (its ref) is not recoverable** — only the mangled class name |
+| List of concepts (`item_concept_ref`) | survived | `list["Domain__Code"]` | `items: {$ref: #/$defs/…}` | survived | same identity loss as above |
+| Native concept field (`concept_ref = "native.Image"`) | survived | import of `ImageContent` | `$defs.ImageContent` | survived | shape survives; identity only as the content-class name |
+| Two-level nesting (Widget → Gadget → Trinket) | survived | forward refs | both levels inlined into `$defs` | survived | **survives** structurally |
+| Unknown keys on a field (`minimum`, `maximum`, `examples`, `unit`) | **silently dropped at parse** — absent from the blueprint dump; validation passes | — | — | — | **dies at hop 1, silently** (`ConceptStructureBlueprint` has no `extra="forbid"`) |
+
+## Concept-declaration facts
+
+| Authored fact | Result on the wire | Verdict |
+|---|---|---|
+| Description-only concept (`PlainNote`), string-shorthand concept (`StringNote`) | generated `TextContent` subclass: schema is `{text: string}` with the concept description as top-level `description` | description **survives**; the implicit text-refinement is visible only as the `text` property |
+| `refines = "native.Document"` (`RefinedDoc`) | schema = `DocumentContent`'s fields, title is the refining class name, concept description on top | **the refinement link itself leaves no trace** in the schema — nothing says "this is a Document" except the inherited field shapes |
+| Custom refinement chain (`BaseEntity` ← `SpecialEntity` ← `ExtraSpecialEntity`) | each link's schema = inherited fields + own description; chain not represented | same: **`refines` dies between hop 2 and hop 3** (only inheritance side-effects survive) |
+| `structure = "TextContent"` (class-backed, `ClassBacked`) | schema is raw `TextContent`: `title: "TextContent"`, **no `description` at all** | **the concept's own description is dropped** — the pre-existing class has no docstring from the concept, so nothing carries it into the schema |
+| Native concepts as direct inputs (`Text`, `Image`, `Document`, `Page`, `Number`, `Date`, `Time`, `Html`, `YesNo`) | content-class schema (`title: "TextContent"` etc.); most have **no top-level description** (only `DateContent`/`TimeContent` docstrings survive); field descriptions are the engine-authored ones (e.g. `DocumentContent.url`: "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL") | concept identity beyond top-level `concept_ref` exists **only** in the `title` class-name spelling and shape-sniffable properties |
+
+## Pipe-input framing facts
+
+| Authored fact | Result on the wire | Verdict |
+|---|---|---|
+| Bare vs qualified concept ref (`Widget` vs `input_semantics_probe.Gadget`) | both resolve to the same qualified `concept_ref` on the contract | **survives, normalized** |
+| `?` optional marker | `optional: true` on the contract; the `json_schema` itself is unchanged | **survives** as a contract flag |
+| `[]` list marker | `json_schema` wrapped as `{type: array, items: <hop-3 schema>}` at the hop-4 render; contract memo keys on `is_multiple()` | **survives** as array wrapping |
+| `[N]` fixed count (`Gadget[2]`) | parsed to `multiplicity: 2` on the loaded spec, but the render only asks `is_multiple()` → plain `array` with **no `minItems`/`maxItems`** | **count dropped at hop 4** (`stuff_spec.py:58`, `concept.py:206-212`) |
+| `!` force marker | parsed to `presence: force`, but the contract reports `optional: false` — same as plain | **force/plain distinction dropped at hop 5** (`pipe_io_contracts.py:123`) |
+| Per-input-slot description | **cannot be authored** — `inputs` values are ref strings only (`pipe_blueprint.py:186`); the table form is rejected (see `rejected/per_input_description.mthds_invalid`) | language ceiling |
+
+## Constructs the language rejects (ceiling evidence, `rejected/`)
+
+- `default_value` on a `concept`-typed field — refused (`concept_structure_blueprint.py:111`).
+- Non-string `choices` (`[1, 2, 3]`) — refused (`choices: list[str]`, pydantic does not coerce).
+- A per-input description table in `inputs` — refused (`inputs: dict[str, str]`).
+- `refines` together with `structure` — refused (`concept_blueprint.py:95`).
+- Multiple `refines` (`["a", "b"]`) — refused (`refines: str | None`; the TODO at `concept_blueprint.py:19` records the restriction).
+
+## Measurement surprises worth carrying into Phase 3
+
+- **Unknown structure-field keys vanish silently at parse.** `ConceptStructureBlueprint` ignores extras (no `extra="forbid"`), so a hopeful `minimum = 0` authors fine, validates green, and reaches nothing. The stale-schema MTHDS hook is the only thing that even warns.
+- **`required` + `default_value` together: the default wins and the required-ness is dropped** by the generator's parameter ordering (`generator.py:308-311`).
+- **`is_multiple()` collapses `[N]` to a bare bool** before the render, so fixed counts can never reach `minItems`/`maxItems` without touching the memo key `(concept_ref, is_multiple())` in `pipe_io_contracts.py:104`.
+- **The SCHEMA render is otherwise lossless**: hop 3 → hop 5 is verbatim (measured equality), so every gap is upstream of the render — in the language, the blueprint, or the generator.