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 S2 (Enrich): loud authoring, enriched schemas, contract reshape (#1149)

Louis Choquel4bb97ec1f037
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02b34c752..2d4c2615e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,10 +8,18 @@
- **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`.
+- **Emitted JSON Schemas carry the concept's identity and authored description.** The SCHEMA render (pipe input contracts, `build output --format schema`, the trace harness) now injects the concept ref as the schema's top-level `title` — replacing the mangled generated-class name — and the concept's authored description as its top-level `description`, uniformly for generated, class-backed, and native concepts. A fixed-count input or output (`Concept[N]`) now emits `minItems`/`maxItems` = N on its array wrap, with real multiplicity threaded through the render seam instead of a boolean; a variable-length list (`Concept[]`) stays unbounded. Native content classes (`TextContent`, `ImageContent`, `DocumentContent`, `PageContent`, `NumberContent`, `HtmlContent`, `YesNoContent`) gained docstrings matching their pinned native descriptions, so provider-side schemas built straight from the classes carry them too.
+
- **`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
+- **`pipe_io_contracts` learns presence and real multiplicity (breaking protocol reshape).** Input contracts now carry `presence` (`plain` / `optional` / `force`) — the declared marker verbatim — replacing the two-valued `optional`, so lint and graph surfaces can see where `!` assertions live without a presentation view. Input and output contracts both carry a three-valued `multiplicity` (`single` / `variable` / `fixed`) with `item_count: int` present exactly when `fixed`, retiring the old ruling that deliberately reported a fixed count as `variable` (the input contract previously had no multiplicity field at all). The output contract keeps its two-valued `optional` (`!` is rejected on outputs). Spec-first: the MTHDS Protocol spec's `pipe_io_contracts` row and optionals section moved in the same change, and the reshaped conformance assertions are gated until the release cascade.
+
+- **A structure field can no longer declare both `required = true` and a `default_value` (breaking).** The two are contradictory instructions — a default's meaning is "applied when the caller omits the field", which makes absence legal — and the generator used to resolve the conflict silently by dropping the required-ness through parameter ordering. The pair is now rejected at blueprint validation — and at the builder's spec layer, so an authoring agent fails before emitting TOML the parser would reject — with a message naming both remedies, and the generator branch that tiebroke it is an explicit invariant that raises if ever reached. Relatedly, a pydantic default on a hand-written structure class now counts as an authored fact: the input-form descriptor reports such a field as `required: false` with its `default_value`, instead of claiming it required and hiding the default.
+
+- **Unknown keys in a structure-field table are now rejected (breaking).** A typo'd or hopeful key on a concept structure field (`minimum`, `unit`, a misspelled `hint`) used to be silently dropped at parse while the bundle validated green — silently discarded authored intent. `ConceptStructureBlueprint` now forbids unknown keys, making the field table's keys strict exactly like an input slot table's; hint *content* stays lenient (unknown hint keys still warn and are preserved). The MTHDS JSON Schema regenerates accordingly (structure-field objects carry `additionalProperties: false`), and hint-free crates keep byte-identical fingerprints.
+
- **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.
Two mechanical conversions ride along, both applied by `ruff check --fix` and therefore not deferrable — `make lint` would re-apply them on first contact. Selector lists in `pyproject.toml` now name rules rather than code them (`"implicit-namespace-package"` for `INP001`), which is what the config linter prefers and reads better besides; and `# noqa: CODE` suppressions became `# ruff: ignore[rule-name]`, explanations preserved. The new formatter also reformats Python code blocks inside Markdown, so the documentation picked up trailing-comment and blank-line normalization.
@@ -22,6 +30,8 @@
### Fixed
+- **Builder-authored defaults no longer evaporate on re-load.** The builder's TOML writer emitted the key `default` where the language reads `default_value`, so a default authored through the builder (or the agent-CLI `concept` command) validated green and then reached nothing when the file was re-loaded. The writer now emits `default_value`, a write-then-validate round-trip test pins the survival, and the new unknown-key rejection turns any recurrence of this bug class into a hard failure instead of silent loss.
+
- **`pipelex.providers.bedrock` imported a type-stub package at runtime.** `ConverseResponseTypeDef` was imported both at module level and inside the module's `if TYPE_CHECKING:` block. It resolves only through `types-aioboto3`, which is a development dependency, so the module-level copy would raise `ModuleNotFoundError` on any install of `pipelex[bedrock]` without the dev extras. The duplicate is gone and the surviving import is the type-checking one; the annotation it serves is a local variable annotation, which is never evaluated at runtime.
- **A usage example in `pipelex.test_extras.shared_pytest_plugins` had lost its `yield`.** The example fixture in `needs_inference_in_pipelex`'s docstring showed a teardown call with nothing handing control to the test first, its `yield` line having drifted into a literal `Yield:` docstring section on a function that only ever returns a `bool`. The example is a working fixture again.
diff --git a/TODOS.md b/TODOS.md
index 5078564eb..2554ab1e7 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,113 +1,107 @@
-# Engine intent hints (H2) — implementation tracker
+# S2 — Enrich: implementation tracker
-Working tracker for `wip/engine-hints/design.md` on branch `feature/Engine-hints`. Read the design doc first — it holds the rationale, the contract, and the file/line anchors; this file only tracks execution. Checkpoint protocol: at each checkpoint, update the design doc with decisions taken and deviations, verify cold-start readiness, and tick the checkpoint box here.
+Seeded from [`wip/enrich/design.md`](wip/enrich/design.md) §7 (the design stays authoritative for rationale; this file tracks live progress). Milestone branch: `feature/Enrich`.
-## Resume state (for a cold start)
+## Decisions ratified (Phase 0, 2026-08-23, by Louis)
-Phases 1 and 2 are landed and green through Checkpoint A (`make agent-check`, `make check`, `make test` all pass). Decisions taken so far that the design doc does not spell out:
+1. **E3 — reject the pair.** A structure field declaring both `required = true` and a `default_value` is a validation error (breaking; mthds spec sentence via inbox; the sole fixture instance moves to `rejected/`).
+2. **E5/E9 — replace, not add.** Input contract `presence: "plain" | "optional" | "force"` **replaces** `optional`; `multiplicity` goes three-valued (`single`/`variable`/`fixed`) with `item_count` exactly when `fixed`, on input and output contracts. Output keeps its two-valued `optional`. Breaking protocol change, spec-first, rides the release cascade.
+3. **Reflected defaults are authored facts.** A pydantic default on a reflected class field reports `required: false` + its `default_value` in the descriptor; `field_info.is_required()` is the single source of truth.
-- **Sorted-hints emission solved at the model, not the encoder:** the shared `normalize_empty_hints` validator on all three models sorts hints keys, so every dump (fingerprints, codegen crate encoding, wire) is canonical without any encoder walking.
-- **Effective hints in normalization:** `_RefinementResolution.effective_hints` is position-specific — the cache write-back walks `reversed(path)` accumulating each visited ref's own hints over what lies below it (`merge_hints`), so a memoized mid-chain resolution carries ITS position's hints (guard test mutation-verified: the naive shared write-back reds exactly that test). `_flatten_refinement` stamps `merge_hints([base_resolution.effective_hints, value.hints])` on BOTH arms — flattened and refines-keeping — and also on chains whose base has no structure to materialize.
-- Hinted fixtures: `tests/data/input_semantics/hinted_bundle.mthds` (all three sites, chain override + inheritance, unknown-key preservation, collapsing slot, marked slot); normalization fixtures in `tests/unit/pipelex/libraries/test_crate_normalization_hints.py`.
+## Phase 0 — ratify and sweep
-- **`PipeBlueprint.inputs` is `Mapping[str, str | InputSlotBlueprint] | None`, not `dict`** — value-covariant, so the many `dict[str, str]` construction sites (specs, tests) stay legal without casts. Rationale is a docstring on the field.
-- **Two access paths for consumers:** grammar-only consumers read the projection `PipeBlueprint.inputs_concept_specs` (or `slot_concept_spec(value)` per value); hints-aware consumers read `inputs` itself. Sites swept to the projection: `contract_match` (hints don't affect contract identity), `crate_normalization._collect_referenced_natives`, `pipe_factory` (both the concept-existence loop and the `InputStuffSpecsFactory` call — the design's "factory accepts the union" became a call-site projection, same invariant: runtime `StuffSpec` never sees hints), `pipe_llm_factory` + `pipe_img_gen_factory` template analyzers, `pipe_structure_blueprint`, `pipelex_bundle_blueprint._collect_local_refs_from_pipe`, `trace_input_semantics_cmd` (framing manifest carries the concept string; hints surface at hop 5), and all builder `*_spec.from_blueprint` sites (spec layer stays `dict[str, str]`; hints dropped there — builder emission is the known out-of-scope follow-up).
-- **Hints travel untouched through:** `crate_qualification` (new `_qualify_slot_value` qualifies the table arm's `concept`, hints pass through) and `bundle_elaborator` (copies `inputs` as-is, so PipeLLM→sequence elaboration keeps slot hints on the draft step and the wrapping sequence).
-- **Subject grants recorded** for `merge_hints`, `applicable_intent`, `is_intent_word_known`, `intent_word_applies`, `slot_concept_spec`, `_qualify_slot_value` (in `subject_grants.toml`).
-- The pinned fingerprints live in `tests/unit/pipelex/libraries/test_fingerprint_pins.py`, computed on the probe bundle BEFORE the fields landed — keep `tests/data/input_semantics/probe_bundle.mthds` hint-free forever; hinted fixtures go in sibling files.
+- [x] Decisions §6 confirmed by Louis (see above)
+- [x] Sweep at head: hopeful extra keys in structure-field tables across fixtures, corpus entries, and cookbook-adjacent test data (E7 fallout list)
+- [x] Sweep at head: `required = true` + `default_value` pairs across the same surfaces (E3 fallout list)
+- [x] Inventory captures that pin emitted schema bytes (codegen/validate parity corpora, conformance captures, characterization tests) so Phase 2 re-baselines are deliberate
+- [x] Record the fixture-fallout list for Phases 1–2 below
-Next actions, in order: finish Phase 1's remaining fixtures/tests (unchecked boxes below), then Phase 2's effective-hints merge in normalization.
+### Phase 0 findings
-## Phase 1 — Language surface
+- **Structure-field sweep (2026-08-23, at head of `feature/Enrich`):** parsed every `.mthds`/concept-bearing `.toml` under this worktree, `pipelex-cookbook`, and `pipelex-starter-python`. The ONLY unknown-key carrier is the probe bundle's `constrained_count` (`tests/data/input_semantics/probe_bundle.mthds:61` — extras `minimum`, `maximum`, `examples`, `unit`), and the ONLY `required`+`default_value` pair is the probe bundle's `titled_default` (`probe_bundle.mthds:30`). No fallout anywhere else; both fields are handled by the design's own plan (extras: E7 flip keeps them as deliberate rejected-case material; `titled_default` moves to a `rejected/` fixture in Phase 4).
+- **Schema-byte capture inventory (very thorough sweep):** NOTHING under `tests/` pins schema bytes — every schema assertion is key-presence or single-value, so Phase 2's render changes are test-green without re-baselining (no snapshot framework exists in the repo). The only committed full-schema payloads are the S1 audit captures under `wip/input-semantics/probe/` (hop3 raw schemas, hop4 renders, hop5 contracts), re-baselined by one command: `.venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o wip/input-semantics/probe`. Hand edits Phase 2 owes: `docs/tools/cli/build/output.md:161-239` (its example `--format schema` output shows the class-name `title`, no top-level `description`, and a `MyType[5]` array with no `minItems`/`maxItems` — falsified by all three enrichments). Digest surfaces checked (migration fingerprints, crate fingerprints, codegen stamps): none hashes rendered schema. Conformance (sibling repo) pins nothing schema-byte-wise; it becomes relevant only at Phase 3. Natural home for new seam unit tests: `tests/unit/pipelex/core/concepts/test_concept_representation_generator.py`; for integration assertions: `tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py`.
-### Shared hints module
+## Phase 1 — loudness (E7, E8)
-- [x] Create `pipelex/language/intent_hints.py`: `INTENT_HINT_KEY = "intent"`, the closed vocabulary (`prose`, `label`, `rating`, `quantity`), pinned per standard version like the native concept definitions.
-- [x] Implement `merge_hints(layers)` — key-by-key, later (nearer) layer wins, empty result is `None`. This is the ONE precedence implementation; normalizer and deriver both call it.
-- [x] Implement the applicability predicates (text-valued / number-valued site judgment per the spec's Applicability section; description-only concepts are text-valued; plural sites judged per item) and `applicable_intent(hints, *, site) -> str | None`.
-- [x] Unit tests for the module: merge precedence, empty-merge → `None`, applicability over each site shape, `applicable_intent` returns only known-and-applicable words.
+- [x] E7: `extra="forbid"` on `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`) — field-table *keys* strict; hint *content* stays lenient (unknown hint keys still warn + preserve)
+- [x] E8: builder writes `default_value`, not `default` (`pipelex/builder/operations/concept_ops.py`)
+- [x] E8: write-then-validate round-trip test for builder-authored defaults (`tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py` — two existing assertions had pinned the buggy `default` key and were fixed too)
+- [x] Regenerate `mthds_schema.json` — `ConceptStructureBlueprint` now carries `additionalProperties: false` (schema is generated + gitignored; downstream copies sync at release per the filed inbox item)
+- [x] Apply Phase 0 fixture fallout: probe bundle's `constrained_count` lost its hopeful extras (its description string kept byte-identical — it is hashed by the fingerprint pins); the extras live on in the new `tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid`
+- [x] Unit tests: forbid rejection + hint leniency (`tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py`)
+- [x] H2 fingerprint invariant check: `test_fingerprint_pins.py` green with UNCHANGED pins
+- [x] Changelog (Unreleased): E7 breaking (Changed) + E8 fix (Fixed)
+- [x] Deliver + remove inbox item `../wip/inbox/2026-08-21-pipelex-builder-default-key-dropped.md` (deleted; fix, round trip, and forbid all delivered)
-### Pinned-fingerprint regression (land BEFORE the model changes)
+**Checkpoint 1** — authoring loop honest, nothing wire-visible changed yet.
-- [x] Compute the normalized fingerprint of a committed hint-free fixture bundle against the unchanged models, hardcode the hex in a regression test, and commit it first — the suite must prove existing digests do not move when the fields land.
+- [x] Checkpoint 1: tracker updated, `make agent-check` green, targeted tests green (concepts + builder + fingerprint pins + input-form integration)
-### The three parse sites
+### Checkpoint 1 state (for cold start)
-- [x] `ConceptBlueprint` (`pipelex/core/concepts/concept_blueprint.py`): add `hints: dict[str, str] | None = None` (`extra="forbid"` already in force — strict shape for free).
-- [x] `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py`): add the same field. Do NOT change the extras policy — the E7 `extra="forbid"` fix stays in S2's strictness sweep (design Part 1b).
-- [x] New `InputSlotBlueprint(BaseModel)` with `extra="forbid"` and exactly two fields: `concept: str` (full existing slot grammar) and `hints: dict[str, str] | None = None`.
-- [x] Widen `PipeBlueprint.inputs` to `dict[str, str | InputSlotBlueprint] | None` (`pipelex/pipe_machinery/pipe_blueprint.py`); check the union assembly in `pipelex/mthds_parsing/pipelex_bundle_blueprint.py` propagates to every `Pipe*Blueprint` subclass.
-- [x] Extend `generic_validate_inputs` (`pipe_blueprint.py`) to validate the table arm's `concept` with the same ref+multiplicity+presence grammar as the string arm — one grammar, two spellings.
-- [x] Implement the parse-time collapse rule at model validation: a slot table with absent or empty `hints` collapses to its plain string, so hint-free bundles produce byte-identical blueprints by construction.
-- [x] Empty-table removal on concept/field models too (validator normalizing `hints = {}` to `None`) so the crate never holds an empty hints table.
+Decisions all ratified (§ above). Phase 1 delivered E7+E8 entirely inside: `concept_structure_blueprint.py` (forbid), `concept_ops.py` (key fix), probe bundle + new rejected fixture, three test modules touched. Note for Phase 4: removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `tests/unit/pipelex/libraries/test_fingerprint_pins.py` — that is a legitimate fixture-content change, not a model leak; the pins must be recomputed then, against the test docstring's usual advice, or the pin test moved onto a stable fixture. The check-mthds PostToolUse hook flags the probe bundle with a stale bundled schema — `plxt lint` with the regenerated `derived/mthds_schema.json` is the authority and passes.
-### Serialization — fingerprint neutrality
+## Phase 2 — schema enrichment (E6, E1-title, E4)
-- [x] Add a `@model_serializer(mode="wrap")` to `ConceptBlueprint`, `ConceptStructureBlueprint`, and `InputSlotBlueprint` that drops only the `hints` key when `None` (pattern: `InputFormField.serialize_without_inapplicable_slots`, `pipelex/pipeline/input_form.py`). Deliberately NOT a blanket `exclude_none` — see design Part 2.
-- [x] Check `pipelex/codegen/crate_encoding.py`'s TOML emission orders hints entries sorted by key; fix if not (JSON side is covered by `sort_keys=True` in both fingerprint functions). RESOLVED at the model instead: the shared `normalize_empty_hints` validator sorts hints keys on all three models, so every dump (fingerprints, codegen, wire) is canonical with no encoder walking.
+- [x] E6: `_render_schema_representation` (`pipelex/core/concepts/concept.py`) injects the concept's authored description as top-level `description` (no-op for generated classes; authored fact for class-backed; pinned native blueprint description for native direct inputs)
+- [x] E6: docstrings on native content classes lacking one (`TextContent`, `ImageContent`, `DocumentContent`, `PageContent`, `NumberContent`, `HtmlContent`, `YesNoContent`) — pinned description text verbatim; the pinned-consistency test (`tests/unit/pipelex/codegen/test_native_expansion.py`) compares factory descriptions, not docstrings, so no interference
+- [x] E1: top-level `title` becomes the concept ref at the same render seam (nested identity stays descriptor-only; no `$defs` renames)
+- [x] E4: `render_concept_representation` takes real multiplicity (not a boolean) — threaded through `render_stuff_spec`; new helpers `is_multiple_multiplicity` / `fixed_item_count` in `variable_multiplicity.py`; `StuffSpec.is_multiple()` delegates; `runner_code.py` local `_is_multiple` deleted in favor of the shared helper
+- [x] E4: array wrap emits `minItems`/`maxItems` = N when fixed; variable `[]` gets neither bound; `[1]` stays single (no wrap, no bounds)
+- [x] E4: contract memo key normalized to `(concept_ref, is_multiple, fixed_count)` (avoids the `hash(True) == hash(1)` collision between `Concept[]` and `Concept[1]`)
+- [x] Guard: `DocumentContent.url` field-description wording untouched (class gained only a docstring)
+- [x] Probe bundle + trace harness: no extension needed — the existing fixtures already exercise class-backed (`probe_refined.classbacked`), native-direct (`probe_native_inputs`), and fixed-count (`probe_markers.two = Gadget[2]`) inputs; all three enrichments verified present in the regenerated captures
+- [x] Re-baseline the Phase 0-inventoried schema-byte captures: `wip/input-semantics/probe/` regenerated; `docs/tools/cli/build/output.md` schema examples hand-updated (concept-ref title, top-level description, `minItems`/`maxItems`)
+- [x] Unit tests at the render seams: four new tests in `TestSchemaRepresentationWithMultiple` (title/description injection, array identity on items, fixed-count bounds, `[1]` stays single) + `tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py` for the two helpers
+- [x] Changelog (Unreleased): additive schema enrichments
-### Fixtures and tests
+**Checkpoint 2** — the "zero client changes" half complete and measurable.
-- [x] Update `tests/data/input_semantics/rejected/per_input_description.mthds_invalid` commentary: it remains a valid rejection, but the rationale shifts to "unknown slot-table key"; verify the failure now surfaces as the slot-table extras error.
-- [x] Add accepted-fixture siblings: `{ concept = "…" }` (collapses to string form) and `{ concept = "…", hints = { intent = "prose" } }`.
-- [x] Parse unit tests (homes: `tests/unit/pipelex/core/concepts/concept_blueprint/`, `tests/unit/pipelex/mthds_parsing/`): each site accepts a valid flat table; non-table `hints`, non-string values, and nested tables fail as structural errors at all three sites; unknown slot-table keys fail; the collapse rule; grammar preserved through the table arm (multiplicity + markers on `concept`).
-- [x] Serialization unit test: the serialized JSON of a hint-free concept/field/pipe contains no `hints` key at any depth.
-- [x] Re-run unchanged: `test_fingerprint_determinism`, `test_normalization_is_idempotent`, the round-trip integration suite, and the pinned-fingerprint regression — all green with the fields in place.
+- [x] Checkpoint 2: tracker updated, checks green
-## Phase 2 — Crate travel
+### Checkpoint 2 state (for cold start)
-- [x] `crate_qualification._qualify_io_ref` (`pipelex/libraries/crate_qualification.py`): handle the table arm — qualify the table's `concept` through `_render_ref_with_markers`, pass `hints` through untouched.
-- [x] `crate_normalization._collect_referenced_natives` (`pipelex/libraries/crate_normalization.py`): read the table arm's `concept`.
-- [x] `InputStuffSpecsFactory.make_from_blueprint` (`pipelex/core/pipes/inputs/input_stuff_specs_factory.py`): accept the union, extract the `concept` string ONLY. `StuffSpec` must NOT grow a hints field — runtime models stay hint-free (structural non-normativity).
-- [x] Effective hints in normalization: extend `_RefinementResolution` with `effective_hints: dict[str, str] | None`; accumulate along the child→base walk in `_resolve_refinement` via the shared `merge_hints` (nearer declaration wins). Applies to both the flattened arm and the `refines`-keeping (native-backed) arm; pinned natives contribute nothing. Empty merge leaves no member.
-- [x] Memoization guard: a cached mid-chain resolution must carry the hints of ITS position in the chain, not the querying concept's — add a test that exposes this.
-- [x] Structure-field and slot hints carried as authored through qualification and normalization (no merge at crate level — the site-over-concept merge is the deriver's).
-- [x] Normalization unit tests (`tests/unit/pipelex/libraries/test_crate_normalization.py`): chain merge on both arms, memoized mid-chain hints, empty merge, idempotency extended to a hinted fixture (re-normalizing is a no-op).
-- [x] Integration: round-trip suite green with a hinted fixture; a hinted crate's fingerprint differs from its hint-free twin.
+Phase 2 delivered entirely inside: `concept.py` (render seam: multiplicity param + title/description injection + array bounds), `variable_multiplicity.py` (two new helpers), `stuff_spec.py` (delegation + pass-through), `runner_code.py` (shared helper), `pipe_io_contracts.py` (normalized memo key), seven native content classes (docstrings), plus tests, probe re-baseline, and the docs example. Signature change is breaking for direct callers of `render_concept_representation` (`is_multiple` → `multiplicity`) — all in-repo callers and tests updated. Phase 3 recon (from the paused-note, still valid): `PresenceMarker` in `variable_multiplicity.py` is exactly the contract's `presence` vocabulary; contract models to replace are `pipe_io_contracts.py` (`IOMultiplicity`, `PipeInputContract`, `PipeOutputContract`). Note for Phase 4 (unchanged): removing `titled_default` from the probe bundle WILL move the pinned hint-free fingerprints in `test_fingerprint_pins.py` — recompute the pins then.
-## Checkpoint A — crate layer done
+## Phase 3 — contract reshaping (E5, E9) — protocol change, spec-first
-- [x] Hints parse at three sites, travel qualified and normalized, hint-free crates provably keep their digests. Update `wip/engine-hints/design.md` with decisions and deviations; verify cold-start readiness; commit.
+- [x] Spec: `../docs/specs/pipelex-mthds-protocol.md` — `pipe_io_contracts` row, "Optional IO contracts and liftable pipes" section, Verified-by line, and the abridged `ValidReport` example all updated to `presence` / three-valued `multiplicity` + `item_count`
+- [x] Spec: one sentence documenting `json_schema` as pydantic-canonical, single-choice enums as `const` (E10's documentation half) — appended to the `pipe_io_contracts` row
+- [x] Conformance: assertions reshaped in `conformance/tests/pipelex_api/test_validate_optionals.py` — the gate is shape-detected (`presence` absent → skip), so it arms automatically when `pipelex-api` re-pins at the cascade; the fixed-count arm stays pinned in pipelex's own suite (the shared optionals fixture has no `[N]` slot, deliberately not extended)
+- [x] `make check-spec-links` in `conformance/` — green (note: `make agent-check` there also surfaced PRE-EXISTING vendored-corpus drift on `vocabulary.toml` from H2, covered by the filed release-time sync inbox item — not this branch's to fix)
+- [x] Engine: `PipeInputContract.presence` replaces `optional` (reuses `PresenceMarker` — same wire values as the descriptor); input + output gain three-valued `IOMultiplicity` (+`FIXED`) and `item_count` via the new `make_io_multiplicity` projection; output `optional` unchanged
+- [x] Emission threads real multiplicity (retired `IOMultiplicity`'s fixed-reports-as-variable ruling)
+- [x] Tests on the contract fields: `tests/integration/pipelex/pipeline/test_pipe_io_contracts.py` reshaped + new `make_two` fixed-count pipe pinning `fixed`/`item_count=2` on input and output plus the bounded array schema
+- [x] Changelog (Unreleased): breaking protocol reshape
+- [x] Probe hop5 capture re-baselined (same regen command); verified `opt/many/two/forced` report exactly (`optional`,`single`) / (`plain`,`variable`) / (`plain`,`fixed`,2) / (`force`,`single`)
-## Phase 3 — Advisory lint
+**Checkpoint 3** — the protocol change contained in one reviewable unit.
-- [x] New `pipelex/pipeline/hint_warnings.py` with `build_hint_warnings(...)`: sweep the qualified crate's three sites, emit one advisory `ValidationErrorItem` per finding (unknown hint key, unknown `intent` word, applicable word on inapplicable site), each naming its site (concept code / field name / pipe code + slot name). Warn only — never reject; well-formed unknown content is preserved.
-- [x] Advisory enum: new `HintLintErrorType` (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`) joined into the `ValidationErrorType` alias (`pipelex/validation_error_types.py`). Open question 1: if the render layer's required properties make a shared enum cheaper, decide here with the code in view — the wire strings are the contract, the enum layout is not. RESOLVED open question 1: separate enum, no render-layer properties needed.
-- [x] Wire into `pipelex/pipeline/validate_in_process.py` beside `build_optionality_warnings`. Done via `build_current_library_hint_warnings()` (empty sweep when no library/crate — the mocked-plumbing and fallback paths). The bare-CLI / agent-CLI / builder-ops warning channels are a deferred follow-up (see `wip/engine-hints/deferred.md`).
-- [x] Regenerate the two gates: error-identity snapshot (`make gei`) and error-reference docs pages (`make gep`). Outcome: no diff from either — `HintLintErrorType` members are enum values, not `PipelexError` subclasses; the corpus vocabulary DID regenerate (three excluded `error.hint_*` tags).
-- [x] Lint unit tests (beside `test_validation_errors.py`): each warning fires with site attribution; a warned bundle is still valid; warned content survives into crate and descriptor. Home: `tests/unit/pipelex/pipeline/test_hint_warnings.py` + a warned-bundle-still-valid integration test in `test_protocol_validate.py`. Descriptor-survival half lands with Phase 4.
+- [x] Checkpoint 3: tracker updated, checks green (`make check` exit 0; the full suite surfaced ONE stale assertion — `test_trace_input_semantics_cmd.py` still pinned the pre-reshape `inputs.hint.optional` — fixed to `presence`/`multiplicity`; full-suite green rides Phase 4's final gate)
-## Phase 4 — Descriptor population
+## Phase 4 — semantics and close (E3, reflected defaults)
-- [x] Narrow `InputFormField.hints` from `dict[str, Any]` to `dict[str, str]` (`pipelex/pipeline/input_form.py`) — flatness is contract.
-- [x] Plumb slot hints from the qualified crate: `build_input_form` keeps the qualified crate's `pipes` too; per slot name, the blueprint's `inputs` value is a string (no hints) or a slot table (hints). Open question 3: per-call `derive_slot` argument vs pipe-ref-keyed lookup — taste call, decide here; the invariant is that `StuffSpec` stays hint-free. Fallback path (no crate) derives with no hints. RESOLVED open question 3: per-call `derive_slot(slot_hints=...)` argument — the `build_input_form` loop has blueprint and StuffSpec in hand; the deriver stays stateless over pipes.
-- [x] Concept nodes (`_blueprint_node`, `derive_concept`): stamp the concept's effective hints — deriver computes the chain merge via its existing `_refines_chain` walk calling the shared `merge_hints`. String-shorthand, natives, and class-backed concepts stamp nothing.
-- [x] Structure fields (`_structure_field`): `merge_hints([referenced concept's effective hints (concept-typed and concept-item fields only), field.hints])`, stamped via `model_copy(update=…)`.
-- [x] Input slots (`derive_slot`): `merge_hints([slot concept's effective hints, slot hints])`, stamped in the final `model_copy(update=…)` beside `presence`/`required`/`gating`.
-- [x] Plural slots and list fields: merged hints stamped on the `list` node AND its `item` descriptor (the `concept_ref` duplication precedent).
-- [x] Intent feeds kind — never competes: via `applicable_intent(...)`, on text-valued nodes `intent = "prose"` → `kind: "prose"`, `intent = "label"` → `kind: "text"`; absent/inapplicable/unknown intent leaves the no-hint default; `rating`/`quantity` never change `kind` and ride the slot; inapplicable words change nothing in `kind` but still ride the slot as preserved content. Implemented as one terminal `_with_effective_hints` stamp per node (inner layers carry hints without flipping), so the flip always reads the FINAL merge against the no-hint kind; `_node_site_kind` mirrors the lint's structural judgment (time-formatted text and Html-backed nodes are not text-valued).
-- [x] Extend the probe bundle under `tests/data/input_semantics/` with hinted fixtures. Done as the SIBLING `hinted_bundle.mthds` (probe_bundle stays hint-free forever — its fingerprints are pinned).
-- [x] Deriver unit + integration tests (`tests/integration/pipelex/pipeline/test_input_form.py` kind table): site-over-concept and chain precedence visible on the wire; `prose`/`label` flip `kind` on text-valued nodes only; `rating`/`quantity` untouched-kind + slot ride; list/item duplication; hint-free descriptor output byte-identical to today.
+- [x] E3: model validator on `ConceptStructureBlueprint` rejecting `required = true` + `default_value` (message names both remedies) + unit seam `test_concept_structure_blueprint_required_default.py`
+- [x] E3: generator's accidental branch replaced by an explicit raising invariant (`ConceptStructureGeneratorError`) + unit seam `test_structure_generator_required_default_invariant.py`
+- [x] E3: probe bundle's `titled_default` moved to `rejected/required_with_default.mthds_invalid`; pair-sweep fallout applied (builder fixture `test_data.py` had authored the pair — `age` keeps `required`, drops the default); `test_input_form.py` now pins `motto` (`required: false` beside its default); fingerprint pins legitimately recomputed (fixture-content change, recorded in the pin module's docstring)
+- [x] Reflected defaults: `_with_reflected_constraints` reads `field_info.is_required()` + `field_info.default` (a `None` default is the optionality artifact, never reported); kind-table row via the new `retries` field on `InputFormConstrainedPayload`
+- [x] Descriptor spec touch-up: the "may carry both" sentence retired (`default_value` row now states the rejection), the "Facts over emission accidents" bullet notes the founding case resolved, the Verified-by line follows; the D2 conformance skeleton's fixture + assertions moved with it (`required = true` dropped from its `title` field) — `make check-spec-links` green
+- [x] Survival table updated with before/after closure rows (E3, E4, E5, E6/E1, E7, E9) against regenerated `wip/input-semantics/probe/` captures (`titled_default` gone from all hops)
+- [x] Findings addendum §F: per-entry closure evidence table
+- [x] Roadmap Track S closure bullet: in-engine close now, hosted-wire half at the cascade
+- [x] Changelog (Unreleased): E3 breaking + reflected-defaults ruling (Changed)
+- [x] Cross-repo inbox filings (§8): `2026-08-23-mthds-structure-field-validation-sentences.md`, `2026-08-23-pipelex-js-mirror-schema-enrichments-and-contract-reshape.md`, `2026-08-23-mthds-js-protocol-types-contract-reshape.md`
+- [x] In-repo docs swept: `inline-structures.md` gains the `required` bullet + the pair rule; `under-the-hood/input-form-descriptor.md` constraint paragraph updated (E7 made the "parser drops unknown constraint keys" claim false) + reflected-defaults sentence
+- [x] Final: `make agent-check` + full `make agent-test` green (suite exit 0)
-## Checkpoint B — round trip end to end
+## PR #1149 review loop
-- [x] Authored hints visible in `hop5_input_form.json` via the trace harness (`pipelex-dev trace-input-semantics`) on the hinted corpus method. Same checkpoint protocol as A: update the design doc, verify cold-start readiness, commit.
+- [x] PR created (`feature/Enrich` → `dev`), CI fully green on first push
+- [x] Bot reviews (Greptile + codex): both converged on ONE finding — `item_count: null` for non-fixed multiplicity "violates the contract". REJECTED after verification: the protocol spec, its wire example, and `conformance/tests/pipelex_api/test_validate_optionals.py` all pin `item_count: null` off the fixed arm for `pipe_io_contracts` (the omit-when-absent convention belongs to the input-form descriptor; the two artifacts deliberately differ). Replied with evidence, resolved both threads; the misleading docstring wording disambiguated
+- [x] gstack `/review @TODOS.md` (fresh context): verdict SHIP, no P1. Clear wins applied: spec-layer E3 validator on `ConceptStructureSpec` (same two-remedies message; an authoring agent no longer validates green then dies on its own TOML) + spec-level test; stale `default_value` docstring in `input_form.py` fixed; inline duplicate of `fixed_item_count` in `derive_slot` replaced by the helper; parser-level tests wiring both new `rejected/` fixtures (`test_parser_rejected_structure_fields.py`); `force` presence pinned on the wire contract (`brief = "Text!"`); `Text[1]`→single contract projection + memo-key collision pinned (`make_from_one`); reflected `default_factory` (no fabricated default) and falsy default (`False` survives the None guard) pinned; wire-level `item_count`-always-present pinned in the trace test; changelog extended with the spec-layer half
+- [x] Deferred (review findings short of clear wins): `wip/enrich/deferred.md` — non-serializable reflected default, `_peel_multiplicity` `[1]`-as-list divergence (pre-existing), `_with_reflected_constraints` naming, double multiplicity normalization, mostly-inert `rejected/` corpus audit. Skipped outright: 0/negative-count helper rows (unreachable from bundles)
+- [x] Cross-repo: `../wip/inbox/2026-08-23-mthds-form-contract-reshape.md` filed — `mthds-form` still gates the Run button on the retired input `optional` and lacks the `fixed` multiplicity arm; no reshape item covered it
-## Phase 5 — Schema, corpus, docs, close
+## Out of scope (per design §9)
-- [x] Regenerate `derived/mthds_schema.json` (`make gms`), verify with `make cms`; if Taplo's `anyOf` disambiguation misbehaves on the slot union, hand-patch via the `_patch_construct_schema` precedent in `pipelex/language/mthds_schema_generator.py`. *(All three hint sites present in the schema; `cms` green, no hand-patch needed.)*
-- [x] Corpus entry authoring hints at all three sites (`pipelex/test_extras/mthds_corpus/`); re-run `make generate-corpus-vocabulary`. This entry is the "one real method" the gate's round-trip proof runs on. *(`feature_intent_hints_reading_circle`: concept + structure-field + expanded-slot hints; `feature.intent_hints` tag added; corpus suites green.)*
-- [x] Check the builder writer (`pipelex/builder/operations/concept_ops.py`): if preserving hints on rewrite is a one-liner, do it; otherwise file the follow-up (it sits beside the known E8 spelling bug in the same writer). *(Not a one-liner — `ConceptSpec`/`ConceptStructureSpec` lack the field entirely; follow-up filed in `wip/engine-hints/deferred.md`.)*
-- [x] Docs: `docs/under-the-hood/input-form-descriptor.md` — the stated no-hint kind rules (promote heuristics to specified rules), hints slot no longer reserved-only, drop the now-false "parser drops unknown keys" framing where it touches hints; document the three authoring sites and the lint in the language-facing blueprint docs.
-- [x] Changelog: record the feature under `## [Unreleased]`.
-- [x] Full gates: `make agent-check` + `make agent-test` green. *(Both green on the settled Phase 5 tree; the pre-existing `test_transported_run_generates_concept_structures` order-dependent flake did not recur — noted in `wip/flaky-test-transported-run-structures.md`.)*
-- [x] Milestone close per workspace protocol:
- - [x] Roadmap checkpoint in `../wip/devx/input-form-roadmap.md` with SHAs, including the gate-wording reconciliation (open question 2: engine-provable gate = wire-descriptor visibility; rendered-control half completes with M1/H3). *(Applied with commit subjects rather than SHAs — the branch squash-merges, so branch SHAs die; H2 marked ✅ in the dependency graph. Workspace-repo edits left uncommitted for review.)*
- - [x] Workspace descriptor spec (`../docs/specs/mthds-input-form-descriptor.md`): reserved-hint-slot section from "reserved" to "populated"; kind-assignment section reflects the stated no-hint rules.
- - [x] Conformance repo: hint-slot arm as a skip-gated skeleton (D2's de-gating pattern, arming at the release that ships H2); `make check-spec-links` in `conformance/`. *(`TestInputFormHintSlot`, 4 skip-gated tests; both conformance gates green.)*
- - [x] Inbox items (`../wip/inbox/`): the `mthds`-site "Specification Status" conformance-assertion update, and the `mthds-corpus-sync` / `mthds-schema-sync` runs that ride the next release.
- - [x] H3 handoff note. *(`../wip/inbox/2026-08-23-mthds-form-h3-render-intent-hints.md`.)*
-
-## Out of scope (do not do here)
-
-E7 `extra="forbid"` on `ConceptStructureBlueprint` (S2); per-slot semantic keys (`description`, defaults, examples); hints on class-backed structures and natives; the crate spec's general absent-members-not-null canonicalization and step-5 materialization; kernel rendering (H3) and consumer wire-descriptor swap (M1).
+Language ceiling (S1 §B) syntax, app-side fixes (M1), corpus widening, `const`→`enum` render rewrite, descriptor wire-model round-trip alias (D4).
diff --git a/docs/building-methods/concepts/inline-structures.md b/docs/building-methods/concepts/inline-structures.md
index 16c93eb81..dda032ecc 100644
--- a/docs/building-methods/concepts/inline-structures.md
+++ b/docs/building-methods/concepts/inline-structures.md
@@ -56,7 +56,8 @@ Each field can specify:
- **type**: The data type (required for detailed definitions)
- **description**: Human-readable description
-- **default_value**: Default value if not provided
+- **required**: Whether the field must be present in the payload (defaults to `false`)
+- **default_value**: Default value applied when the field is omitted. A field cannot declare both `required = true` and a `default_value` — a default makes absence legal, which contradicts requiring the field, so the pair is rejected at validation
- **choices**: For `enum`-like fields, a list of valid values
- **item_type**: For `list` fields, the type of list items
- **key_type** and **value_type**: For `dict` fields, the types of keys and values
diff --git a/docs/tools/cli/build/output.md b/docs/tools/cli/build/output.md
index 4da9cc2cc..ecca6c044 100644
--- a/docs/tools/cli/build/output.md
+++ b/docs/tools/cli/build/output.md
@@ -156,7 +156,7 @@ The Python format generates class instantiation code:
### Schema Format
-The schema format generates JSON Schema definitions, ideal for generating TypeScript interfaces or Zod schemas:
+The schema format generates JSON Schema definitions, ideal for generating TypeScript interfaces or Zod schemas. The schema's top-level `title` is the concept ref, and its top-level `description` is the concept's authored description:
```json
{
@@ -168,12 +168,13 @@ The schema format generates JSON Schema definitions, ideal for generating TypeSc
"key_points": { "type": "string", "title": "Key Points" }
},
"required": ["title", "key_points"],
- "title": "MyOutputConcept"
+ "title": "my_domain.MyOutputConcept",
+ "description": "The concept's description, as authored in the bundle"
}
}
```
-**Array outputs** (e.g., `MyType[5]`) are properly represented as JSON Schema arrays:
+**Array outputs** are represented as JSON Schema arrays, with the concept identity kept on `items`. A fixed count (e.g., `MyType[5]`) additionally emits `minItems`/`maxItems` bounds; a variable-length list (`MyType[]`) carries no bounds:
```json
{
@@ -187,8 +188,11 @@ The schema format generates JSON Schema definitions, ideal for generating TypeSc
"description": { "type": "string", "title": "Description" }
},
"required": ["name", "description"],
- "title": "Item"
- }
+ "title": "my_domain.Item",
+ "description": "An item of the collection"
+ },
+ "minItems": 5,
+ "maxItems": 5
}
}
```
diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.md
index 28b582c92..18c391917 100644
--- a/docs/under-the-hood/input-form-descriptor.md
+++ b/docs/under-the-hood/input-form-descriptor.md
@@ -2,7 +2,7 @@
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.
+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, 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
@@ -49,7 +49,7 @@ The table and rules above ARE the no-hint kind assignment — stated rules, not
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 *constraint* keys it does not know, so an authored `minimum = 0` never reaches the deriver, whereas a registered class's `Field(gt=0, max_length=8, pattern=...)` is read from the pydantic field metadata and stamped on the matching `number` or `text` node. (Authored `hints` are the exception — they are a parsed blueprint field, not a dropped unknown; see below.)
+Constraint slots (`minimum`, `exclusive_minimum`, `min_length`, `pattern`, …) come only from reflected classes: the language cannot author constraint keys (an authored `minimum = 0` is rejected as an unknown structure-field key), 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. A pydantic default on a reflected class is an authored fact: `field_info.is_required()` decides the node's `required` and a non-`None` default is reported as its `default_value` — a defaulted field is never required, the same invariant blueprint validation enforces by rejecting the `required = true` + `default_value` pair. (Authored `hints` are a parsed blueprint field with its own leniency rules; see below.)
## Hints
diff --git a/pipelex/builder/concept/concept_spec.py b/pipelex/builder/concept/concept_spec.py
index 950e0b45e..50a16f376 100644
--- a/pipelex/builder/concept/concept_spec.py
+++ b/pipelex/builder/concept/concept_spec.py
@@ -104,6 +104,13 @@ class ConceptStructureSpec(StructuredContent):
@model_validator(mode="after")
def validate_structure_blueprint(self) -> Self:
"""Validate the structure blueprint according to type rules."""
+ if self.required and self.default_value is not None:
+ msg = (
+ f"A field cannot declare both required = true and a default_value: a default is applied when "
+ f"the caller omits the field, which contradicts requiring it. Got default_value: {self.default_value!r}. "
+ f"Drop `required` to keep the default, or drop `default_value` to keep the field required."
+ )
+ raise ValueError(msg)
match self.type:
case ConceptStructureSpecFieldType.CONCEPT:
if not self.concept_ref:
diff --git a/pipelex/builder/operations/concept_ops.py b/pipelex/builder/operations/concept_ops.py
index 4fb6584a1..e679a856e 100644
--- a/pipelex/builder/operations/concept_ops.py
+++ b/pipelex/builder/operations/concept_ops.py
@@ -113,7 +113,7 @@ def structure_field_to_dict(field_spec: ConceptStructureSpec) -> dict[str, Any]:
result["required"] = True
if field_spec.default_value is not None:
- result["default"] = field_spec.default_value
+ result["default_value"] = field_spec.default_value
if field_spec.concept_ref:
result["concept_ref"] = field_spec.concept_ref
diff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.py
index 05652b094..7e85f3460 100644
--- a/pipelex/builder/runner_code.py
+++ b/pipelex/builder/runner_code.py
@@ -20,7 +20,7 @@ from pipelex.core.concepts.concept_representation_generator import (
)
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
-from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
+from pipelex.core.pipes.variable_multiplicity import is_multiple_multiplicity
from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.runtime_hub import get_class_registry
@@ -29,23 +29,6 @@ STRUCTURES_MODULE = "structures.structures"
"""Module path of the emitted types projection, relative to the generated script's directory."""
-def _is_multiple(multiplicity: VariableMultiplicity | None) -> bool:
- """Check if the multiplicity indicates multiple items.
-
- Args:
- multiplicity: The multiplicity value (None, bool, or int)
-
- Returns:
- True if multiple items are expected
- """
- if multiplicity is None:
- return False
- if isinstance(multiplicity, bool):
- return multiplicity
- # int means specific count, which is multiple
- return multiplicity > 1
-
-
def _format_representation_as_python(representation: dict[str, Any], *, is_multiple: bool = False) -> str:
"""Format a representation dict as Python code.
@@ -226,11 +209,11 @@ def generate_runner_code(
if not pipe.inputs.is_empty:
input_entries: list[str] = []
for var_name, input_req in pipe.inputs.root.items():
- is_multiple = _is_multiple(input_req.multiplicity)
+ is_multiple = is_multiple_multiplicity(multiplicity=input_req.multiplicity)
result, _ = input_req.concept.render_concept_representation(
structure_class=get_concept_library().get_structure_class(concept=input_req.concept),
output_format=ConceptRepresentationFormat.PYTHON,
- is_multiple=is_multiple,
+ multiplicity=input_req.multiplicity,
class_name_overrides=overrides,
)
python_code = _format_representation_as_python(result, is_multiple=is_multiple)
diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.py
index ab3933c21..fd78cb6d9 100644
--- a/pipelex/core/concepts/concept.py
+++ b/pipelex/core/concepts/concept.py
@@ -13,6 +13,7 @@ from pipelex.core.concepts.validation import is_concept_ref_or_code_valid, valid
from pipelex.core.domains.domain import SpecialDomain
from pipelex.core.domains.exceptions import DomainCodeError
from pipelex.core.domains.validation import validate_domain_code
+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity, fixed_item_count, is_multiple_multiplicity
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.misc.string_utils import pascal_case_to_sentence
@@ -155,7 +156,7 @@ class Concept(ConceptAbstract):
*,
structure_class: type[StuffContent],
output_format: ConceptRepresentationFormat,
- is_multiple: bool = False,
+ multiplicity: VariableMultiplicity | None = None,
class_name_overrides: dict[str, str] | None = None,
) -> tuple[dict[str, Any], set[str]]:
"""Render a representation for this concept.
@@ -165,19 +166,22 @@ class Concept(ConceptAbstract):
looked up: turning `structure_class_name` into a type is a registry read, and the
caller's provider is the only thing that knows *which* registry to read.
output_format: The format to generate (JSON, PYTHON, or SCHEMA)
- is_multiple: If True, wrap content in a list/array schema
+ multiplicity: The declared multiplicity: None for a single item, True for a
+ variable-length list, an int for a fixed count. A list-shaped multiplicity wraps
+ the content in a list/array, and a fixed count reaches the SCHEMA render as
+ `minItems`/`maxItems` bounds.
class_name_overrides: Optional runtime-class-name -> rendered-name mapping applied to
Python instantiation code and imports (see ConceptRepresentationGenerator)
Returns:
Tuple of (representation dict, imports_needed set)
- - For JSON: content is a dict (or list of dicts if is_multiple)
+ - For JSON: content is a dict (or list of dicts when multiple)
- For Python: content is a class instantiation string (wrapping handled by caller)
- - For SCHEMA: content is a JSON Schema dict (or array schema if is_multiple)
+ - For SCHEMA: content is a JSON Schema dict (or array schema when multiple)
"""
match output_format:
case ConceptRepresentationFormat.SCHEMA:
- return self._render_schema_representation(structure_class=structure_class, is_multiple=is_multiple)
+ return self._render_schema_representation(structure_class=structure_class, multiplicity=multiplicity)
case ConceptRepresentationFormat.JSON | ConceptRepresentationFormat.PYTHON:
generator = ConceptRepresentationGenerator(output_format, class_name_overrides=class_name_overrides)
# For inputs, we only want required fields (not optional ones)
@@ -185,30 +189,46 @@ class Concept(ConceptAbstract):
# If multiple and JSON format, wrap content in a list
# For Python format, the caller handles wrapping since content is a string
- if is_multiple and output_format == ConceptRepresentationFormat.JSON:
+ if is_multiple_multiplicity(multiplicity=multiplicity) and output_format == ConceptRepresentationFormat.JSON:
result["content"] = [result["content"]]
return result, generator.imports_needed
- def _render_schema_representation(self, *, structure_class: type[StuffContent], is_multiple: bool = False) -> tuple[dict[str, Any], set[str]]:
+ def _render_schema_representation(
+ self,
+ *,
+ structure_class: type[StuffContent],
+ multiplicity: VariableMultiplicity | None = None,
+ ) -> tuple[dict[str, Any], set[str]]:
"""Render JSON Schema for this concept.
Args:
structure_class: This concept's already-resolved structure class.
- is_multiple: If True, wrap the schema in an array type
+ multiplicity: None for a single item, True for a variable-length list, an int for a
+ fixed count. A list-shaped multiplicity wraps the schema in an array type, and a
+ fixed count adds `minItems`/`maxItems` bounds on the array.
Returns:
Tuple of (representation dict with JSON Schema content, empty set)
The dict has "concept" and "content" keys where content is the JSON Schema.
"""
json_schema = structure_class.model_json_schema()
-
- if is_multiple:
- # Wrap the schema in an array schema
+ # The concept's identity and authored description are facts of the concept, not of its
+ # (possibly shared) structure class, so they are injected on the object schema at the
+ # render: `title` is the concept ref, `description` the concept's authored description.
+ json_schema["title"] = self.concept_ref
+ json_schema["description"] = self.description
+
+ if is_multiple_multiplicity(multiplicity=multiplicity):
+ # Wrap the schema in an array schema; the concept identity stays on `items`.
array_schema: dict[str, Any] = {
"type": "array",
"items": json_schema,
}
+ item_count = fixed_item_count(multiplicity=multiplicity)
+ if item_count is not None:
+ array_schema["minItems"] = item_count
+ array_schema["maxItems"] = item_count
return {"concept": self.concept_ref, "content": array_schema}, set()
return {"concept": self.concept_ref, "content": json_schema}, set()
diff --git a/pipelex/core/concepts/concept_structure_blueprint.py b/pipelex/core/concepts/concept_structure_blueprint.py
index 8b36b58fc..b2f3f1df0 100644
--- a/pipelex/core/concepts/concept_structure_blueprint.py
+++ b/pipelex/core/concepts/concept_structure_blueprint.py
@@ -2,7 +2,7 @@ from datetime import date, datetime, time
from enum import StrEnum
from typing import Any, Self
-from pydantic import BaseModel, Field, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validator
+from pydantic import BaseModel, ConfigDict, Field, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validator
from pipelex.core.concepts.validation import is_concept_ref_or_code_valid
from pipelex.system.pipe_run_param_key import PipeRunParamKey
@@ -48,6 +48,13 @@ class ConceptStructureBlueprintFieldType(StrEnum):
class ConceptStructureBlueprint(BaseModel):
+ """One field of a concept's structure table. Unknown keys are rejected — the field table's
+ keys are strict, exactly like an input slot table's; hint *content* stays lenient (unknown
+ hint keys warn and are preserved, per intent-hints.md).
+ """
+
+ model_config = ConfigDict(extra="forbid")
+
description: str
type: ConceptStructureBlueprintFieldType | None = None
# type=dict
@@ -105,6 +112,16 @@ class ConceptStructureBlueprint(BaseModel):
@model_validator(mode="after")
def validate_structure_blueprint(self) -> Self:
"""Validate the structure blueprint according to type rules."""
+ # required + default_value contradict each other: a default's meaning is "applied when the
+ # caller omits the field", which makes absence legal — the opposite of required (E3).
+ if self.required and self.default_value is not None:
+ msg = (
+ f"A field cannot declare both required = true and a default_value: a default is applied when "
+ f"the caller omits the field, which contradicts requiring it. Got default_value: {self.default_value!r}. "
+ f"Drop `required` to keep the default, or drop `default_value` to keep the field required."
+ )
+ raise ValueError(msg)
+
# If type is None (array), choices must not be None
if self.type is None and not self.choices:
msg = f"When type is None (array), choices must not be empty. Actual type: {self.type}, choices: {self.choices}"
diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.py
index 4768a376c..b22e5db54 100644
--- a/pipelex/core/concepts/structure_generation/generator.py
+++ b/pipelex/core/concepts/structure_generation/generator.py
@@ -305,7 +305,16 @@ class StructureGenerator:
# Generate Field parameters (default/... first, then description)
field_params = [self._format_field_description(resolved_field.description)]
default_value = resolved_field.default_value
- if resolved_field.required and default_value is None:
+ if resolved_field.required:
+ # The blueprint validator rejects `required = true` beside a `default_value` (E3),
+ # so a required field can never carry a default here — assert the invariant loudly
+ # instead of letting parameter ordering tiebreak silently.
+ if default_value is not None:
+ msg = (
+ f"Field '{resolved_field.name}' is required AND carries default_value {default_value!r} — "
+ f"the blueprint validator rejects this pair, so reaching the generator with it is a bug."
+ )
+ raise ConceptStructureGeneratorError(msg)
field_params.insert(0, "...")
elif default_value is not None:
field_params.insert(0, f"default={self._format_default_value(default_value)}")
diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec.py b/pipelex/core/pipes/stuff_spec/stuff_spec.py
index efd361116..db3dd3e54 100644
--- a/pipelex/core/pipes/stuff_spec/stuff_spec.py
+++ b/pipelex/core/pipes/stuff_spec/stuff_spec.py
@@ -5,7 +5,12 @@ from pydantic import BaseModel
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
-from pipelex.core.pipes.variable_multiplicity import PresenceMarker, VariableMultiplicity, format_concept_with_multiplicity
+from pipelex.core.pipes.variable_multiplicity import (
+ PresenceMarker,
+ VariableMultiplicity,
+ format_concept_with_multiplicity,
+ is_multiple_multiplicity,
+)
class StuffSpec(BaseModel):
@@ -14,11 +19,7 @@ class StuffSpec(BaseModel):
presence: PresenceMarker = PresenceMarker.PLAIN
def is_multiple(self) -> bool:
- if self.multiplicity is None:
- return False
- if isinstance(self.multiplicity, bool):
- return self.multiplicity
- return self.multiplicity > 1
+ return is_multiple_multiplicity(multiplicity=self.multiplicity)
def to_bundle_representation(self, *, relative_to_domain: str | None = None) -> str:
"""Render this spec as a bundle ref string (concept + multiplicity + presence marker).
@@ -55,6 +56,6 @@ class StuffSpec(BaseModel):
json_value, _ = self.concept.render_concept_representation(
structure_class=concept_provider.get_structure_class(concept=self.concept),
output_format=output_format,
- is_multiple=self.is_multiple(),
+ multiplicity=self.multiplicity,
)
return json_value
diff --git a/pipelex/core/pipes/variable_multiplicity.py b/pipelex/core/pipes/variable_multiplicity.py
index 4d7cb6388..0f313e5a1 100644
--- a/pipelex/core/pipes/variable_multiplicity.py
+++ b/pipelex/core/pipes/variable_multiplicity.py
@@ -112,6 +112,31 @@ def make_variable_multiplicity(*, nb_items: int | None, multiple_items: bool | N
return variable_multiplicity
+def is_multiple_multiplicity(*, multiplicity: VariableMultiplicity | None) -> bool:
+ """Whether a multiplicity denotes a list of items.
+
+ True for a variable-length list (`[]`) and for a fixed count above one (`[N]`, N > 1).
+ A fixed count of exactly one (`[1]`) stays single: no list framing.
+ """
+ if multiplicity is None:
+ return False
+ if isinstance(multiplicity, bool):
+ return multiplicity
+ return multiplicity > 1
+
+
+def fixed_item_count(*, multiplicity: VariableMultiplicity | None) -> int | None:
+ """The exact item count when the multiplicity is a fixed count above one, else None.
+
+ Both a variable-length list (`True`) and a single item (`None` or `[1]`) report None —
+ only a genuine fixed-length list carries a count. The bool check must come first:
+ `True` is an `int` in Python and would otherwise read as a count of 1.
+ """
+ if multiplicity is None or isinstance(multiplicity, bool):
+ return None
+ return multiplicity if multiplicity > 1 else None
+
+
class MultiplicityParseResult(BaseModel):
concept_ref_or_code: str
multiplicity: int | bool | None
diff --git a/pipelex/core/stuffs/document_content.py b/pipelex/core/stuffs/document_content.py
index 68cd01c07..cfa8ae482 100644
--- a/pipelex/core/stuffs/document_content.py
+++ b/pipelex/core/stuffs/document_content.py
@@ -13,6 +13,8 @@ from pipelex.tools.uri.uri_resolver import extract_filename_from_uri, resolve_ur
class DocumentContent(StuffContent):
+ """A document"""
+
url: str = Field(..., description="The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL")
public_url: str | None = Field(default=None, description="The public HTTPS URL of the document")
diff --git a/pipelex/core/stuffs/html_content.py b/pipelex/core/stuffs/html_content.py
index 359cc4288..3e7fc6d3d 100644
--- a/pipelex/core/stuffs/html_content.py
+++ b/pipelex/core/stuffs/html_content.py
@@ -9,6 +9,8 @@ from pipelex.tools.jinja2.template_category import TemplateCategory
class HtmlContent(StuffContent):
+ """HTML content"""
+
inner_html: str = Field(..., description="The inner HTML of the content")
css_class: str = Field(..., description="The CSS class of the content")
diff --git a/pipelex/core/stuffs/image_content.py b/pipelex/core/stuffs/image_content.py
index 95fce5c14..5fc39302c 100644
--- a/pipelex/core/stuffs/image_content.py
+++ b/pipelex/core/stuffs/image_content.py
@@ -17,6 +17,8 @@ from pipelex.tools.uri.uri_resolver import describe_uri, extract_filename_from_u
class ImageContent(StuffContent):
+ """An image"""
+
url: str = Field(..., description="The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL")
public_url: str | None = Field(default=None, description="The public URL of the image")
diff --git a/pipelex/core/stuffs/number_content.py b/pipelex/core/stuffs/number_content.py
index dc66f6454..1f5dc9349 100644
--- a/pipelex/core/stuffs/number_content.py
+++ b/pipelex/core/stuffs/number_content.py
@@ -7,6 +7,8 @@ from pipelex.core.stuffs.stuff_content import StuffContent
class NumberContent(StuffContent):
+ """A number"""
+
number: int | float = Field(description="The number")
@property
diff --git a/pipelex/core/stuffs/page_content.py b/pipelex/core/stuffs/page_content.py
index daa30e877..20f12b9c3 100644
--- a/pipelex/core/stuffs/page_content.py
+++ b/pipelex/core/stuffs/page_content.py
@@ -11,6 +11,8 @@ from pipelex.tools.misc.pretty import PrettyPrintable
class PageContent(StructuredContent):
+ """The content of a page of a document, comprising text and linked images and an optional page view image"""
+
text_and_images: TextAndImagesContent = Field(..., description="The text and images content extracted from the page")
page_view: ImageContent | None = Field(default=None, description="The screenshot of the page")
diff --git a/pipelex/core/stuffs/text_content.py b/pipelex/core/stuffs/text_content.py
index e05abcc3b..7a7a9d536 100644
--- a/pipelex/core/stuffs/text_content.py
+++ b/pipelex/core/stuffs/text_content.py
@@ -14,6 +14,8 @@ HTML_PATTERN = re.compile(r"^\s*<(!DOCTYPE|!--|[a-zA-Z])", re.IGNORECASE)
class TextContent(StuffContent):
+ """A text"""
+
text: str = Field(description="The text")
@property
diff --git a/pipelex/core/stuffs/yes_no_content.py b/pipelex/core/stuffs/yes_no_content.py
index 0fa5ab11d..add4f4d7b 100644
--- a/pipelex/core/stuffs/yes_no_content.py
+++ b/pipelex/core/stuffs/yes_no_content.py
@@ -7,6 +7,8 @@ from pipelex.core.stuffs.stuff_content import StuffContent
class YesNoContent(StuffContent):
+ """The answer to a yes/no question"""
+
# strict=True keeps the concept a genuine boolean: pydantic's default lax mode would coerce
# "yes"/"true"/"1"/0/1 into a bool on the dict-content path (model_validate), silently bypassing
# the no-cross-kind-coercion contract the scalar envelope arm enforces. Only a real bool is accepted.
diff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.py
index c0b107f10..24f99eec1 100644
--- a/pipelex/pipeline/input_form.py
+++ b/pipelex/pipeline/input_form.py
@@ -33,6 +33,7 @@ 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 pydantic_core import PydanticUndefined
from typing_extensions import Self
from pipelex.codegen.native_expansion import reflect_structure_class
@@ -41,7 +42,7 @@ from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBl
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.core.pipes.variable_multiplicity import PresenceMarker, fixed_item_count
from pipelex.interpreter_hub import get_current_library, get_library_manager
from pipelex.language.intent_hints import HintSiteValueKind, IntentWord, applicable_intent, merge_hints
from pipelex.libraries.crate_qualification import qualify_crate
@@ -127,7 +128,8 @@ class InputFormField(BaseModel):
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`."""
+ never the emission's `null`-for-optional artifact. Always beside `required: false`: the blueprint
+ rejects `required = true` with a default, and a reflected default makes the field not required."""
examples: list[Any] | None = None
hints: dict[str, str] | None = None
@@ -256,8 +258,7 @@ class InputFormDeriver:
node = self._concept_node(name=name, concept_ref=stuff_spec.concept.concept_ref, seen=frozenset())
effective_hints = merge_hints([node.hints, slot_hints])
if stuff_spec.is_multiple():
- multiplicity = stuff_spec.multiplicity
- item_count = multiplicity if isinstance(multiplicity, int) and not isinstance(multiplicity, bool) else None
+ item_count = fixed_item_count(multiplicity=stuff_spec.multiplicity)
# A plural slot's merged hints ride the `list` node AND its `item` (the `concept_ref`
# duplication precedent): applicability is judged per item, and a renderer reading
# either node finds the same answer.
@@ -661,12 +662,22 @@ def _scalar_field(
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=...)`).
+ """Stamp the facts a registered class states on a field: presence, default, and constraints.
- 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.
+ A pydantic default on a reflected class is an authored fact (the S2 ruling closing the D2
+ deferral): the class author wrote it, validation applies it on absence exactly like a blueprint
+ `default_value`, so `field_info.is_required()` is the source of truth for `required` and a
+ defaulted field is never required — the same invariant the blueprint side enforces (E3). A
+ `None` default is the emission artifact of optionality, never reported as a `default_value`.
+
+ Constraint slots read only what applies to the node's kind: 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] = {}
+ if field_info.is_required() != node.required:
+ constraints["required"] = field_info.is_required()
+ if field_info.default is not PydanticUndefined and field_info.default is not None:
+ constraints["default_value"] = field_info.default
match node.kind:
case FieldKind.NUMBER:
for constraint in field_info.metadata:
diff --git a/pipelex/pipeline/pipe_io_contracts.py b/pipelex/pipeline/pipe_io_contracts.py
index c143e94c7..12511aaa6 100644
--- a/pipelex/pipeline/pipe_io_contracts.py
+++ b/pipelex/pipeline/pipe_io_contracts.py
@@ -26,41 +26,56 @@ from pydantic import BaseModel, Field, PydanticUndefinedAnnotation, PydanticUser
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
from pipelex.core.concepts.exceptions import ConceptValueError
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker, VariableMultiplicity, fixed_item_count, is_multiple_multiplicity
from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipeline.exceptions import PipeIOContractError
class IOMultiplicity(StrEnum):
- """Wire value for an output's multiplicity: one item, or a list of them.
+ """Wire value for a slot's multiplicity: one item, a variable-length list, or a fixed count.
- Any multiple output — variable-length or fixed-count — reports `variable`; the
- distinction the contract carries is "one vs many", not the exact count.
+ A fixed-count slot (`Concept[N]`) reports `fixed` and carries the exact count in the
+ contract's `item_count`; a variable-length slot (`Concept[]`) reports `variable` with no
+ count. `Concept[1]` is single — no list framing.
"""
SINGLE = "single"
VARIABLE = "variable"
+ FIXED = "fixed"
class PipeInputContract(BaseModel):
"""One declared input: the concept it expects and the JSON Schema of its content."""
concept_ref: str
- optional: bool = False
- """`True` when the input is declared optional (`?`): the caller may omit it and the pipe
- handles absence itself. A plain or force (`!`) input reports `False` — it must be provided."""
+ presence: PresenceMarker = PresenceMarker.PLAIN
+ """The declared presence marker, verbatim: `optional` (`?`) means the caller may omit the
+ input and the pipe handles absence itself; `plain` and `force` (`!`) both must be provided —
+ the distinction is the authored assertion, which lint and graph surfaces read."""
+
+ multiplicity: IOMultiplicity = IOMultiplicity.SINGLE
+ item_count: int | None = None
+ """The exact item count, non-null exactly when `multiplicity` is `fixed`. The slot is always
+ on the wire — `null` off the fixed arm, per the protocol spec (the input-form descriptor makes
+ the opposite choice and omits it; the two artifacts deliberately differ)."""
json_schema: dict[str, Any] = Field(default_factory=dict)
class PipeOutputContract(BaseModel):
- """The pipe's output: the concept it produces and whether it is one item or a list."""
+ """The pipe's output: the concept it produces and how many items it resolves to."""
concept_ref: str
multiplicity: IOMultiplicity
+ item_count: int | None = None
+ """The exact item count, non-null exactly when `multiplicity` is `fixed`. Always on the wire,
+ `null` off the fixed arm — see `PipeInputContract.item_count`."""
+
optional: bool = False
"""`True` when the output is declared optional (`?`): the pipe may resolve it as a recorded
- absence instead of a value — a successful run with an absent result."""
+ absence instead of a value — a successful run with an absent result. Genuinely two-valued:
+ `!` is rejected on outputs."""
class PipeIOContract(BaseModel):
@@ -70,6 +85,20 @@ class PipeIOContract(BaseModel):
output: PipeOutputContract
+def make_io_multiplicity(*, multiplicity: VariableMultiplicity | None) -> tuple[IOMultiplicity, int | None]:
+ """Project a declared multiplicity onto the wire pair (`multiplicity`, `item_count`).
+
+ `item_count` is set exactly when the projection is `fixed`. `[1]` projects to `single`,
+ like everywhere else in the chain.
+ """
+ item_count = fixed_item_count(multiplicity=multiplicity)
+ if item_count is not None:
+ return IOMultiplicity.FIXED, item_count
+ if is_multiple_multiplicity(multiplicity=multiplicity):
+ return IOMultiplicity.VARIABLE, None
+ return IOMultiplicity.SINGLE, None
+
+
def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOContract]:
"""Project loaded pipes into `pipe_io_contracts` entries keyed by namespaced `pipe_ref`.
@@ -95,13 +124,20 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCo
# (pydantic's model_json_schema, uncached) would otherwise be regenerated once per
# occurrence. Deliberately NOT a module-level cache — bundle-defined structure classes
# vary per loaded library, so a cross-call cache would serve stale schemas.
- schema_memo: dict[tuple[str, bool], dict[str, Any]] = {}
+ # The key normalizes multiplicity into (is_multiple, fixed_count) rather than carrying the
+ # raw bool|int value: `hash(True) == hash(1)`, so a raw key would collide `Concept[]` with
+ # `Concept[1]` and serve one's schema for the other.
+ schema_memo: dict[tuple[str, bool, int | None], dict[str, Any]] = {}
concept_provider = get_concept_library()
io_contracts: dict[str, PipeIOContract] = {}
for pipe in pipes:
pipe_inputs: dict[str, PipeInputContract] = {}
for var_name, stuff_spec in pipe.inputs.root.items():
- memo_key = (stuff_spec.concept.concept_ref, stuff_spec.is_multiple())
+ memo_key = (
+ stuff_spec.concept.concept_ref,
+ stuff_spec.is_multiple(),
+ fixed_item_count(multiplicity=stuff_spec.multiplicity),
+ )
json_schema = schema_memo.get(memo_key)
if json_schema is None:
try:
@@ -118,14 +154,19 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOCo
)
raise PipeIOContractError(message=msg) from exc
schema_memo[memo_key] = json_schema
+ input_multiplicity, input_item_count = make_io_multiplicity(multiplicity=stuff_spec.multiplicity)
pipe_inputs[var_name] = PipeInputContract(
concept_ref=stuff_spec.concept.concept_ref,
- optional=stuff_spec.presence.is_optional,
+ presence=stuff_spec.presence,
+ multiplicity=input_multiplicity,
+ item_count=input_item_count,
json_schema=json_schema,
)
+ output_multiplicity, output_item_count = make_io_multiplicity(multiplicity=pipe.output.multiplicity)
pipe_output = PipeOutputContract(
concept_ref=pipe.output.concept.concept_ref,
- multiplicity=IOMultiplicity.VARIABLE if pipe.output.is_multiple() else IOMultiplicity.SINGLE,
+ multiplicity=output_multiplicity,
+ item_count=output_item_count,
optional=pipe.output.presence.is_optional,
)
io_contracts[pipe.pipe_ref] = PipeIOContract(inputs=pipe_inputs, output=pipe_output)
diff --git a/subject_grants.toml b/subject_grants.toml
index 851217bd1..4237c9e7c 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -116,10 +116,6 @@ rationale = "Verb-object: collects imports for the pipe inputs; single operand."
param = "representation"
rationale = "Verb-object: formats the representation dict as Python; is_multiple stays keyword."
-["pipelex/builder/runner_code.py::_is_multiple"]
-param = "multiplicity"
-rationale = "Predicate on the multiplicity value; single operand."
-
["pipelex/builder/runner_code.py::generate_runner_code"]
param = "pipe"
rationale = "Verb-object: generates runner code for the pipe; single obvious operand."
diff --git a/tests/data/input_semantics/probe_bundle.mthds b/tests/data/input_semantics/probe_bundle.mthds
index d1e86af7c..29d767fcc 100644
--- a/tests/data/input_semantics/probe_bundle.mthds
+++ b/tests/data/input_semantics/probe_bundle.mthds
@@ -27,7 +27,6 @@ title = { type = "text", description = "PROBE_desc_field_title: required text",
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 }
@@ -58,10 +57,9 @@ 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" }
+# The unknown constraint keys this field once carried are rejected since E7 — they live on in rejected/unknown_structure_field_key.mthds_invalid.
+# The description string is part of the pinned hint-free fingerprints (test_fingerprint_pins.py) and must not change.
+constrained_count = { type = "integer", description = "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys" }
[concept.PlainNote]
description = "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)"
diff --git a/tests/data/input_semantics/rejected/required_with_default.mthds_invalid b/tests/data/input_semantics/rejected/required_with_default.mthds_invalid
new file mode 100644
index 000000000..4dc3b4d36
--- /dev/null
+++ b/tests/data/input_semantics/rejected/required_with_default.mthds_invalid
@@ -0,0 +1,8 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: a field declaring both required = true and default_value is rejected (E3) — a default makes absence legal, which contradicts requiring the field"
+
+[concept.Contradictory]
+description = "Holder of the field the probe bundle's titled_default used to author"
+
+[concept.Contradictory.structure]
+titled_default = { type = "text", description = "PROBE_desc_field_titled_default: required AND default together", required = true, default_value = "PROBE_default_titled" }
diff --git a/tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid b/tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid
new file mode 100644
index 000000000..eef3ed1c3
--- /dev/null
+++ b/tests/data/input_semantics/rejected/unknown_structure_field_key.mthds_invalid
@@ -0,0 +1,11 @@
+domain = "input_semantics_rejected"
+description = "REJECTED probe: unknown keys in a structure-field table are rejected (E7) — the field table's keys are strict, like an input slot table's"
+
+[concept.Constrained]
+description = "Holder of a field carrying hopeful constraint keys the language does not define"
+
+[concept.Constrained.structure]
+constrained_count = { type = "integer", description = "integer carrying unknown constraint keys", minimum = 0, maximum = 100, examples = [
+ 1,
+ 2,
+], unit = "items" }
diff --git a/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py b/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py
index 27dceecb6..a559aa331 100644
--- a/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py
+++ b/tests/integration/pipelex/cli/test_trace_input_semantics_cmd.py
@@ -95,8 +95,13 @@ class TestTraceInputSemantics:
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"]["hint"]["presence"] == "optional"
+ assert do_one["inputs"]["items"]["multiplicity"] == "variable"
assert do_one["inputs"]["items"]["json_schema"]["type"] == "array"
+ # The contract's item_count slot is always on the wire — `null` off the fixed arm, per the
+ # protocol spec (unlike the descriptor, which omits inapplicable slots).
+ assert "item_count" in do_one["inputs"]["items"]
+ assert do_one["inputs"]["items"]["item_count"] is None
# 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)
diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.py
index b91331377..ecd4406ce 100644
--- a/tests/integration/pipelex/pipeline/test_input_form.py
+++ b/tests/integration/pipelex/pipeline/test_input_form.py
@@ -211,7 +211,7 @@ class TestBuildInputForm:
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)."""
+ """Nested fields state the blueprint's facts: defaults (the E3 pair is rejected upstream), 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
@@ -221,9 +221,9 @@ class TestBuildInputForm:
# 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"
+ motto = by_name["motto"]
+ assert motto.required is False, "A defaulted field is not required — the E3 pair is rejected upstream"
+ assert motto.default_value == "PROBE_default_motto"
assert by_name["shorthand_note"].required is True, "A shorthand string field implies required text"
assert by_name["shorthand_note"].kind == FieldKind.TEXT
@@ -285,7 +285,7 @@ class TestBuildInputForm:
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"
+ assert constrained_count.minimum is None, "Unknown blueprint keys are rejected at parse (E7) — a valid bundle cannot carry them"
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."""
@@ -447,6 +447,9 @@ class InputFormConstrainedPayload(StructuredContent):
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")
+ retries: int = Field(default=3, description="PROBE_desc_reflected_retries")
+ strict: bool = Field(default=False, description="PROBE_desc_reflected_strict")
+ tags: list[str] = Field(default_factory=list, description="PROBE_desc_reflected_tags")
class InputFormUnmappablePayload(StructuredContent):
@@ -571,6 +574,20 @@ class TestKindAssignmentTable:
assert ratio.required is False
assert ratio.minimum == 0.0
assert ratio.exclusive_maximum == 1.0
+ assert ratio.default_value is None, "A None default is the optionality artifact, never a default_value"
+
+ retries = by_name["retries"]
+ assert retries.kind == FieldKind.NUMBER
+ assert retries.required is False, "A pydantic default on a reflected class is an authored fact — the field is not required"
+ assert retries.default_value == 3
+
+ strict = by_name["strict"]
+ assert strict.required is False
+ assert strict.default_value is False, "A falsy non-None default is an authored fact — the None guard must not drop it"
+
+ tags = by_name["tags"]
+ assert tags.required is False, "A default_factory makes the field not required"
+ assert tags.default_value is None, "A default_factory has no reportable value — no default_value is fabricated"
async def test_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."""
diff --git a/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py b/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
index f804cadb0..f05cd2d27 100644
--- a/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
+++ b/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
@@ -6,8 +6,9 @@ Covers the two combinations the hosted builder it was ported from never saw:
``allow_signatures=True`` gets an IO-contract entry like any concrete pipe (its declared
contract is exactly what a top-down build needs), keyed by its namespaced ``pipe_ref``.
- **Multiplicity entry shapes** — a single output reports ``multiplicity="single"``, a
- list output (``Concept[]``) reports ``multiplicity="variable"`` with an array JSON Schema
- on list-typed inputs.
+ variable list output (``Concept[]``) reports ``multiplicity="variable"``, and a fixed-count
+ output (``Concept[N]``) reports ``multiplicity="fixed"`` with ``item_count=N``; list-typed
+ inputs carry the same projection plus an array JSON Schema.
The builder runs against the open validation library (`validate_bundle` leaves it loaded on
success), mirroring how the protocol wrapper consumes it.
@@ -21,6 +22,7 @@ from typing import TYPE_CHECKING
import pytest
from pydantic import PydanticUserError
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipeline.exceptions import PipeIOContractError
from pipelex.pipeline.pipe_io_contracts import IOMultiplicity, build_pipe_io_contracts
@@ -63,6 +65,20 @@ description = "Make many items"
inputs = { docs = "Text[]" }
output = "Item[]"
prompt = "Make items from:\\n@docs"
+
+[pipe.make_two]
+type = "PipeLLM"
+description = "Make exactly two items"
+inputs = { docs = "Text[2]" }
+output = "Item[2]"
+prompt = "Make two items from:\\n@docs"
+
+[pipe.make_from_one]
+type = "PipeLLM"
+description = "Make an item from a [1]-declared doc"
+inputs = { docs = "Text[1]" }
+output = "Item"
+prompt = "Make an item from:\\n@docs"
"""
@@ -76,10 +92,10 @@ description = "A verdict"
[pipe.assess]
type = "PipeLLM"
description = "Assess with an optional hint"
-inputs = { doc = "Text", hint = "Text?" }
+inputs = { doc = "Text", hint = "Text?", brief = "Text!" }
output = "Verdict"
prompt = '''
-Assess $doc.
+Assess $doc following $brief.
@?hint
'''
@@ -106,7 +122,7 @@ go = "check"
@pytest.mark.asyncio(loop_scope="class")
class TestBuildPipeIOContracts:
async def test_optional_markers_reported_on_contracts(self, load_empty_library: Callable[[], str]) -> None:
- """A `?`-declared input/output reports optional=True on its contract; plain ones False."""
+ """A `?`-declared input reports presence=optional; plain ones plain; a `?` output optional=True."""
outer_library_id = load_empty_library()
try:
result = await validate_bundle(mthds_contents=[_OPTIONAL_MTHDS])
@@ -115,8 +131,9 @@ class TestBuildPipeIOContracts:
_teardown_validation_library(outer_library_id)
assess = io_contracts["optional_contracts_test.assess"]
- assert assess.inputs["doc"].optional is False
- assert assess.inputs["hint"].optional is True
+ assert assess.inputs["doc"].presence == PresenceMarker.PLAIN
+ assert assess.inputs["hint"].presence == PresenceMarker.OPTIONAL
+ assert assess.inputs["brief"].presence == PresenceMarker.FORCE
assert assess.output.optional is False
gate = io_contracts["optional_contracts_test.gate"]
@@ -131,19 +148,53 @@ class TestBuildPipeIOContracts:
finally:
_teardown_validation_library(outer_library_id)
- assert set(io_contracts) == {"structures_test.make_one", "structures_test.make_many"}
+ assert set(io_contracts) == {
+ "structures_test.make_one",
+ "structures_test.make_many",
+ "structures_test.make_two",
+ "structures_test.make_from_one",
+ }
make_one = io_contracts["structures_test.make_one"]
assert make_one.output.concept_ref == "structures_test.Item"
assert make_one.output.multiplicity == IOMultiplicity.SINGLE
+ assert make_one.output.item_count is None
assert make_one.inputs["doc"].concept_ref == "native.Text"
+ assert make_one.inputs["doc"].multiplicity == IOMultiplicity.SINGLE
+ assert make_one.inputs["doc"].item_count is None
assert make_one.inputs["doc"].json_schema
make_many = io_contracts["structures_test.make_many"]
assert make_many.output.concept_ref == "structures_test.Item"
assert make_many.output.multiplicity == IOMultiplicity.VARIABLE
- # A list-typed input renders an array JSON Schema.
- assert make_many.inputs["docs"].json_schema.get("type") == "array"
+ assert make_many.output.item_count is None
+ assert make_many.inputs["docs"].multiplicity == IOMultiplicity.VARIABLE
+ assert make_many.inputs["docs"].item_count is None
+ # A list-typed input renders an array JSON Schema, unbounded on the variable arm.
+ docs_schema = make_many.inputs["docs"].json_schema
+ assert docs_schema.get("type") == "array"
+ assert "minItems" not in docs_schema
+ assert "maxItems" not in docs_schema
+
+ make_two = io_contracts["structures_test.make_two"]
+ assert make_two.output.multiplicity == IOMultiplicity.FIXED
+ assert make_two.output.item_count == 2
+ assert make_two.inputs["docs"].multiplicity == IOMultiplicity.FIXED
+ assert make_two.inputs["docs"].item_count == 2
+ # The fixed-count input renders a bounded array JSON Schema.
+ two_schema = make_two.inputs["docs"].json_schema
+ assert two_schema.get("type") == "array"
+ assert two_schema.get("minItems") == 2
+ assert two_schema.get("maxItems") == 2
+
+ # A `[1]` input projects to single: no count, no array framing — and the schema memo
+ # must not serve it another arm's schema (the memo key normalizes multiplicity because
+ # `hash(True) == hash(1)` would collide `Text[]` with `Text[1]` under a raw key).
+ make_from_one = io_contracts["structures_test.make_from_one"]
+ assert make_from_one.inputs["docs"].multiplicity == IOMultiplicity.SINGLE
+ assert make_from_one.inputs["docs"].item_count is None
+ one_schema = make_from_one.inputs["docs"].json_schema
+ assert one_schema.get("type") != "array"
async def test_schema_render_failure_converts_to_structured_error(
self,
diff --git a/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py b/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py
index 2c687b116..fbb6bb208 100644
--- a/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py
+++ b/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py
@@ -34,6 +34,23 @@ class TestConceptStructureSpecValidation:
assert spec.type == ConceptStructureSpecFieldType.CONCEPT
assert spec.concept_ref == "myapp.Customer"
+ def test_required_with_default_is_rejected_at_spec_level(self):
+ """The E3 pair is rejected on the authoring surface itself, with the same two-remedies
+ message as the blueprint — a builder agent must not validate green and then die on its
+ own emitted TOML.
+ """
+ with pytest.raises(ValidationError) as exc_info:
+ ConceptStructureSpec(
+ the_field_name="title",
+ description="A title",
+ type=ConceptStructureSpecFieldType.TEXT,
+ required=True,
+ default_value="Untitled",
+ )
+ error_str = str(exc_info.value)
+ assert "required" in error_str
+ assert "default_value" in error_str
+
def test_concept_type_cannot_have_default_value(self):
"""CONCEPT type cannot have default_value set."""
with pytest.raises(ValidationError) as exc_info:
diff --git a/tests/unit/pipelex/builder/concept/test_data.py b/tests/unit/pipelex/builder/concept/test_data.py
index ddd7478dc..9ec2abbc5 100644
--- a/tests/unit/pipelex/builder/concept/test_data.py
+++ b/tests/unit/pipelex/builder/concept/test_data.py
@@ -110,7 +110,6 @@ class ConceptBlueprintTestCases:
description="Age",
type=ConceptStructureSpecFieldType.INTEGER,
required=True,
- default_value=18,
),
"active": ConceptStructureSpec(
the_field_name="active",
@@ -135,7 +134,6 @@ class ConceptBlueprintTestCases:
description="Age",
type=ConceptStructureBlueprintFieldType.INTEGER,
required=True,
- default_value=18,
),
"active": ConceptStructureBlueprint(
description="Active status",
diff --git a/tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py b/tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py
index 6d29ef882..688777d14 100644
--- a/tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py
+++ b/tests/unit/pipelex/builder/operations/test_concept_spec_to_toml.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import json
+import tomllib
from typing import Any
from pipelex.builder.concept.concept_spec import ConceptStructureSpec, ConceptStructureSpecFieldType
@@ -11,6 +12,8 @@ from pipelex.builder.operations.concept_ops import (
parse_concept_spec,
structure_field_to_dict,
)
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint
class TestConceptSpecToToml:
@@ -58,7 +61,7 @@ class TestConceptSpecToToml:
default_value=0,
)
result = structure_field_to_dict(field_spec)
- assert result["default"] == 0
+ assert result["default_value"] == 0, "The language key is default_value — `default` evaporates on re-load (E8)"
def test_concept_field_with_concept_ref(self) -> None:
field_spec = ConceptStructureSpec(
@@ -102,7 +105,7 @@ class TestConceptSpecToToml:
)
result = structure_field_to_dict(field_spec)
assert result["choices"] == ["active", "inactive", "pending"]
- assert result["default"] == "pending"
+ assert result["default_value"] == "pending"
# -- concept_spec_to_toml ---------------------------------------------
@@ -218,6 +221,31 @@ class TestConceptSpecToToml:
toml_output = concept_spec_to_toml(concept_spec)
assert "structure" not in toml_output
+ def test_builder_toml_roundtrips_through_blueprint_with_default(self) -> None:
+ """Write-then-validate round trip (E8): a builder-authored default must survive re-load as a
+ blueprint — the builder once wrote the key `default`, which the language does not read, so
+ the fact evaporated silently. E7's forbid now turns any recurrence into a hard failure.
+ """
+ spec_data: dict[str, Any] = {
+ "concept_code": "Counter",
+ "description": "A counter with a default",
+ "structure": {
+ "count": {"type": "integer", "description": "Number of items", "default_value": 7},
+ "label": {"type": "text", "description": "A label", "required": True},
+ },
+ }
+ concept_spec = parse_concept_spec(spec_data)
+ toml_output = concept_spec_to_toml(concept_spec)
+ reloaded = tomllib.loads(toml_output)
+ blueprint = ConceptBlueprint.model_validate(reloaded["concept"]["Counter"])
+ assert isinstance(blueprint.structure, dict)
+ count_field = blueprint.structure["count"]
+ assert isinstance(count_field, ConceptStructureBlueprint)
+ assert count_field.default_value == 7, "The authored default must survive the write-then-validate loop"
+ label_field = blueprint.structure["label"]
+ assert isinstance(label_field, ConceptStructureBlueprint)
+ assert label_field.required is True
+
def test_no_refines_omits_refines(self) -> None:
spec_data: dict[str, Any] = {
"concept_code": "Standalone",
diff --git a/tests/unit/pipelex/builder/test_runner_generator.py b/tests/unit/pipelex/builder/test_runner_generator.py
index 539add142..42bbf4539 100644
--- a/tests/unit/pipelex/builder/test_runner_generator.py
+++ b/tests/unit/pipelex/builder/test_runner_generator.py
@@ -58,7 +58,7 @@ class TestConceptGenerateInputRepresentationJson:
result, _ = concept.render_concept_representation(
structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept),
output_format=ConceptRepresentationFormat.JSON,
- is_multiple=True,
+ multiplicity=True,
)
assert result["concept"] == "native.Document"
assert "content" in result
@@ -114,9 +114,9 @@ class TestConceptGenerateInputRepresentationPython:
result, imports = concept.render_concept_representation(
structure_class=ConceptLibrary.make_empty().get_structure_class(concept=concept),
output_format=ConceptRepresentationFormat.PYTHON,
- is_multiple=True,
+ multiplicity=True,
)
- # For Python format, is_multiple doesn't wrap content (caller handles it)
+ # For Python format, a multiple multiplicity doesn't wrap content (caller handles it)
assert result["concept"] == "native.Document"
assert "DocumentContent" in result["content"]
assert "DocumentContent" in imports
diff --git a/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py
new file mode 100644
index 000000000..7a03fed6a
--- /dev/null
+++ b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_extra_keys.py
@@ -0,0 +1,60 @@
+"""Unknown keys in a structure-field table are rejected (S2 E7) — the field table's keys are
+strict, exactly like an input slot table's, while hint content stays lenient (intent-hints.md).
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint
+
+
+class TestConceptStructureBlueprintExtraKeys:
+ @pytest.mark.parametrize(
+ ("extra_key", "extra_value"),
+ [
+ ("minimum", 0),
+ ("maximum", 100),
+ ("examples", [1, 2]),
+ ("unit", "items"),
+ ("hint", {"intent": "label"}),
+ ("defalt_value", "typo'd default"),
+ ],
+ )
+ def test_unknown_field_key_is_rejected(self, extra_key: str, extra_value: object) -> None:
+ """A hopeful or typo'd key on a structure field must fail loudly, never drop silently."""
+ with pytest.raises(ValidationError) as exc_info:
+ ConceptStructureBlueprint.model_validate({"description": "a field", "type": "integer", extra_key: extra_value})
+ assert extra_key in str(exc_info.value)
+
+ def test_unknown_field_key_is_rejected_through_concept_blueprint(self) -> None:
+ """The rejection reaches the concept blueprint's structure table, the authoring path."""
+ with pytest.raises(ValidationError):
+ ConceptBlueprint.model_validate(
+ {
+ "description": "a concept",
+ "structure": {"count": {"type": "integer", "description": "a count", "minimum": 0}},
+ }
+ )
+
+ def test_known_keys_still_accepted(self) -> None:
+ field = ConceptStructureBlueprint.model_validate(
+ {
+ "description": "a field",
+ "type": "integer",
+ "required": True,
+ "hints": {"intent": "quantity"},
+ }
+ )
+ assert field.required is True
+
+ def test_unknown_hint_content_keys_stay_lenient(self) -> None:
+ """The strictness boundary is H2's: the field table's keys are strict, hint CONTENT is not."""
+ field = ConceptStructureBlueprint.model_validate(
+ {
+ "description": "a field",
+ "type": "text",
+ "hints": {"made_up_hint_key": "preserved"},
+ }
+ )
+ assert field.hints == {"made_up_hint_key": "preserved"}
diff --git a/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_required_default.py b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_required_default.py
new file mode 100644
index 000000000..22484f664
--- /dev/null
+++ b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_structure_blueprint_required_default.py
@@ -0,0 +1,46 @@
+"""`required = true` + `default_value` on one structure field is rejected (S2 E3) — a default
+makes absence legal, which contradicts requiring the field. Two contradictory instructions on
+one field is an authoring error, and it must fail loudly, never tiebreak silently.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint
+
+
+class TestConceptStructureBlueprintRequiredDefault:
+ @pytest.mark.parametrize(
+ "field_table",
+ [
+ {"description": "a field", "type": "text", "required": True, "default_value": "hello"},
+ {"description": "a field", "type": "integer", "required": True, "default_value": 42},
+ {"description": "a field", "choices": ["one", "two"], "required": True, "default_value": "one"},
+ ],
+ )
+ def test_required_with_default_is_rejected(self, field_table: dict[str, object]) -> None:
+ with pytest.raises(ValidationError) as exc_info:
+ ConceptStructureBlueprint.model_validate(field_table)
+ assert "required" in str(exc_info.value)
+ assert "default_value" in str(exc_info.value)
+
+ def test_rejection_reaches_the_concept_blueprint(self) -> None:
+ """The rejection fires on the authoring path, through the concept's structure table."""
+ with pytest.raises(ValidationError):
+ ConceptBlueprint.model_validate(
+ {
+ "description": "a concept",
+ "structure": {"title": {"type": "text", "description": "a title", "required": True, "default_value": "Untitled"}},
+ }
+ )
+
+ def test_default_without_required_still_accepted(self) -> None:
+ field = ConceptStructureBlueprint.model_validate({"description": "a field", "type": "text", "default_value": "hello"})
+ assert field.required is False
+ assert field.default_value == "hello"
+
+ def test_required_without_default_still_accepted(self) -> None:
+ field = ConceptStructureBlueprint.model_validate({"description": "a field", "type": "text", "required": True})
+ assert field.required is True
+ assert field.default_value is None
diff --git a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_required_default_invariant.py b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_required_default_invariant.py
new file mode 100644
index 000000000..ce027f37f
--- /dev/null
+++ b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_required_default_invariant.py
@@ -0,0 +1,25 @@
+"""The generator's required+default invariant (S2 E3): the blueprint validator rejects the pair
+upstream, so a field carrying both reaching the generator is a bug — it must raise, not silently
+drop the required marker by parameter ordering (the accident S1 measured). The pair is smuggled
+past validation with `model_construct`, exactly how a future bypass would reach the generator.
+"""
+
+import pytest
+
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType
+from pipelex.core.concepts.structure_generation.exceptions import ConceptStructureGeneratorError
+from pipelex.core.concepts.structure_generation.generator import StructureGenerator
+
+
+class TestStructureGeneratorRequiredDefaultInvariant:
+ def test_required_with_default_raises_instead_of_dropping_required(self) -> None:
+ contradictory_field = ConceptStructureBlueprint.model_construct(
+ description="required AND default together",
+ type=ConceptStructureBlueprintFieldType.TEXT,
+ required=True,
+ default_value="Untitled",
+ )
+ with pytest.raises(ConceptStructureGeneratorError, match="required AND carries default_value"):
+ StructureGenerator().generate_from_structure_blueprint(
+ class_name="ContradictoryModel", structure_blueprint={"titled_default": contradictory_field}
+ )
diff --git a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
index dae071d5f..0eb809ea2 100644
--- a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
+++ b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
@@ -508,12 +508,12 @@ class TestIncludeOptionalParameter:
# =============================================================================
-# Tests for SCHEMA format with is_multiple parameter
+# Tests for SCHEMA format with the multiplicity parameter
# =============================================================================
class TestSchemaRepresentationWithMultiple:
- """Test schema representation with is_multiple parameter."""
+ """Test schema representation with the multiplicity parameter."""
def test_schema_single_item(self) -> None:
"""Schema for single item returns the JSON schema directly."""
@@ -527,7 +527,7 @@ class TestSchemaRepresentationWithMultiple:
result, imports = concept.render_concept_representation(
structure_class=SimpleContent,
output_format=ConceptRepresentationFormat.SCHEMA,
- is_multiple=False,
+ multiplicity=None,
)
assert result["concept"] == "test.SimpleContent"
@@ -549,7 +549,7 @@ class TestSchemaRepresentationWithMultiple:
result, imports = concept.render_concept_representation(
structure_class=SimpleContent,
output_format=ConceptRepresentationFormat.SCHEMA,
- is_multiple=True,
+ multiplicity=True,
)
assert result["concept"] == "test.SimpleContent"
@@ -575,7 +575,7 @@ class TestSchemaRepresentationWithMultiple:
result, _ = concept.render_concept_representation(
structure_class=ContentWithNestedClass,
output_format=ConceptRepresentationFormat.SCHEMA,
- is_multiple=True,
+ multiplicity=True,
)
assert result["concept"] == "test.ContentWithNestedClass"
@@ -587,6 +587,87 @@ class TestSchemaRepresentationWithMultiple:
assert items_schema["type"] == "object"
assert "properties" in items_schema
+ def test_schema_title_and_description_are_the_concept_facts(self) -> None:
+ """The schema's top-level title is the concept ref and its description the concept's
+ authored description — injected at the render, overriding whatever the (possibly shared)
+ structure class carries.
+ """
+ concept = Concept(
+ code="SimpleContent",
+ domain_code="test",
+ description="The authored concept description",
+ structure_class_name="SimpleContent",
+ )
+
+ result, _ = concept.render_concept_representation(
+ structure_class=SimpleContent,
+ output_format=ConceptRepresentationFormat.SCHEMA,
+ )
+
+ assert result["content"]["title"] == "test.SimpleContent"
+ assert result["content"]["description"] == "The authored concept description"
+
+ def test_schema_array_wrap_keeps_identity_on_items(self) -> None:
+ """A variable-length list wraps in a bare array — identity on items, no count bounds."""
+ concept = Concept(
+ code="SimpleContent",
+ domain_code="test",
+ description="The authored concept description",
+ structure_class_name="SimpleContent",
+ )
+
+ result, _ = concept.render_concept_representation(
+ structure_class=SimpleContent,
+ output_format=ConceptRepresentationFormat.SCHEMA,
+ multiplicity=True,
+ )
+
+ array_schema = result["content"]
+ assert array_schema["type"] == "array"
+ assert "minItems" not in array_schema
+ assert "maxItems" not in array_schema
+ assert array_schema["items"]["title"] == "test.SimpleContent"
+ assert array_schema["items"]["description"] == "The authored concept description"
+
+ def test_schema_fixed_count_emits_min_and_max_items(self) -> None:
+ """A fixed count [N] emits minItems and maxItems = N on the array wrap."""
+ concept = Concept(
+ code="SimpleContent",
+ domain_code="test",
+ description="Test concept",
+ structure_class_name="SimpleContent",
+ )
+
+ result, _ = concept.render_concept_representation(
+ structure_class=SimpleContent,
+ output_format=ConceptRepresentationFormat.SCHEMA,
+ multiplicity=3,
+ )
+
+ array_schema = result["content"]
+ assert array_schema["type"] == "array"
+ assert array_schema["minItems"] == 3
+ assert array_schema["maxItems"] == 3
+ assert array_schema["items"]["type"] == "object"
+
+ def test_schema_fixed_count_of_one_stays_single(self) -> None:
+ """[1] is single: no array wrap, no bounds."""
+ concept = Concept(
+ code="SimpleContent",
+ domain_code="test",
+ description="Test concept",
+ structure_class_name="SimpleContent",
+ )
+
+ result, _ = concept.render_concept_representation(
+ structure_class=SimpleContent,
+ output_format=ConceptRepresentationFormat.SCHEMA,
+ multiplicity=1,
+ )
+
+ assert result["content"]["type"] == "object"
+ assert result["content"]["title"] == "test.SimpleContent"
+
# =============================================================================
# Tests for NumberContent (native Number concept)
diff --git a/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py b/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py
new file mode 100644
index 000000000..2a52b8130
--- /dev/null
+++ b/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py
@@ -0,0 +1,41 @@
+"""Unit tests for the multiplicity projection helpers.
+
+These two helpers are the normalization every consumer of `VariableMultiplicity | None`
+shares: list-or-not, and the exact count when (and only when) the multiplicity is a fixed
+count above one. The bool/int cases matter because `True == 1` in Python — the helpers must
+keep `[]` (True) and `[1]` (1) distinct.
+"""
+
+import pytest
+
+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity, fixed_item_count, is_multiple_multiplicity
+
+
+class TestMultiplicityHelpers:
+ @pytest.mark.parametrize(
+ ("multiplicity", "expected"),
+ [
+ (None, False),
+ (False, False),
+ (True, True),
+ (1, False),
+ (2, True),
+ (10, True),
+ ],
+ )
+ def test_is_multiple(self, multiplicity: VariableMultiplicity | None, expected: bool):
+ assert is_multiple_multiplicity(multiplicity=multiplicity) is expected
+
+ @pytest.mark.parametrize(
+ ("multiplicity", "expected"),
+ [
+ (None, None),
+ (False, None),
+ (True, None),
+ (1, None),
+ (2, 2),
+ (10, 10),
+ ],
+ )
+ def test_fixed_item_count(self, multiplicity: VariableMultiplicity | None, expected: int | None):
+ assert fixed_item_count(multiplicity=multiplicity) == expected
diff --git a/tests/unit/pipelex/libraries/test_fingerprint_pins.py b/tests/unit/pipelex/libraries/test_fingerprint_pins.py
index 93202d050..0836810d5 100644
--- a/tests/unit/pipelex/libraries/test_fingerprint_pins.py
+++ b/tests/unit/pipelex/libraries/test_fingerprint_pins.py
@@ -18,9 +18,12 @@ from pipelex.mthds_parsing.parser import MthdsParser
_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"
-# Computed on the probe bundle at the base of feature/Engine-hints (models without hints fields).
-_PINNED_CONTENT_FINGERPRINT = "32d3b801c1124334b5415c77f7e501b41890dbeb6bd881a76ff10c41a1fa1c14"
-_PINNED_NORMALIZED_FINGERPRINT = "c6265a638147a5dcc6d9b22d24751c6579d46f7d8d29220ff443265c896fec28"
+# Computed on the probe bundle at the base of feature/Engine-hints (models without hints fields),
+# recomputed once on feature/Enrich when the bundle itself changed content: its `titled_default`
+# field moved to a rejected/ fixture (E3 outlaws the required+default pair) — a fixture-content
+# change, not a model leak, so the recompute is the legitimate exception to the note above.
+_PINNED_CONTENT_FINGERPRINT = "053d3ce1a1963feffcea1aaea21e6329a7d2d2371cecdb92eb4a1e51269b0043"
+_PINNED_NORMALIZED_FINGERPRINT = "0a2aac25fe00afb191d52eb12bed7a778a4cab6687bbd1c0455b016e7eae1847"
_MTHDS_TEST_VERSION = "0.0.0-test"
diff --git a/tests/unit/pipelex/mthds_parsing/test_parser_rejected_structure_fields.py b/tests/unit/pipelex/mthds_parsing/test_parser_rejected_structure_fields.py
new file mode 100644
index 000000000..09433fa59
--- /dev/null
+++ b/tests/unit/pipelex/mthds_parsing/test_parser_rejected_structure_fields.py
@@ -0,0 +1,28 @@
+"""Full-bundle parsing of the rejected structure-field probes: the E3 required+default pair and
+E7 unknown field-table keys must fail the `.mthds` parse itself with an error naming the offending
+keys — not just the pydantic model layer, which the blueprint unit tests already pin.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.mthds_parsing.exceptions import MthdsParserError
+from pipelex.mthds_parsing.parser import MthdsParser
+
+_REJECTED_DIR = Path(__file__).parents[3] / "data" / "input_semantics" / "rejected"
+
+
+class TestRejectedStructureFieldParsing:
+ def test_required_with_default_fails_the_parse_naming_the_pair(self):
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_REJECTED_DIR / "required_with_default.mthds_invalid")
+ message = str(exc_info.value)
+ assert "required" in message
+ assert "default_value" in message
+
+ def test_unknown_structure_field_key_fails_the_parse_naming_the_key(self):
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(bundle_path=_REJECTED_DIR / "unknown_structure_field_key.mthds_invalid")
+ message = str(exc_info.value)
+ assert "minimum" in message
diff --git a/wip/enrich/deferred.md b/wip/enrich/deferred.md
new file mode 100644
index 000000000..a84c5edb1
--- /dev/null
+++ b/wip/enrich/deferred.md
@@ -0,0 +1,23 @@
+# S2 "Enrich" — deferred findings
+
+Items surfaced by the pre-landing review of PR #1149 that are real but not clear-cut wins to fix on the branch. Each needs a ruling or a design choice; none blocks the merge.
+
+## 1. Non-JSON-serializable reflected default can crash report serialization far from its cause
+
+`pipelex/pipeline/input_form.py` (`_with_reflected_constraints`) stamps `field_info.default` raw into the descriptor's `default_value: Any` slot. A registered hand-written class whose field default holds a non-JSON-serializable value turns a valid bundle's report dump into a `PydanticSerializationError` at serialization time, far from the offending class. Exposure is limited by `reflect_structure_class`'s annotation gating (only mappable annotations reach reflection at all). The candidate remedy is to coerce via `pydantic_core.to_jsonable_python` and drop the fact on failure, per the faithful-or-absent rule — but silently dropping an authored fact versus failing loudly is a design choice that deserves a ruling, not a speculative guard.
+
+## 2. `_peel_multiplicity` rules `[1]` the opposite way from the rest of the chain
+
+`pipelex/core/memory/input_shaper.py` (`_peel_multiplicity`) treats a fixed count of 1 as a one-item **list**, while the S2 chain — `variable_multiplicity.py` helpers, the wire contract, the schema render, and `docs/under-the-hood/input-form-descriptor.md` — all rule `[1]` **single** (no list framing). So a `[1]` slot's published schema says single object while the runtime shaper frames the payload as a list. Pre-existing (the file is untouched by the branch), made visible by the new ruling; each side's docstring claims its ruling as universal. Cross-surface semantic decision: either the shaper adopts the `[1]`-is-single ruling or the divergence is documented as intentional at the memory boundary.
+
+## 3. `_with_reflected_constraints` name/content drift
+
+The function now stamps presence and default facts as well as constraints; the docstring says so but the name and the `constraints` dict variable don't. Rename-only suggestion (e.g. `_with_reflected_facts`) — not worth churn on its own; fold into the next touch of the module.
+
+## 4. Contract builder normalizes multiplicity twice per input
+
+`pipelex/pipeline/pipe_io_contracts.py` — the schema-memo key hand-normalizes `(is_multiple, fixed_count)` with the `hash(True) == hash(1)` caveat comment, while `make_io_multiplicity` computes the same projection a few lines later. Keying the memo on the `(IOMultiplicity, item_count)` pair from a single up-front `make_io_multiplicity` call would drop both the duplication and the caveat. Current code is correct (all four arms verified; the collision trap is genuinely closed and now pinned by a test) — simplification only.
+
+## 5. `rejected/` fixture corpus is mostly inert
+
+Four of the pre-existing `tests/data/input_semantics/rejected/` fixtures (`default_on_concept_field`, `multiple_refines`, `non_string_choices`, `refines_plus_structure`) are loaded by no test — the directory grew as a documentation corpus with only `per_input_description` (and now the two S2 fixtures, wired on this branch) exercised through the parser. A parametrized parser-level harness sweeping the whole directory would keep fixtures from rotting, but each fixture must first be confirmed to actually fail today's parse (some may document aspirational rejections) — audit before wiring.
diff --git a/wip/enrich/design.md b/wip/enrich/design.md
new file mode 100644
index 000000000..209fbdf9b
--- /dev/null
+++ b/wip/enrich/design.md
@@ -0,0 +1,130 @@
+# S2 — Enrich: closing the engine-side semantics gaps (design)
+
+**Status:** design written 2026-08-23, opening milestone S2 of the input-form roadmap (`../wip/devx/input-form-roadmap.md` → Track S), on branch `feature/Enrich`. Inputs: the S1 findings ([`../input-semantics/findings.md`](../input-semantics/findings.md) — the worklist is its §A, ranked in §E, with the blast-radius catalogue in §D), the frozen descriptor spec (`../docs/specs/mthds-input-form-descriptor.md`), the D2 deriver (`pipelex/pipeline/input_form.py`), and H2's hint machinery, all on `dev` since PRs #1147/#1148. Per the roadmap: *"Richer schemas flow through the existing wire with zero client changes, and immediately improve agent tool-calling and docs as well as forms. Gate: the audit's engine-side list is closed; enriched schemas visible on `/validate`."*
+
+---
+
+## 1. Where S2 stands after D2 and H2
+
+The S1 worklist was written before the descriptor existed. D2 has since landed the reference derivation, and the descriptor already carries most of what §A's "who guesses" columns were missing: `concept_ref` on every concept-typed node (E1's form-side ask), the `refines` chain (E2's), three-valued `presence` (E5's), `item_count` for fixed `[N]` multiplicity (E4's), authored `default_value` reported faithfully beside `required` (E3's descriptor half), and normalized one-member `choices` (E10's descriptor half, pinned by the spec). M1 will delete the app-side guessing by swapping the kernel onto that descriptor.
+
+So S2 is **not** "make the form possible" — that is done. S2 is what the roadmap always said it was, now sharpened by the descriptor's existence: make the authored facts live on the **contract channel** — the `json_schema`, the `pipe_io_contracts` shape, the runtime validation behavior, and the authoring loop — and make silent drops loud. The consumers this serves are the ones the descriptor deliberately does not: agent tool-calling, docs, ajv-style payload validation, the SDKs' structural surface, and the author who needs to know their key was read.
+
+## 2. The doctrine that sorts every entry
+
+The workspace's presentation-vs-contract doctrine decides where each fix goes, and it resolves every ambiguity in the worklist:
+
+- A fact about **what the caller submits** — multiplicity, presence, payload constraints, defaults, required-ness, descriptions of payload fields — is a contract fact. It belongs in `json_schema` and on the contract's structured fields, and machine consumers must be able to read it there without the descriptor.
+- A fact about **how to render** — kinds, gating, hints, flattening — is presentation. It lives on the descriptor, and S2 does not duplicate it onto the contract channel.
+- Where both channels carry the same fact (a default, a fixed count), they derive from the same crate in the same window, so they cannot disagree — the D2 precedent.
+
+One consequence stated up front: the roadmap's "zero client changes" describes the schema enrichments, which are additive inside an existing `json_schema` value. The contract reshaping (E5, E9) is a deliberate protocol change — spec-first, breaking, coordinated at the release cascade like everything else in this program. The two kinds of change are separated into their own phases below so the free half never waits on the coordinated half.
+
+## 3. Dispositions, entry by entry
+
+| Entry | Disposition |
+|---|---|
+| E1 concept identity | Schema: top-level `title` becomes the concept ref. Nested identity: ruled closed by the descriptor. |
+| E2 refinement chain | Ruled closed by the descriptor. No schema change. |
+| E3 required + default | **Decision:** reject the pair at validation. Language sentence to `mthds`, engine validator, spec touch-up. |
+| E4 `[N]` multiplicity | Schema: `minItems`/`maxItems` on the array wrap; multiplicity threaded through render and memo key. |
+| E5 `!` on the contract | Contract: three-valued `presence` replaces the input's `optional`. Protocol change. |
+| E6 missing descriptions | Schema: top-level `description` is the concept's authored description, by rule; native classes gain docstrings. |
+| E7 silent extras | `extra="forbid"` on `ConceptStructureBlueprint`; language sentence to `mthds`; `mthds_schema.json` regen. |
+| E8 builder writes `default` | One-line fix + round-trip test; delivers the standing inbox item. |
+| E9 multiplicity on contract | Contract: `multiplicity` goes three-valued (`single`/`variable`/`fixed`) with `item_count`. Protocol change, shared with E5. |
+| E10 `const` vs `enum` | Descriptor half closed by D2. Schema stays pydantic-canonical; `const` documented as part of the contract. |
+
+### E6 — the description rule (with E1's title riding along)
+
+The rule that closes E6 for every concept species at once: **the schema's top-level `description` is the concept's authored description, injected at the render.** The injection point is `_render_schema_representation` (`pipelex/core/concepts/concept.py:193`), which already receives the resolved class and knows `self.concept_ref`. For a generated class this is a no-op (its docstring *is* the concept description); for a class-backed concept it injects the authored fact the class cannot carry (several concepts may back onto one class, so the concept's description can never live on the class); for a native concept as a direct input it injects the pinned native blueprint's description — the same source the descriptor already reads via `make_pinned_native_blueprint`.
+
+Separately and additively, the native content classes that lack docstrings (`TextContent`, `ImageContent`, `DocumentContent`, `PageContent`, `NumberContent`, `HtmlContent`, `YesNoContent` — S1 measured only `DateContent`/`TimeContent` carrying one) **gain docstrings**. This serves the consumers the render never touches: the live class is handed to instructor as the structured-output response model, so a docstring reaches the provider-side schema on every LLM structured generation.
+
+E1's schema half rides the same render seam: the top-level `title`, today the mangled generated-class name that the app deliberately discards (`pipelex-app/src/lib/run-form/field-model.ts:210-215`), becomes the concept ref. Nested concept identity stays descriptor-only: renaming `$defs` keys would mean rewriting every `$ref` in the emitted schema, and after M1 no consumer derives a form from the schema — the descriptor's per-node `concept_ref` is the answer to that question. Same ruling for E2: JSON Schema has no inheritance vocabulary, the descriptor's `refines` list is the fact's home, and the schema stays untouched.
+
+### E4 — fixed multiplicity reaches the schema
+
+`render_stuff_spec` collapses multiplicity to `is_multiple()` before the render (`pipelex/core/pipes/stuff_spec/stuff_spec.py:58`), and the contract memo key does the same (`pipelex/pipeline/pipe_io_contracts.py:104`), which is why `Gadget[2]` renders as a bare `array`. The fix threads the real multiplicity value through: `render_concept_representation` takes the multiplicity (not a boolean), the array wrap in `_render_schema_representation` emits `minItems: N` and `maxItems: N` when the count is fixed, and the memo key becomes `(concept_ref, multiplicity)` so two different counts of the same concept no longer share one cached schema. A variable `[]` slot gets neither bound — the language cannot yet say "at least one" (S1 §B), and inventing a minimum here would contradict the gating rationale the descriptor spec records.
+
+### E5 + E9 — the contract learns presence and multiplicity (protocol change)
+
+These are the two entries whose fix is a wire-shape change on `pipe_io_contracts`, and they land together because they touch the same models and the same spec section. The doctrine argument for doing them despite the descriptor: presence and multiplicity are facts about *what the caller submits* — contract facts. Today the app rebuilds `[]` from `json_schema.type === "array"` in three drifted places with one documented gating bug (S1 E9), and a graph or lint surface that wants to show where `!` assertions live has no channel at all (S1 E5). Non-form consumers should not need a presentation view to learn a contract fact.
+
+Proposed shape, mirroring the descriptor's vocabulary so the two surfaces share words (the D1 naming discipline):
+
+- `PipeInputContract`: `presence: "plain" | "optional" | "force"` **replaces** `optional` (`pipelex/pipeline/pipe_io_contracts.py:45-53`). `optional` is exactly `presence == "optional"` — keeping both would be two spellings of one fact, the drift pattern S1 catalogued in the app.
+- `PipeInputContract` and `PipeOutputContract`: `multiplicity` becomes three-valued — `single` / `variable` / `fixed` — with `item_count: int` present exactly when `fixed` (today `IOMultiplicity` deliberately reports a fixed count as `variable`, per its own docstring at `pipe_io_contracts.py:34-42`; that ruling is what E4/E9 revisits). The input contract, which today has no multiplicity field at all, gains both.
+- `PipeOutputContract` keeps `optional` as-is: `!` is rejected on outputs (`pipelex/pipe_machinery/pipe_blueprint.py:335`), so the output's presence is genuinely two-valued and the existing spelling is honest.
+
+This is spec-first work: the protocol spec pins the current shape and prose (`../docs/specs/pipelex-mthds-protocol.md:48` — the `pipe_io_contracts` row — and the "Optional IO contracts and liftable pipes" section), and the conformance side is `conformance/tests/pipelex_api/test_validate_optionals.py`, already skip-gated until the pinned runtime speaks optionals — the reshaped assertions inherit that gate and arm at the cascade like everything else. Spec and conformance move in the same change (`make check-spec-links` in `conformance/`). The TS protocol types (`mthds-js/src/protocol/models.ts`) and the second engine's contract emission (`pipelex-js`, `@pipelex/runtime`) follow at the cascade — cross-repo, filed as inbox items at S2 close, listed in §8. Changelog: breaking.
+
+### E3 — `required = true` + `default_value` is rejected (decision to ratify)
+
+The audit measured the pair validating green and the generator silently dropping the required-ness by parameter ordering (`pipelex/core/concepts/structure_generation/generator.py:307-313`). The descriptor spec deliberately did not enshrine the accident and delegated the emission decision to engine work (spec → "Facts over emission accidents"). The two candidate rulings:
+
+- **Reject the pair at blueprint validation** — the recommendation. `default_value`'s measured meaning is "applied on absence at validation" (S1 §C), which makes absence legal, which contradicts `required`'s "must be present in the payload". Two contradictory instructions on one field is an authoring error, and the workspace answer to an authoring error is a loud validation failure, not a silent tiebreak.
+- *Define the pair* (required advertises, default fills) — rejected here: it would split what the schema advertises from what validation does, and an author wanting "prefill but make the user confirm" is asking a presentation question, which is hint/`examples` territory, not `default_value`'s.
+
+What the ruling touches: a model validator on `ConceptStructureBlueprint` rejecting the pair; the generator's accidental branch becomes unreachable and is replaced by an explicit invariant; the mthds format spec gains the validation-rule sentence (its rules list at `mthds/docs/spec/mthds-format.md:179-188` addresses adjacent combinations but not this one) — cross-repo, via inbox; the descriptor spec's `default_value` row retires its "may carry both `required: true` and a `default_value`" sentence (the pair can no longer reach a descriptor — the row's "reporting authored intent, not the accident" framing is what made the sentence true, and rejection upstream makes it vacuous); the probe bundle's `titled_default` field (`tests/data/input_semantics/probe_bundle.mthds:30` — the only authored instance of the pair anywhere in the fixtures or corpus, measured by sweep) moves to a `rejected/` fixture. Changelog: breaking.
+
+### E7 + E8 — the authoring loop stops lying
+
+**E7:** `extra="forbid"` on `ConceptStructureBlueprint` (`pipelex/core/concepts/concept_structure_blueprint.py:50`), closing the asymmetry S1 called stark — a typo on a concept fails loudly while a typo on a field dies silently. H2 raised the stakes: `hints` is now a known key, so a typo'd `hint = {...}` is silently dropped authored intent today. The strictness boundary is exactly H2's: the field table's *keys* are strict; hint *content* stays lenient (unknown hint keys warn and are preserved — that rule is untouched). Knock-ons: the mthds format spec's structure-field key table (`mthds/docs/spec/mthds-format.md:148-158`) needs the sentence its input-slot twin already has ("An unknown key in an input slot table MUST be rejected", `mthds-format.md:304`) — cross-repo, via inbox, engine leading the spec by one release exactly as H2 did; `mthds_schema.json` regenerates (`make gms` — structure-field objects flip to `additionalProperties: false`), and its propagation rides the already-filed release-time sync (`../wip/inbox/2026-08-23-workspace-hints-corpus-and-schema-sync-at-release.md` — S2 ships in the same release as H2, so the filed item covers both); fixtures and corpus get swept for hopeful extras before the flip (the S1 sweep found the hopeful keys only in the probe bundle, but the sweep must be re-run at implementation time). Changelog: breaking.
+
+**E8:** the builder writes the TOML key `default` where the language reads `default_value` (`pipelex/builder/operations/concept_ops.py:115-116` — still live, verified on `feature/Enrich`), so a builder-authored default evaporates on re-load. One-line fix plus a write-then-validate round-trip test; E7's forbid turns any recurrence of this bug class into a hard failure instead of silent loss. This delivers the standing inbox item `../wip/inbox/2026-08-21-pipelex-builder-default-key-dropped.md` — remove it from the queue at close.
+
+### E10 — the schema stays canonical, and says so
+
+The descriptor half is closed: D2's deriver normalizes pydantic's one-member-`Literal`-as-`const` quirk into a one-member `choices` list, pinned by the descriptor spec. For the schema channel the ruling is **no render mutation**: `const` is valid JSON Schema, ajv reads it, and rewriting pydantic's canonical output would break the measured hop-3-to-hop-5 losslessness that S1 called worth repeating — the property that makes the whole chain auditable — and would hand the second engine's schema emitters a divergence to chase. Instead the protocol spec's `pipe_io_contracts` row gains one sentence documenting that `json_schema` is pydantic-canonical, single-choice enums included (`const`, no `enum` array), so a schema consumer reads it as contract rather than discovering it as a quirk. The app's form path stops reading the schema at M1, which retires the one consumer that mishandled it.
+
+### The D2 deferral folds in: reflected defaults are authored facts (decision to ratify)
+
+D2 parked a decision (`../input-semantics/deferred-descriptor-reflection-and-roundtrip.md`): a reflected class field with a pydantic default (`count: int = Field(default=0)`) lands in the descriptor as `required: true` with no `default_value`, because `native_expansion` derives required-ness from the annotation only. The recommendation is to rule **a pydantic default on a reflected class is an authored fact** — the class author wrote it, validation applies it on absence exactly like a blueprint `default_value`, and the descriptor claiming `required: true` for such a field is today's actual dishonesty. With E3's rejection ruled, the two stay consistent: `field_info.is_required()` is the single source of truth for the flag, and a defaulted field is not required — the same invariant the blueprint side now enforces loudly. Mechanically it is the one-function change the deferral note describes (`_with_reflected_constraints` in `pipelex/pipeline/input_form.py`, reading `field_info.is_required()` and `field_info.default`), plus a row in the kind-assignment table's tests. The deferral note's second item (the wire model's `datetime` round-trip alias) stays parked for D4, as ruled there.
+
+## 4. Blast radius
+
+- **Do not touch the wording of `DocumentContent.url`'s field description in S2.** The app's dropzone matcher still keys on the `"document url"` substring (S1 §D); its retirement is M1's, and the half-dead branch is already filed app-side. All S2 description work is *top-level* (concept descriptions, class docstrings), which is safe on both app stacks: the RJSF stack overwrites the top-level description anyway, and no matcher reads it.
+- **No native field renames.** Every `⚠` row in S1 §D stands; S2 adds facts, it never reshapes payloads.
+- **Schema-byte captures re-baseline.** Anything that pins emitted schema bytes — the codegen/validate parity corpora, conformance captures, characterization tests — shifts under E6/E1/E4. Phase 0 inventories exactly which captures pin schema output so the re-baselines are deliberate, not discovered in CI.
+- **The second engine diverges until mirrored.** `pipelex-js`'s emitters must mirror the schema enrichments and the contract reshape to keep the E-track differential green; that is a filed follow-up (§8), and the differential is precisely the instrument that will measure the gap in the meantime — failing on purpose, the E1 pattern.
+- **`H2`'s fingerprint invariant is untouched.** E7's forbid changes what *parses*, not how a valid crate normalizes; hint-free crates keep byte-identical fingerprints.
+
+## 5. Measurement and gate mechanics
+
+S1's instrument is S2's proof. The probe bundle and the `pipelex-dev trace-input-semantics` harness are extended where a closure needs a case they lack (class-backed and native-direct-input descriptions, the title, `minItems`/`maxItems`; `titled_default` moves to `rejected/`), and the survival table is regenerated at close — each entry's closure must be visible as a before/after row change, the same evidence standard the audit set. Beside the probe: unit tests at each seam (the blueprint validator, the generator invariant, the render injections, the contract fields, the builder round trip).
+
+The gate splits exactly as D2's did, and the roadmap closure bullet must say so: **in-engine close** is the probe-measured survival table plus green tests on `feature/Enrich`; **"enriched schemas visible on `/validate`"** on the hosted wire arrives with the release cascade (D3's sequence), where the gated conformance modules arm. In-process `/validate` (the CLI and agent-CLI surfaces) shows the enrichment immediately on merge, since all three presentations share the one validation engine.
+
+## 6. Decisions to ratify before implementation
+
+1. **E3:** reject `required = true` + `default_value` at validation (recommended), versus defining the pair. Carries a one-sentence mthds spec addition and a breaking changelog note.
+2. **E5/E9:** reshape the contract — `presence` *replaces* the input's `optional`, `multiplicity` goes three-valued with `item_count` (recommended), versus additive-only (keeping `optional` beside `presence`). The recommendation follows the no-backward-compat principle and the single-source rule; the cost is coordinated updates to the protocol spec, conformance, `mthds-js` types, and the second engine, all of which ride the cascade anyway.
+3. **Reflected defaults:** a pydantic default on a reflected class counts as an authored fact (recommended), closing the D2 deferral's first item inside S2.
+
+## 7. Execution phases
+
+Tracker convention: at kickoff, seed `TODOS.md` at the worktree root from this section (the D2/E1 pattern); this document stays the design and does not track live state. Each checkpoint updates the tracker with decisions taken, deviations reconciled into later phases, and enough state for a cold-start session to continue.
+
+- **Phase 0 — ratify and sweep.** Decisions §6 confirmed by Louis. Sweeps, re-run at head: hopeful extras and the `required`+`default_value` pair across fixtures, corpus entries, and cookbook-adjacent test data; inventory of captures that pin schema bytes. Output: the fixture-fallout list for Phases 1–2.
+- **Phase 1 — loudness (E7, E8).** The forbid, the builder key, the round-trip test, `make gms`, fixture fallout, delivery of the E8 inbox item. **Checkpoint 1** — natural handoff: the authoring loop is honest, nothing wire-visible has changed yet.
+- **Phase 2 — schema enrichment (E6, E1-title, E4).** The render-seam injections, native docstrings, multiplicity threading, memo-key change, probe extensions. **Checkpoint 2** — the "zero client changes" half is complete and measurable.
+- **Phase 3 — contract reshaping (E5, E9).** Spec-first: the protocol spec's contract row and presence section, the conformance assertions (gated), then the engine models and emission, `make check-spec-links`. **Checkpoint 3** — the protocol change is contained in one reviewable unit.
+- **Phase 4 — semantics and close (E3, reflected defaults).** The blueprint validator, the generator invariant, `_with_reflected_constraints`, descriptor-spec touch-ups, survival-table regeneration, findings addendum (a short §F recording each entry's closure evidence), roadmap closure bullet, changelog, and the cross-repo filings of §8.
+
+## 8. Cross-repo follow-ups to file at close
+
+Each of these crosses a boundary this session must not quietly widen into; they are filed as `../wip/inbox/` items in Phase 4, with this design as their evidence base:
+
+- **`mthds`** — two spec sentences: unknown structure-field keys MUST be rejected (the slot-table rule's twin), and a field MUST NOT declare both `required = true` and `default_value`. Engine leads by one release, the H2 precedent.
+- **`pipelex-js`** — mirror the schema enrichments and the contract reshape in the second engine's emitters; the parity differential measures the gap until then.
+- **`mthds-js`** — the protocol types in `src/protocol/models.ts` follow the contract reshape at the cascade (D4 regenerates SDK types against the same release).
+- No new item for schema/corpus sync: the filed release-time item (`2026-08-23-workspace-hints-corpus-and-schema-sync-at-release.md`) covers the release that ships H2 and S2 both.
+
+## 9. Out of scope
+
+- **The language ceiling (S1 §B)** — constraints, examples, units, per-slot descriptions, choice labels, non-string choices, refine-and-extend: all language design, Track H's territory via an mthds design session. S2 makes their absence *loud* (E7) but adds no syntax. The descriptor's `examples` and constraint slots stay shaped-to-receive.
+- **App-side fixes** — the drifted taxonomy copies, the dropzone matcher, the flatten-then-repair round trip: M1 deletes them by swapping the kernel onto the descriptor.
+- **Corpus widening** — the input-side coverage wish-list (`../wip/inbox/2026-08-22-pipelex-corpus-input-side-concept-coverage.md`) is adjacent and stays its own pass; S2's probe bundle is the measurement fixture, not a corpus substitute.
+- **E10 beyond documentation** — no `const`-to-`enum` render rewrite, per the §3 ruling.
+- **The descriptor wire model's round-trip alias** — D4's, per the deferral note.
diff --git a/wip/input-semantics/findings.md b/wip/input-semantics/findings.md
index ce4ebafe2..8a3e3d025 100644
--- a/wip/input-semantics/findings.md
+++ b/wip/input-semantics/findings.md
@@ -161,3 +161,24 @@ Worked-around gaps first, per the brief:
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).
+
+---
+
+## F. S2 closure evidence (2026-08-23, `feature/Enrich`)
+
+Every engine-side entry of §A/§E is closed; the evidence standard is the audit's own — each closure is visible as a before/after row change in the [survival table](survival-table.md) against the regenerated captures under `probe/`. Design and rulings: `wip/enrich/design.md`; wire spec: `docs/specs/pipelex-mthds-protocol.md` (workspace root).
+
+| Entry | Closure | Evidence |
+|---|---|---|
+| E1 concept identity | Top-level schema `title` is the concept ref, injected at `_render_schema_representation` (`concept.py`). Nested `$defs` identity stays descriptor-only, per the design ruling. | `probe/hop4_schema_renders/*.json` — every render's `content.title` is the concept ref (e.g. `native.Text`, `input_semantics_probe.ClassBacked`). |
+| E2 refinement chain | Ruled closed by the descriptor (`refines` list); no schema change, by design. | Descriptor spec + `hop5_input_form.json`. |
+| E3 required + default | The pair is rejected by a `ConceptStructureBlueprint` model validator; the generator's silent tiebreak is now an explicit raising invariant; a reflected class's pydantic default counts as an authored fact (`required: false` + `default_value`, closing the D2 deferral's first item). | `rejected/required_with_default.mthds_invalid`; unit seams `test_concept_structure_blueprint_required_default.py`, `test_structure_generator_required_default_invariant.py`; reflected row in `test_input_form.py`. Survival-table row now "rejected at hop 1". |
+| E4 `[N]` multiplicity | Real multiplicity threaded through `render_stuff_spec` → `render_concept_representation`; fixed counts emit `minItems`/`maxItems`; memo key normalized (no `hash(True)==hash(1)` collision); `[1]` stays single. | `probe/hop4_schema_renders/input_semantics_probe.probe_markers.two.json` (`minItems: 2`, `maxItems: 2`); `many` unbounded. |
+| E5 `!` on the contract | `PipeInputContract.presence` (three-valued, replacing `optional`) — protocol change, spec-first. | `probe/hop5_pipe_io_contracts.json`: `forced` reports `presence: "force"`. Conformance arms at the re-pin (shape-detected skip). |
+| E6 missing descriptions | Top-level schema `description` is the concept's authored description for every species; the seven bare native content classes gained docstrings (instructor-side schemas carry them too). | `probe/hop4_schema_renders/…classbacked.json` (authored description present); native renders carry pinned descriptions. |
+| E7 silent extras | `extra="forbid"` on `ConceptStructureBlueprint` (hint content stays lenient). | `rejected/unknown_structure_field_key.mthds_invalid`; `test_concept_structure_blueprint_extra_keys.py`. |
+| E8 builder `default` key | Builder writes `default_value`; write-then-validate round trip pinned. | `concept_ops.py` + `test_concept_spec_to_toml.py`; inbox item delivered and removed. |
+| E9 multiplicity on contract | Input and output contracts carry three-valued `multiplicity` + `item_count` (`make_io_multiplicity`); the fixed-reports-as-variable ruling retired. | `probe/hop5_pipe_io_contracts.json`: `two` reports `("fixed", 2)` on input and output; `many` `("variable", null)`. |
+| E10 `const` vs `enum` | Schema stays pydantic-canonical; `const` documented as part of the contract (protocol spec sentence). Descriptor half closed by D2. | Spec `pipe_io_contracts` row; `only_choice` render shows `const`. |
+
+The §B language ceiling is untouched (out of scope, by design §9); its absence is now loud where it used to be silent (E7). Cross-repo follow-ups filed: `mthds` (the two validation sentences), `pipelex-js` (mirror), `mthds-js` (protocol types at the cascade).
diff --git a/wip/input-semantics/probe/hop1_bundle_blueprints.json b/wip/input-semantics/probe/hop1_bundle_blueprints.json
index e1df6e3dc..759a437ad 100644
--- a/wip/input-semantics/probe/hop1_bundle_blueprints.json
+++ b/wip/input-semantics/probe/hop1_bundle_blueprints.json
@@ -99,18 +99,6 @@
"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",
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
index 7db811df0..db7739206 100644
--- 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
@@ -28,7 +28,6 @@ class input_semantics_probe__Widget(StructuredContent):
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")
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
index 1020c00aa..6a5afdf39 100644
--- 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
@@ -1,4 +1,5 @@
{
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
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
index 458762f02..431b2d776 100644
--- 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
@@ -1,6 +1,7 @@
{
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -214,12 +215,6 @@
"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": [
{
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
index 3dc39647d..e3ea0d85c 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Document.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Document.json
@@ -1,4 +1,5 @@
{
+ "description": "A document",
"properties": {
"url": {
"description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
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
index e73e5c975..8d783264b 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Html.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Html.json
@@ -1,4 +1,5 @@
{
+ "description": "HTML content",
"properties": {
"inner_html": {
"description": "The inner HTML of the content",
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
index 6b399a78a..2e8c9cdc5 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Image.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Image.json
@@ -1,4 +1,5 @@
{
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
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
index cecae614b..bfbd6719c 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Number.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Number.json
@@ -1,4 +1,5 @@
{
+ "description": "A number",
"properties": {
"number": {
"anyOf": [
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
index a2846983c..9fbfd40b2 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Page.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Page.json
@@ -1,6 +1,7 @@
{
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -168,6 +169,7 @@
"type": "object"
},
"TextContent": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -182,6 +184,7 @@
"type": "object"
}
},
+ "description": "The content of a page of a document, comprising text and linked images and an optional page view image",
"properties": {
"text_and_images": {
"$ref": "#/$defs/TextAndImagesContent",
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
index 1020c00aa..6a5afdf39 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Text.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.Text.json
@@ -1,4 +1,5 @@
{
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
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
index b21293654..9e4c6fe26 100644
--- a/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.YesNo.json
+++ b/wip/input-semantics/probe/hop3_raw_pydantic_schemas/native.YesNo.json
@@ -1,4 +1,5 @@
{
+ "description": "The answer to a yes/no question",
"properties": {
"yes_no": {
"description": "Whether the answer is yes (true) or no (false).",
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
index 2fe21f3c4..7eb5f9166 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Text",
"content": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -11,7 +12,7 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "native.Text",
"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
index dc46ffe64..2582caaba 100644
--- 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
@@ -5,6 +5,7 @@
"items": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -218,12 +219,6 @@
"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": [
{
@@ -508,7 +503,7 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "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
index 0f1930229..eccb473e3 100644
--- 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
@@ -3,6 +3,7 @@
"content": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -216,12 +217,6 @@
"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": [
{
@@ -506,7 +501,7 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "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
index 82fb9e896..44f23315d 100644
--- 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
@@ -43,8 +43,10 @@
"required": [
"name"
],
- "title": "input_semantics_probe__Gadget",
+ "title": "input_semantics_probe.Gadget",
"type": "object"
- }
+ },
+ "minItems": 2,
+ "maxItems": 2
}
}
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
index 529a8fe03..76cb3d254 100644
--- 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
@@ -1,7 +1,7 @@
{
"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.",
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.",
"properties": {
"date": {
"description": "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.",
@@ -27,7 +27,7 @@
"required": [
"date"
],
- "title": "DateContent",
+ "title": "native.Date",
"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
index e3805f734..f89bb3500 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Document",
"content": {
+ "description": "A document",
"properties": {
"url": {
"description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -76,7 +77,7 @@
"required": [
"url"
],
- "title": "DocumentContent",
+ "title": "native.Document",
"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
index fcccee0ae..b040a1986 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Html",
"content": {
+ "description": "HTML content",
"properties": {
"inner_html": {
"description": "The inner HTML of the content",
@@ -17,7 +18,7 @@
"inner_html",
"css_class"
],
- "title": "HtmlContent",
+ "title": "native.Html",
"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
index cb8b56296..c9d1be941 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Image",
"content": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -117,7 +118,7 @@
"required": [
"url"
],
- "title": "ImageContent",
+ "title": "native.Image",
"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
index 2fe035890..651d85961 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Number",
"content": {
+ "description": "A number",
"properties": {
"number": {
"anyOf": [
@@ -18,7 +19,7 @@
"required": [
"number"
],
- "title": "NumberContent",
+ "title": "native.Number",
"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
index e5d3185ac..0984da36b 100644
--- 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
@@ -3,6 +3,7 @@
"content": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -170,6 +171,7 @@
"type": "object"
},
"TextContent": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -184,6 +186,7 @@
"type": "object"
}
},
+ "description": "The content of a page of a document, comprising text and linked images and an optional page view image",
"properties": {
"text_and_images": {
"$ref": "#/$defs/TextAndImagesContent",
@@ -205,7 +208,7 @@
"required": [
"text_and_images"
],
- "title": "PageContent",
+ "title": "native.Page",
"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
index 2fe21f3c4..7eb5f9166 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.Text",
"content": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -11,7 +12,7 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "native.Text",
"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
index f0268668c..334143014 100644
--- 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
@@ -1,7 +1,7 @@
{
"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.",
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.",
"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).",
@@ -13,7 +13,7 @@
"required": [
"time"
],
- "title": "TimeContent",
+ "title": "native.Time",
"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
index ee06c2a86..afb8faf0f 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "native.YesNo",
"content": {
+ "description": "The answer to a yes/no question",
"properties": {
"yes_no": {
"description": "Whether the answer is yes (true) or no (false).",
@@ -11,7 +12,7 @@
"required": [
"yes_no"
],
- "title": "YesNoContent",
+ "title": "native.YesNo",
"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
index 1acf67d0a..f385fa0ba 100644
--- 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
@@ -1,6 +1,7 @@
{
"concept": "input_semantics_probe.ClassBacked",
"content": {
+ "description": "PROBE_desc_concept_ClassBacked: structure declared as an existing class name",
"properties": {
"text": {
"description": "The text",
@@ -11,7 +12,7 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "input_semantics_probe.ClassBacked",
"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
index 36dc9b616..9b67e9baf 100644
--- 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
@@ -12,7 +12,7 @@
"required": [
"ident"
],
- "title": "input_semantics_probe__ExtraSpecialEntity",
+ "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
index 42964bbab..0c23883bc 100644
--- 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
@@ -77,7 +77,7 @@
"required": [
"url"
],
- "title": "input_semantics_probe__RefinedDoc",
+ "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
index d06772ae8..d2b54ec65 100644
--- 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
@@ -12,7 +12,7 @@
"required": [
"ident"
],
- "title": "input_semantics_probe__SpecialEntity",
+ "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
index 7f6bdf728..181ded651 100644
--- 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
@@ -12,7 +12,7 @@
"required": [
"text"
],
- "title": "input_semantics_probe__StringNote",
+ "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
index ff263d941..a2f93fcf8 100644
--- 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
@@ -41,7 +41,7 @@
"required": [
"name"
],
- "title": "input_semantics_probe__Gadget",
+ "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
index 7dba7d9ad..84d21054c 100644
--- 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
@@ -12,7 +12,7 @@
"required": [
"text"
],
- "title": "input_semantics_probe__PlainNote",
+ "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
index 0f1930229..eccb473e3 100644
--- 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
@@ -3,6 +3,7 @@
"content": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -216,12 +217,6 @@
"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": [
{
@@ -506,7 +501,7 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "title": "input_semantics_probe.Widget",
"type": "object"
}
}
diff --git a/wip/input-semantics/probe/hop5_input_form.json b/wip/input-semantics/probe/hop5_input_form.json
new file mode 100644
index 000000000..91882163a
--- /dev/null
+++ b/wip/input-semantics/probe/hop5_input_form.json
@@ -0,0 +1,1101 @@
+{
+ "input_semantics_probe.probe_single": {
+ "fields": [
+ {
+ "kind": "object",
+ "name": "widget",
+ "concept_ref": "input_semantics_probe.Widget",
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "shorthand_note",
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "title",
+ "description": "PROBE_desc_field_title: required text",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "subtitle",
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "summary",
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "required": false,
+ "default_value": "PROBE_default_motto"
+ },
+ {
+ "kind": "number",
+ "name": "count",
+ "description": "PROBE_desc_field_count: integer with default",
+ "required": false,
+ "default_value": 42,
+ "integer": true
+ },
+ {
+ "kind": "boolean",
+ "name": "enabled",
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "required": false,
+ "default_value": true
+ },
+ {
+ "kind": "number",
+ "name": "price",
+ "description": "PROBE_desc_field_price: number with default",
+ "required": false,
+ "default_value": 9.99,
+ "integer": false
+ },
+ {
+ "kind": "date",
+ "name": "released_on",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "required": false,
+ "default_value": "2026-01-15",
+ "datetime": false
+ },
+ {
+ "kind": "date",
+ "name": "launched_at",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "required": false,
+ "default_value": "2026-01-15T12:30:00",
+ "datetime": true
+ },
+ {
+ "kind": "text",
+ "name": "daily_at",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "required": false,
+ "default_value": "12:30:00",
+ "format": "time"
+ },
+ {
+ "kind": "list",
+ "name": "tags",
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "required": false,
+ "default_value": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "item": {
+ "kind": "text",
+ "name": "tags",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "ratings",
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "required": false,
+ "item": {
+ "kind": "number",
+ "name": "ratings",
+ "required": true,
+ "integer": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "matrix",
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "required": false,
+ "item": {
+ "kind": "unknown",
+ "name": "matrix",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "required": false,
+ "item": {
+ "kind": "object",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "attributes",
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "required": false
+ },
+ {
+ "kind": "unknown",
+ "name": "scores",
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "required": false,
+ "default_value": {
+ "speed": 5
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "milestones",
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "required": false
+ },
+ {
+ "kind": "object",
+ "name": "main_gadget",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "kind": "image",
+ "name": "icon",
+ "concept_ref": "native.Image",
+ "description": "PROBE_desc_field_icon: native concept field",
+ "required": false
+ },
+ {
+ "kind": "enum",
+ "name": "tone",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "required": false,
+ "default_value": "PROBE_choice_casual",
+ "choices": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "only_choice",
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "required": false,
+ "choices": [
+ "PROBE_choice_single"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "typed_choice",
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "required": false,
+ "choices": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ]
+ },
+ {
+ "kind": "number",
+ "name": "constrained_count",
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "required": false,
+ "integer": true
+ }
+ ]
+ },
+ {
+ "kind": "object",
+ "name": "gadget_q",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "kind": "prose",
+ "name": "note",
+ "concept_ref": "input_semantics_probe.PlainNote",
+ "refines": [
+ "native.Text"
+ ],
+ "description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ }
+ ]
+ },
+ "input_semantics_probe.probe_native_inputs": {
+ "fields": [
+ {
+ "kind": "prose",
+ "name": "text_in",
+ "concept_ref": "native.Text",
+ "description": "A text",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "image",
+ "name": "image_in",
+ "concept_ref": "native.Image",
+ "description": "An image",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "document",
+ "name": "document_in",
+ "concept_ref": "native.Document",
+ "description": "A document",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "object",
+ "name": "page_in",
+ "concept_ref": "native.Page",
+ "description": "The content of a page of a document, comprising text and linked images and an optional page view image",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "fields": [
+ {
+ "kind": "object",
+ "name": "text_and_images",
+ "concept_ref": "native.TextAndImages",
+ "description": "The text and images content extracted from the page",
+ "required": true,
+ "fields": [
+ {
+ "kind": "prose",
+ "name": "text",
+ "concept_ref": "native.Text",
+ "description": "A text content",
+ "required": false
+ },
+ {
+ "kind": "list",
+ "name": "images",
+ "concept_ref": "native.Image",
+ "description": "A list of images that were extracted from the text",
+ "required": false,
+ "item": {
+ "kind": "image",
+ "name": "images",
+ "concept_ref": "native.Image",
+ "description": "An image",
+ "required": true
+ }
+ },
+ {
+ "kind": "text",
+ "name": "raw_html",
+ "description": "The raw HTML of the fetched page, if requested",
+ "required": false
+ }
+ ]
+ },
+ {
+ "kind": "image",
+ "name": "page_view",
+ "concept_ref": "native.Image",
+ "description": "The screenshot of the page",
+ "required": false
+ }
+ ]
+ },
+ {
+ "kind": "number",
+ "name": "number_in",
+ "concept_ref": "native.Number",
+ "description": "A number",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "integer": false
+ },
+ {
+ "kind": "date",
+ "name": "date_in",
+ "concept_ref": "native.Date",
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "datetime": false
+ },
+ {
+ "kind": "text",
+ "name": "time_in",
+ "concept_ref": "native.Time",
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "format": "time"
+ },
+ {
+ "kind": "prose",
+ "name": "html_in",
+ "concept_ref": "native.Html",
+ "description": "HTML content",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "boolean",
+ "name": "yesno_in",
+ "concept_ref": "native.YesNo",
+ "description": "The answer to a yes/no question",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ }
+ ]
+ },
+ "input_semantics_probe.probe_markers": {
+ "fields": [
+ {
+ "kind": "object",
+ "name": "opt",
+ "concept_ref": "input_semantics_probe.Widget",
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "required": false,
+ "presence": "optional",
+ "gating": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "shorthand_note",
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "title",
+ "description": "PROBE_desc_field_title: required text",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "subtitle",
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "summary",
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "required": false,
+ "default_value": "PROBE_default_motto"
+ },
+ {
+ "kind": "number",
+ "name": "count",
+ "description": "PROBE_desc_field_count: integer with default",
+ "required": false,
+ "default_value": 42,
+ "integer": true
+ },
+ {
+ "kind": "boolean",
+ "name": "enabled",
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "required": false,
+ "default_value": true
+ },
+ {
+ "kind": "number",
+ "name": "price",
+ "description": "PROBE_desc_field_price: number with default",
+ "required": false,
+ "default_value": 9.99,
+ "integer": false
+ },
+ {
+ "kind": "date",
+ "name": "released_on",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "required": false,
+ "default_value": "2026-01-15",
+ "datetime": false
+ },
+ {
+ "kind": "date",
+ "name": "launched_at",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "required": false,
+ "default_value": "2026-01-15T12:30:00",
+ "datetime": true
+ },
+ {
+ "kind": "text",
+ "name": "daily_at",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "required": false,
+ "default_value": "12:30:00",
+ "format": "time"
+ },
+ {
+ "kind": "list",
+ "name": "tags",
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "required": false,
+ "default_value": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "item": {
+ "kind": "text",
+ "name": "tags",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "ratings",
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "required": false,
+ "item": {
+ "kind": "number",
+ "name": "ratings",
+ "required": true,
+ "integer": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "matrix",
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "required": false,
+ "item": {
+ "kind": "unknown",
+ "name": "matrix",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "required": false,
+ "item": {
+ "kind": "object",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "attributes",
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "required": false
+ },
+ {
+ "kind": "unknown",
+ "name": "scores",
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "required": false,
+ "default_value": {
+ "speed": 5
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "milestones",
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "required": false
+ },
+ {
+ "kind": "object",
+ "name": "main_gadget",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "kind": "image",
+ "name": "icon",
+ "concept_ref": "native.Image",
+ "description": "PROBE_desc_field_icon: native concept field",
+ "required": false
+ },
+ {
+ "kind": "enum",
+ "name": "tone",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "required": false,
+ "default_value": "PROBE_choice_casual",
+ "choices": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "only_choice",
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "required": false,
+ "choices": [
+ "PROBE_choice_single"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "typed_choice",
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "required": false,
+ "choices": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ]
+ },
+ {
+ "kind": "number",
+ "name": "constrained_count",
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "required": false,
+ "integer": true
+ }
+ ]
+ },
+ {
+ "kind": "list",
+ "name": "many",
+ "concept_ref": "input_semantics_probe.Widget",
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "required": true,
+ "presence": "plain",
+ "gating": false,
+ "item": {
+ "kind": "object",
+ "name": "many",
+ "concept_ref": "input_semantics_probe.Widget",
+ "description": "PROBE_desc_concept_Widget: the full-matrix structure under audit",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "shorthand_note",
+ "description": "PROBE_desc_field_shorthand_note: shorthand string field (implies text, required)",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "title",
+ "description": "PROBE_desc_field_title: required text",
+ "required": true
+ },
+ {
+ "kind": "text",
+ "name": "subtitle",
+ "description": "PROBE_desc_field_subtitle: optional text (required omitted)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "summary",
+ "description": "PROBE_desc_field_summary: optional text (required explicit false)",
+ "required": false
+ },
+ {
+ "kind": "text",
+ "name": "motto",
+ "description": "PROBE_desc_field_motto: text with default",
+ "required": false,
+ "default_value": "PROBE_default_motto"
+ },
+ {
+ "kind": "number",
+ "name": "count",
+ "description": "PROBE_desc_field_count: integer with default",
+ "required": false,
+ "default_value": 42,
+ "integer": true
+ },
+ {
+ "kind": "boolean",
+ "name": "enabled",
+ "description": "PROBE_desc_field_enabled: boolean with default",
+ "required": false,
+ "default_value": true
+ },
+ {
+ "kind": "number",
+ "name": "price",
+ "description": "PROBE_desc_field_price: number with default",
+ "required": false,
+ "default_value": 9.99,
+ "integer": false
+ },
+ {
+ "kind": "date",
+ "name": "released_on",
+ "description": "PROBE_desc_field_released_on: date with default",
+ "required": false,
+ "default_value": "2026-01-15",
+ "datetime": false
+ },
+ {
+ "kind": "date",
+ "name": "launched_at",
+ "description": "PROBE_desc_field_launched_at: datetime with default",
+ "required": false,
+ "default_value": "2026-01-15T12:30:00",
+ "datetime": true
+ },
+ {
+ "kind": "text",
+ "name": "daily_at",
+ "description": "PROBE_desc_field_daily_at: time with default",
+ "required": false,
+ "default_value": "12:30:00",
+ "format": "time"
+ },
+ {
+ "kind": "list",
+ "name": "tags",
+ "description": "PROBE_desc_field_tags: list of text with default",
+ "required": false,
+ "default_value": [
+ "PROBE_tag_a",
+ "PROBE_tag_b"
+ ],
+ "item": {
+ "kind": "text",
+ "name": "tags",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "ratings",
+ "description": "PROBE_desc_field_ratings: list of integer",
+ "required": false,
+ "item": {
+ "kind": "number",
+ "name": "ratings",
+ "required": true,
+ "integer": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "matrix",
+ "description": "PROBE_desc_field_matrix: nested list with unspecified inner item",
+ "required": false,
+ "item": {
+ "kind": "unknown",
+ "name": "matrix",
+ "required": true
+ }
+ },
+ {
+ "kind": "list",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_gadgets: list of concept",
+ "required": false,
+ "item": {
+ "kind": "object",
+ "name": "gadgets",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "attributes",
+ "description": "PROBE_desc_field_attributes: dict text to text",
+ "required": false
+ },
+ {
+ "kind": "unknown",
+ "name": "scores",
+ "description": "PROBE_desc_field_scores: dict text to number with default",
+ "required": false,
+ "default_value": {
+ "speed": 5
+ }
+ },
+ {
+ "kind": "unknown",
+ "name": "milestones",
+ "description": "PROBE_desc_field_milestones: dict text to date",
+ "required": false
+ },
+ {
+ "kind": "object",
+ "name": "main_gadget",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_field_main_gadget: required concept field",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "kind": "image",
+ "name": "icon",
+ "concept_ref": "native.Image",
+ "description": "PROBE_desc_field_icon: native concept field",
+ "required": false
+ },
+ {
+ "kind": "enum",
+ "name": "tone",
+ "description": "PROBE_desc_field_tone: choices with default",
+ "required": false,
+ "default_value": "PROBE_choice_casual",
+ "choices": [
+ "PROBE_choice_formal",
+ "PROBE_choice_casual",
+ "PROBE_choice_playful"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "only_choice",
+ "description": "PROBE_desc_field_only_choice: single-entry choice list",
+ "required": false,
+ "choices": [
+ "PROBE_choice_single"
+ ]
+ },
+ {
+ "kind": "enum",
+ "name": "typed_choice",
+ "description": "PROBE_desc_field_typed_choice: type AND choices together",
+ "required": false,
+ "choices": [
+ "PROBE_choice_typed_a",
+ "PROBE_choice_typed_b"
+ ]
+ },
+ {
+ "kind": "number",
+ "name": "constrained_count",
+ "description": "PROBE_desc_field_constrained_count: integer carrying unknown constraint keys",
+ "required": false,
+ "integer": true
+ }
+ ]
+ }
+ },
+ {
+ "kind": "list",
+ "name": "two",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "item": {
+ "kind": "object",
+ "name": "two",
+ "concept_ref": "input_semantics_probe.Gadget",
+ "description": "PROBE_desc_concept_Gadget: mid-level structure nested inside Widget",
+ "required": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "name",
+ "description": "PROBE_desc_field_gadget_name",
+ "required": true
+ },
+ {
+ "kind": "object",
+ "name": "trinket",
+ "concept_ref": "input_semantics_probe.Trinket",
+ "description": "PROBE_desc_field_gadget_trinket: nested concept, level two",
+ "required": false,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "label",
+ "description": "PROBE_desc_field_trinket_label: shorthand string field on the nesting leaf",
+ "required": true
+ }
+ ]
+ }
+ ]
+ },
+ "item_count": 2
+ },
+ {
+ "kind": "prose",
+ "name": "forced",
+ "concept_ref": "native.Text",
+ "description": "A text",
+ "required": true,
+ "presence": "force",
+ "gating": true
+ }
+ ]
+ },
+ "input_semantics_probe.probe_refined": {
+ "fields": [
+ {
+ "kind": "document",
+ "name": "refdoc",
+ "concept_ref": "input_semantics_probe.RefinedDoc",
+ "refines": [
+ "native.Document"
+ ],
+ "description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "object",
+ "name": "special",
+ "concept_ref": "input_semantics_probe.SpecialEntity",
+ "refines": [
+ "input_semantics_probe.BaseEntity"
+ ],
+ "description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "ident",
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "required": true
+ }
+ ]
+ },
+ {
+ "kind": "object",
+ "name": "extra",
+ "concept_ref": "input_semantics_probe.ExtraSpecialEntity",
+ "refines": [
+ "input_semantics_probe.SpecialEntity",
+ "input_semantics_probe.BaseEntity"
+ ],
+ "description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
+ "required": true,
+ "presence": "plain",
+ "gating": true,
+ "fields": [
+ {
+ "kind": "text",
+ "name": "ident",
+ "description": "PROBE_desc_field_base_ident: inherited field",
+ "required": true
+ }
+ ]
+ },
+ {
+ "kind": "prose",
+ "name": "classbacked",
+ "concept_ref": "input_semantics_probe.ClassBacked",
+ "description": "PROBE_desc_concept_ClassBacked: structure declared as an existing class name",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ },
+ {
+ "kind": "prose",
+ "name": "stringnote",
+ "concept_ref": "input_semantics_probe.StringNote",
+ "refines": [
+ "native.Text"
+ ],
+ "description": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
+ "required": true,
+ "presence": "plain",
+ "gating": true
+ }
+ ]
+ }
+}
diff --git a/wip/input-semantics/probe/hop5_pipe_io_contracts.json b/wip/input-semantics/probe/hop5_pipe_io_contracts.json
index ebd2d986d..3543df2ce 100644
--- a/wip/input-semantics/probe/hop5_pipe_io_contracts.json
+++ b/wip/input-semantics/probe/hop5_pipe_io_contracts.json
@@ -3,10 +3,13 @@
"inputs": {
"widget": {
"concept_ref": "input_semantics_probe.Widget",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -220,12 +223,6 @@
"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": [
{
@@ -510,13 +507,15 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "title": "input_semantics_probe.Widget",
"type": "object"
}
},
"gadget_q": {
"concept_ref": "input_semantics_probe.Gadget",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"$defs": {
"input_semantics_probe__Trinket": {
@@ -558,13 +557,15 @@
"required": [
"name"
],
- "title": "input_semantics_probe__Gadget",
+ "title": "input_semantics_probe.Gadget",
"type": "object"
}
},
"note": {
"concept_ref": "input_semantics_probe.PlainNote",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"description": "PROBE_desc_concept_PlainNote: description-only concept (basic blueprint)",
"properties": {
@@ -577,7 +578,7 @@
"required": [
"text"
],
- "title": "input_semantics_probe__PlainNote",
+ "title": "input_semantics_probe.PlainNote",
"type": "object"
}
}
@@ -585,6 +586,7 @@
"output": {
"concept_ref": "native.Text",
"multiplicity": "single",
+ "item_count": null,
"optional": false
}
},
@@ -592,8 +594,11 @@
"inputs": {
"text_in": {
"concept_ref": "native.Text",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -604,14 +609,17 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "native.Text",
"type": "object"
}
},
"image_in": {
"concept_ref": "native.Image",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -728,14 +736,17 @@
"required": [
"url"
],
- "title": "ImageContent",
+ "title": "native.Image",
"type": "object"
}
},
"document_in": {
"concept_ref": "native.Document",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "A document",
"properties": {
"url": {
"description": "The document URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -811,16 +822,19 @@
"required": [
"url"
],
- "title": "DocumentContent",
+ "title": "native.Document",
"type": "object"
}
},
"page_in": {
"concept_ref": "native.Page",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -988,6 +1002,7 @@
"type": "object"
},
"TextContent": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -1002,6 +1017,7 @@
"type": "object"
}
},
+ "description": "The content of a page of a document, comprising text and linked images and an optional page view image",
"properties": {
"text_and_images": {
"$ref": "#/$defs/TextAndImagesContent",
@@ -1023,14 +1039,17 @@
"required": [
"text_and_images"
],
- "title": "PageContent",
+ "title": "native.Page",
"type": "object"
}
},
"number_in": {
"concept_ref": "native.Number",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "A number",
"properties": {
"number": {
"anyOf": [
@@ -1048,15 +1067,17 @@
"required": [
"number"
],
- "title": "NumberContent",
+ "title": "native.Number",
"type": "object"
}
},
"date_in": {
"concept_ref": "native.Date",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"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.",
+ "description": "A calendar date, optionally with a time of day — as precise as its source states.",
"properties": {
"date": {
"description": "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.",
@@ -1082,15 +1103,17 @@
"required": [
"date"
],
- "title": "DateContent",
+ "title": "native.Date",
"type": "object"
}
},
"time_in": {
"concept_ref": "native.Time",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"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.",
+ "description": "A time of day, optionally with a UTC offset — as precise as its source states.",
"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).",
@@ -1102,14 +1125,17 @@
"required": [
"time"
],
- "title": "TimeContent",
+ "title": "native.Time",
"type": "object"
}
},
"html_in": {
"concept_ref": "native.Html",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "HTML content",
"properties": {
"inner_html": {
"description": "The inner HTML of the content",
@@ -1126,14 +1152,17 @@
"inner_html",
"css_class"
],
- "title": "HtmlContent",
+ "title": "native.Html",
"type": "object"
}
},
"yesno_in": {
"concept_ref": "native.YesNo",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "The answer to a yes/no question",
"properties": {
"yes_no": {
"description": "Whether the answer is yes (true) or no (false).",
@@ -1144,7 +1173,7 @@
"required": [
"yes_no"
],
- "title": "YesNoContent",
+ "title": "native.YesNo",
"type": "object"
}
}
@@ -1152,6 +1181,7 @@
"output": {
"concept_ref": "native.Text",
"multiplicity": "single",
+ "item_count": null,
"optional": false
}
},
@@ -1159,10 +1189,13 @@
"inputs": {
"opt": {
"concept_ref": "input_semantics_probe.Widget",
- "optional": true,
+ "presence": "optional",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -1376,12 +1409,6 @@
"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": [
{
@@ -1666,18 +1693,21 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "title": "input_semantics_probe.Widget",
"type": "object"
}
},
"many": {
"concept_ref": "input_semantics_probe.Widget",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "variable",
+ "item_count": null,
"json_schema": {
"type": "array",
"items": {
"$defs": {
"ImageContent": {
+ "description": "An image",
"properties": {
"url": {
"description": "The image URL: a storage URI, an HTTP(S) URL, or a base64 data URL",
@@ -1891,12 +1921,6 @@
"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": [
{
@@ -2181,14 +2205,16 @@
"title",
"main_gadget"
],
- "title": "input_semantics_probe__Widget",
+ "title": "input_semantics_probe.Widget",
"type": "object"
}
}
},
"two": {
"concept_ref": "input_semantics_probe.Gadget",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "fixed",
+ "item_count": 2,
"json_schema": {
"type": "array",
"items": {
@@ -2232,15 +2258,20 @@
"required": [
"name"
],
- "title": "input_semantics_probe__Gadget",
+ "title": "input_semantics_probe.Gadget",
"type": "object"
- }
+ },
+ "minItems": 2,
+ "maxItems": 2
}
},
"forced": {
"concept_ref": "native.Text",
- "optional": false,
+ "presence": "force",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "A text",
"properties": {
"text": {
"description": "The text",
@@ -2251,7 +2282,7 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "native.Text",
"type": "object"
}
}
@@ -2259,6 +2290,7 @@
"output": {
"concept_ref": "native.Text",
"multiplicity": "single",
+ "item_count": null,
"optional": false
}
},
@@ -2266,7 +2298,9 @@
"inputs": {
"refdoc": {
"concept_ref": "input_semantics_probe.RefinedDoc",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"description": "PROBE_desc_concept_RefinedDoc: refinement of a native concept",
"properties": {
@@ -2344,13 +2378,15 @@
"required": [
"url"
],
- "title": "input_semantics_probe__RefinedDoc",
+ "title": "input_semantics_probe.RefinedDoc",
"type": "object"
}
},
"special": {
"concept_ref": "input_semantics_probe.SpecialEntity",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"description": "PROBE_desc_concept_SpecialEntity: refines a custom concept",
"properties": {
@@ -2363,13 +2399,15 @@
"required": [
"ident"
],
- "title": "input_semantics_probe__SpecialEntity",
+ "title": "input_semantics_probe.SpecialEntity",
"type": "object"
}
},
"extra": {
"concept_ref": "input_semantics_probe.ExtraSpecialEntity",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"description": "PROBE_desc_concept_ExtraSpecialEntity: second link of the refinement chain",
"properties": {
@@ -2382,14 +2420,17 @@
"required": [
"ident"
],
- "title": "input_semantics_probe__ExtraSpecialEntity",
+ "title": "input_semantics_probe.ExtraSpecialEntity",
"type": "object"
}
},
"classbacked": {
"concept_ref": "input_semantics_probe.ClassBacked",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
+ "description": "PROBE_desc_concept_ClassBacked: structure declared as an existing class name",
"properties": {
"text": {
"description": "The text",
@@ -2400,13 +2441,15 @@
"required": [
"text"
],
- "title": "TextContent",
+ "title": "input_semantics_probe.ClassBacked",
"type": "object"
}
},
"stringnote": {
"concept_ref": "input_semantics_probe.StringNote",
- "optional": false,
+ "presence": "plain",
+ "multiplicity": "single",
+ "item_count": null,
"json_schema": {
"description": "PROBE_desc_concept_StringNote: a concept declared as a bare string",
"properties": {
@@ -2419,7 +2462,7 @@
"required": [
"text"
],
- "title": "input_semantics_probe__StringNote",
+ "title": "input_semantics_probe.StringNote",
"type": "object"
}
}
@@ -2427,6 +2470,7 @@
"output": {
"concept_ref": "native.Text",
"multiplicity": "single",
+ "item_count": null,
"optional": false
}
}
diff --git a/wip/input-semantics/probe/trace_manifest.json b/wip/input-semantics/probe/trace_manifest.json
index 8faed807f..c6fdc664a 100644
--- a/wip/input-semantics/probe/trace_manifest.json
+++ b/wip/input-semantics/probe/trace_manifest.json
@@ -61,6 +61,7 @@
"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",
+ "hop5_input_form": "hop5_input_form.json",
"wire_framing": [
{
"pipe_ref": "input_semantics_probe.probe_single",
diff --git a/wip/input-semantics/survival-table.md b/wip/input-semantics/survival-table.md
index 58502672f..57c3a7ba6 100644
--- a/wip/input-semantics/survival-table.md
+++ b/wip/input-semantics/survival-table.md
@@ -1,6 +1,6 @@
# 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.
+**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`); **re-measured 2026-08-23 on `feature/Enrich` after the S2 closures** — rows an S2 entry changed carry a "**closed by S2**" note stating the before → after, with the new behavior visible in the regenerated captures. 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
@@ -8,7 +8,7 @@
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.
+5. **Contract** — `hop5_pipe_io_contracts.json`: `PipeInputContract { concept_ref, presence, multiplicity, item_count, json_schema }` where `json_schema` is hop 4's `content` verbatim (S1 measured the pre-reshape `{ concept_ref, optional, json_schema }`; E5/E9 reshaped it).
## Structure-field facts
@@ -22,7 +22,7 @@
| `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 |
+| `required = true` **and** `default_value` together | **closed by S2 (E3): rejected at hop 1** — the blueprint validator refuses the pair as contradictory, and the generator's silent tiebreak became an explicit invariant | — | — | — | S1 measured: both survived hop 1, then **`required` silently dropped at hop 2**. Now an authoring error; the construct moved to `rejected/required_with_default.mthds_invalid` |
| `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` |
@@ -34,7 +34,7 @@
| 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"`) |
+| Unknown keys on a field (`minimum`, `maximum`, `examples`, `unit`) | **closed by S2 (E7): rejected at hop 1, loudly** — `ConceptStructureBlueprint` is `extra="forbid"` | — | — | — | S1 measured: **died at hop 1, silently**. Now a validation error; the construct lives in `rejected/unknown_structure_field_key.mthds_invalid` |
## Concept-declaration facts
@@ -43,18 +43,18 @@
| 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 |
+| `structure = "TextContent"` (class-backed, `ClassBacked`) | **closed by S2 (E1+E6):** the render injects `title` = the concept ref and `description` = the concept's authored description | S1 measured: raw `TextContent` schema with the class-name title and **no description**. Now the authored facts ride every render (visible on `hop4_schema_renders/input_semantics_probe.probe_refined.classbacked.json`) |
+| Native concepts as direct inputs (`Text`, `Image`, `Document`, `Page`, `Number`, `Date`, `Time`, `Html`, `YesNo`) | **closed by S2 (E1+E6):** top-level `title` is the native concept ref (`native.Text`), `description` is the pinned native blueprint's; the native content classes also gained docstrings, so the instructor-side schema carries them too | S1 measured: class-name title, most natives with **no top-level description**. Nested concept identity (`$defs` keyed by class-name spelling) stays descriptor-only, per the E1 ruling |
## 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`) |
+| `?` optional marker | **reshaped by S2 (E5):** `presence: "optional"` on the contract (the two-valued `optional` flag is gone from inputs); the `json_schema` itself is unchanged | **survives**, now three-valued |
+| `[]` list marker | `json_schema` wrapped as `{type: array, items: <hop-3 schema>}` at the hop-4 render, no bounds; the contract states `multiplicity: "variable"` (E9) and the memo key carries the real multiplicity | **survives** as array wrapping + a stated contract fact |
+| `[N]` fixed count (`Gadget[2]`) | **closed by S2 (E4+E9):** the render emits `minItems: N` / `maxItems: N` on the array wrap, and the contract states `multiplicity: "fixed"` + `item_count: N` (`[1]` stays single) | S1 measured: **count dropped at hop 4** (`is_multiple()` collapse). Now visible on `hop4_schema_renders/input_semantics_probe.probe_markers.two.json` and hop 5's `two` entry |
+| `!` force marker | **closed by S2 (E5):** the contract reports `presence: "force"` — the authored assertion reaches lint and graph surfaces | S1 measured: **force/plain distinction dropped at hop 5**. Output presence stays two-valued (`!` is rejected on outputs) |
| 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/`)
@@ -64,10 +64,14 @@
- 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).
+- Unknown keys in a structure-field table — refused since S2 (E7, `extra="forbid"`); see `rejected/unknown_structure_field_key.mthds_invalid`.
+- `required = true` together with `default_value` — refused since S2 (E3); see `rejected/required_with_default.mthds_invalid`.
## 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.
+All four fed S2 and the first three are closed there (the fourth was the good news that scoped it):
+
+- **Unknown structure-field keys vanish silently at parse.** ~~`ConceptStructureBlueprint` ignores extras~~ — closed by E7 (`extra="forbid"`).
+- **`required` + `default_value` together: the default wins and the required-ness is dropped** by the generator's parameter ordering — closed by E3 (the pair is rejected at validation; the generator branch is now an explicit invariant).
+- **`is_multiple()` collapses `[N]` to a bare bool** before the render — closed by E4 (real multiplicity threaded through the render and the memo key).
+- **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. This is what made S2 an upstream-only worklist.