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.

Hold the pinned natives to the standard's page, and catch up to MTHDS v0.9.0 (#1155)

Louis Choquelbdd853c41b57
diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.toml
index 1a78ff3aa..8e629b392 100644
--- a/.drift/acks/pipelex-kernel-docs.toml
+++ b/.drift/acks/pipelex-kernel-docs.toml
@@ -1,12 +1,12 @@
contract = "pipelex-kernel-docs"
-digest = "sha256:72913ee5d4505143e4919037ef9dd8012392f895197ea56513caec82dd42b85a"
+digest = "sha256:835a768141c5702b53e3924ae1b50d218d89cbf2038049432b7d610738a2123d"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-21T09:18:48Z"
-rationale = "Trigger fired on a lint-comment migration only. The ruff 0.16 upgrade rewrote two suppressions in tests/unit/pipelex/kernel/test_kernel_boot_contract.py from '# noqa: S404/S603' to the new '# ruff: ignore[suspicious-subprocess-import]' / '# ruff: ignore[subprocess-without-shell-equals-true]' spelling; the diff on that file is those two comments and nothing else. No kernel surface moved: PipelexKernel.make, llm_text, llm_object and make_step_metadata are untouched in name and signature, and the boot contract the test asserts is unchanged. docs/under-the-hood/pipelex-kernel.md therefore cannot have gone stale from this change and needs no edit. The page was touched in the same sweep, but only by ruff 0.16's new formatting of Python code blocks inside Markdown (blank lines and trailing-comment spacing) - no prose or code semantics changed."
+reviewed_at = "2026-08-27T08:35:00Z"
+rationale = "Reviewed docs/under-the-hood/pipelex-kernel.md against the compose_ops.py change: build_composed_content no longer fabricates an empty css_class for an Html-shaped output class (native.Html made css_class optional per MTHDS v0.9.0). The doc names the function in the surface table only and does not describe the fabricated value, so nothing is stale and no edit is needed."
[trigger_files]
"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"
-"pipelex/kernel/compose_ops.py" = "blob:d89a27422da1ec41685a93fc7e3e4ab53d2f72bc"
+"pipelex/kernel/compose_ops.py" = "blob:ccd8ba141246380eb5e9d55e693fa6fedf38233a"
"pipelex/kernel/compose_results.py" = "blob:a837ae9680c7d4d0eb4dee37d4657c410e5b5cea"
"pipelex/kernel/exceptions.py" = "blob:45e9ad60c2699f7b57cad0a46c13f0b07b4cfbc9"
"pipelex/kernel/extract_ops.py" = "blob:cd596c03e45ab57eccca6fe1bf332e5977d1f2b2"
diff --git a/.github/workflows/mthds-standard-check.yml b/.github/workflows/mthds-standard-check.yml
new file mode 100644
index 000000000..986a7ced7
--- /dev/null
+++ b/.github/workflows/mthds-standard-check.yml
@@ -0,0 +1,69 @@
+name: MTHDS standard conformance
+
+# Holds this repo's pinned native-concept set against the standard's own page,
+# `mthds/docs/spec/native-concepts.md`, read from a fresh checkout of the standard's repository.
+#
+# The standard is checked out UNPINNED, at its default branch, on purpose: the page is the
+# authority this implementation answers to, and reading a pinned copy would only re-assert that
+# two files this repo controls still match. The consequence is deliberate and worth stating
+# loudly, because this repo has heavy PR traffic:
+#
+# A RED HERE CAN ARRIVE WITH NO PIPELEX COMMIT INVOLVED. When the standard ships a
+# definition change, this check goes red on every PR until the pinned set catches up.
+# That red means "the standard moved" — it is not the PR's fault. The remedy is a
+# dedicated change bringing pinned_blueprints.py (and the matching runtime content
+# class) to the page, never a tweak to whatever PR happened to be open.
+
+on:
+ pull_request:
+ workflow_dispatch:
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+ cancel-in-progress: true
+
+jobs:
+ natives-vs-standard:
+ name: "Pinned natives vs the standard's page (a red with no pinned-set change in this PR means the standard moved)"
+ runs-on: ubuntu-latest
+ env:
+ VIRTUAL_ENV: ${{ github.workspace }}/pipelex/.venv
+ ENV: dev
+ # The documented workspace layout, reproduced on the runner: this repo and the standard as
+ # siblings, so the test's `../mthds` path resolves exactly as it does on a developer machine.
+ # `actions/checkout` refuses a path outside $GITHUB_WORKSPACE, so the sibling can only exist
+ # if this repo stops being the workspace root; `defaults.run` moves `run:` steps back into it.
+ defaults:
+ run:
+ working-directory: pipelex
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ path: pipelex
+
+ # The MTHDS standard's own repository — public, so GITHUB_TOKEN is credential enough.
+ - uses: actions/checkout@v4
+ with:
+ repository: mthds-ai/mthds
+ path: mthds
+ fetch-depth: 1
+ persist-credentials: false
+
+ # The conformance test names its own absence and skips when the sibling is missing — right
+ # for a contributor's machine, wrong here, where running it is this job's whole purpose. A
+ # missing page must be THIS loud step failing, never a green run full of skips.
+ - name: Refuse to run without the standard's page
+ run: test -f ../mthds/docs/spec/native-concepts.md
+
+ - name: Install uv (with cache)
+ uses: astral-sh/setup-uv@v7
+ with:
+ enable-cache: true
+ cache-dependency-glob: "pipelex/uv.lock"
+
+ - name: Install dependencies
+ run: PYTHON_VERSION=3.11 make install
+
+ - name: Hold the pinned natives to the standard's page
+ run: .venv/bin/pytest tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py -v
diff --git a/.test_durations b/.test_durations
index f8cb25602..be7ed461c 100644
--- a/.test_durations
+++ b/.test_durations
@@ -4749,6 +4749,37 @@
"tests/unit/pipelex/core/concepts/test_helpers.py::TestStripMarkersFromConceptStringOrCode::test_strip_markers[my_domain.ConceptCode[]-my_domain.ConceptCode]": 0.0004,
"tests/unit/pipelex/core/concepts/test_helpers.py::TestStripMarkersFromConceptStringOrCode::test_strip_markers[my_domain.ConceptCode[]?-my_domain.ConceptCode]": 0.1183,
"tests/unit/pipelex/core/concepts/test_helpers.py::TestStripMarkersFromConceptStringOrCode::test_strip_markers[some_domain.MyConceptCode[42]-some_domain.MyConceptCode]": 0.0007,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Anything]": 1.414,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Composite]": 0.0211,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Date]": 1.4372,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Document]": 0.0178,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Dynamic]": 1.3322,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Html]": 1.3813,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Image]": 1.3993,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[JSON]": 0.0188,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Number]": 1.4346,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Page]": 1.424,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[SearchResult]": 0.0168,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[TextAndImages]": 0.0196,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Text]": 0.0019,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[Time]": 0.0198,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_keeps_the_structure_fields_in_the_pages_order[YesNo]": 0.0199,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_pins_the_same_natives_in_the_pages_own_section_order": 1.3378,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Anything]": 1.3363,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Composite]": 0.0199,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Date]": 0.0147,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Document]": 1.415,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Dynamic]": 0.0184,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Html]": 0.0137,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Image]": 0.0187,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[JSON]": 1.334,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Number]": 0.014,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Page]": 0.0393,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[SearchResult]": 0.0196,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[TextAndImages]": 1.4122,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Text]": 1.3397,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[Time]": 1.34,
+ "tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py::TestPinnedNativesAgreeWithTheStandard::test_transcribes_the_definition_exactly_as_the_page_states_it[YesNo]": 1.3842,
"tests/unit/pipelex/core/concepts/test_special_args_concept.py::TestSpecialArgsConcept::test_create_concept_with_content_field": 2.2145,
"tests/unit/pipelex/core/concepts/test_validation.py::TestConceptValidation::test_is_concept_code_valid[-False]": 0.0004,
"tests/unit/pipelex/core/concepts/test_validation.py::TestConceptValidation::test_is_concept_code_valid[123Concept-False]": 0.0003,
@@ -5215,8 +5246,10 @@
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_html": 0.0009,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_html_async": 0.0024,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_html_escapes_css_class": 0.0018,
+ "tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_html_without_css_class": 0.192,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_json": 0.0009,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_json_async": 0.1416,
+ "tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_json_without_css_class": 1.4292,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_markdown": 0.0007,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_markdown_async": 0.0022,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py::TestHtmlContentRenders::test_rendered_plain": 1.0012,
@@ -5224,7 +5257,9 @@
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_returns_dict": 1.032,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_various_inputs[--expected_output0]": 0.001,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_various_inputs[<div>test</div>-container-expected_output1]": 0.0008,
+ "tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_various_inputs[<p>bare</p>-None-expected_output3]": 0.229,
"tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_various_inputs[plain text-highlight-expected_output2]": 0.1243,
+ "tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py::TestHtmlContentSmartDump::test_smart_dump_without_css_class": 0.2732,
"tests/unit/pipelex/core/stuffs/image_content/test_image_content_dimensions.py::TestImageContentDimensions::test_accepts_both_dimensions_or_neither[dimensions-known]": 0.1359,
"tests/unit/pipelex/core/stuffs/image_content/test_image_content_dimensions.py::TestImageContentDimensions::test_accepts_both_dimensions_or_neither[dimensions-unknown]": 0.0004,
"tests/unit/pipelex/core/stuffs/image_content/test_image_content_dimensions.py::TestImageContentDimensions::test_rejects_unpaired_or_non_positive_dimensions[height-only]": 0.0013,
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a710c2dfc..a5e891288 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,15 @@
## [Unreleased]
+### Added
+
+- **Live conformance check against the standard's native-concepts page**: A new test holds the pinned native-concept set (`pinned_blueprints.py`) to the standard's own `native-concepts.md`, read from the sibling `mthds` checkout — definition for definition and field for field, section and field order included. The dedicated `MTHDS standard conformance` CI workflow checks the standard out beside this repo (unpinned, at its default branch) and runs the check on every pull request, so the day the standard moves a definition this repo goes red instead of a downstream port. A red with no pinned-set change in the PR means the standard moved, not that the PR broke something; the remedy is a dedicated catch-up change.
+
### Changed
+- **`native.Html`'s `css_class` is optional (Breaking)**: Matching MTHDS v0.9.0, `HtmlContent.css_class` is now `str | None = None` and the pinned blueprint no longer marks the field required — an `Html` value is its markup, and the class is presentation a producer states when it has one. Composed HTML no longer fabricates an empty `css_class` to satisfy the model, JSON rendering omits an unset class instead of emitting an empty string, and structured output no longer forces a generating LLM to invent presentation data nobody asked for.
+- **`native.Date` and `native.Html` are `object` nodes in the input-form descriptor (Breaking for descriptor consumers)**: The derivation moves both onto the standard's object arm, deriving `fields` from the pinned definitions like the other structured natives — a `Date` slot is an object with a required `date` and an optional `time` child, an `Html` slot an object with a required `inner_html` and an optional `css_class` — instead of the former `date` and `prose` scalars, which reported shapes the slots' own schemas rejected.
+- **Input-form descriptor conformance fixes (Breaking for descriptor consumers)**: A description-only concept's `refines` now carries the authored chain alone (absent when nothing was authored) instead of a fabricated `native.Text` link the spec forbids reconstructing — text-valuedness still reaches the wire as `kind: "prose"`. And a list's `item` node no longer carries a `name` member: the spec states an item has no authored name, and the index labels entries.
- **The input-form descriptor and the pipe I/O contracts are typed by the standard now (Breaking for importers)**: The wire models of both artifacts are declared once, by the MTHDS standard's Python client, and Pipelex imports them instead of restating them. `pipelex/pipeline/pipe_io_contracts.py` re-exports `PipeInputContract`, `PipeOutputContract`, `PipeIOContract` and `IOMultiplicity` from `mthds.protocol.pipe_io_contracts`; `pipelex/pipeline/input_form.py` re-exports `FieldKind`, `PipeInputFormDescriptor` and the field models from `mthds.protocol.input_form`; and `pipelex/core/pipes/variable_multiplicity.py` re-exports `PresenceMarker` from the contracts module, since the marker is part of the contract's wire vocabulary. **The wire is unchanged** — every field name, every value, and every absent-versus-null rule is the one the engine already emitted, and the derivation is the same derivation. What moved is which package declares the shape. Importers are affected in three ways: a field descriptor is now one model per kind (`TextField`, `ProseField`, `DateField`, `NumberField`, `BooleanField`, `EnumField`, `DocumentField`, `ImageField`, `ObjectField`, `ListField`, `UnknownField`) under an `InputFormField` union discriminated on `kind`, so a node is narrowed with `isinstance` or a `match` on its class rather than read off a flat model; `FieldKind.is_list` and `FieldKind.is_object` are gone with that narrowing; and the `date` kind's Python attribute is now `datetime`, the name it always had on the wire, rather than `datetime_flag`. Because the engine constructs the standard's own closed shapes, a drift between what it emits and what the standard defines now fails at derivation instead of silently on the wire. See [Input-form descriptor](under-the-hood/input-form-descriptor.md) and [Pipe I/O contracts](under-the-hood/pipe-io-contracts.md).
- **`PresenceMarker`'s symbol grammar moved off the enum (Breaking)**: The marker enum is the standard's, so the three helpers that are this engine's `.mthds` suffix grammar rather than wire vocabulary became module-level functions in `pipelex/core/pipes/variable_multiplicity.py`: `PresenceMarker.from_symbol(...)` is `presence_from_symbol(symbol=...)`, `marker.symbol` is `presence_symbol(presence=marker)`, and `marker.is_force` is `is_force_presence(presence=marker)`, all keyword-only per this repo's convention. `is_optional` and `is_plain` stay properties on the enum, which the standard declares.
- **Minimum `mthds` version**: The floor moves to `mthds>=0.9.0`, the release that carries `mthds/protocol/pipe_io_contracts.py` and `mthds/protocol/input_form.py`.
diff --git a/docs/building-methods/concepts/native-concepts.md b/docs/building-methods/concepts/native-concepts.md
index 6a6ee3c85..532bf81ed 100644
--- a/docs/building-methods/concepts/native-concepts.md
+++ b/docs/building-methods/concepts/native-concepts.md
@@ -36,7 +36,7 @@ Here are all the native concepts you can use out of the box:
| `Page` | A document page with text, images, and optional page view | `PageContent` |
| `Dynamic` | A dynamic concept that adapts to context | `DynamicContent` |
| `JSON` | A JSON object | `JSONContent` |
-| `Html` | HTML content with inner HTML and CSS class | `HtmlContent` |
+| `Html` | HTML content with inner HTML and optional CSS class | `HtmlContent` |
| `SearchResult` | A web search result with answer and sources | `SearchResultContent` |
| `Composite` | A named composition of contents | `CompositeContent` |
| `Anything` | Any type of content | *No specific implementation* |
@@ -247,13 +247,13 @@ Represents HTML content with styling:
```python
class HtmlContent(StuffContent):
inner_html: str
- css_class: str
+ css_class: str | None = None
```
**Fields:**
- `inner_html`: The inner HTML of the content
-- `css_class`: The CSS class applied to the wrapping element
+- `css_class`: The CSS class applied to the wrapping element, optional — content that needs no wrapper simply omits it, and the HTML rendering then returns the raw `inner_html` with no wrapping `div`
**Use for:** Rendered HTML fragments, styled content blocks, HTML-based reports.
diff --git a/docs/under-the-hood/input-form-descriptor.md b/docs/under-the-hood/input-form-descriptor.md
index 7133cd762..37857c23f 100644
--- a/docs/under-the-hood/input-form-descriptor.md
+++ b/docs/under-the-hood/input-form-descriptor.md
@@ -30,25 +30,24 @@ Kinds are decided by chain membership and declared types — never by sniffing a
1. A concept with an authored structure *table* anywhere along its refinement chain is an `object`; its fields are the merged structures along the chain, base fields first, a refining concept overriding its parents'. The table decides even when it is empty — the engine backs an empty `[concept.X.structure]` with a field-less structured model, not with `TextContent`, so the descriptor reports `object` with an empty `fields` list rather than falling through to rule 4.
2. Otherwise, the first `structure = "ClassName"` on the chain decides: a native class name (`TextContent`, `ImageContent`, …) maps by identity to that native's row; any other registered class is reflected field by field into an `object`; an unregistered or unmappable class is `unknown`.
3. Otherwise, a chain bottoming at a native concept takes that native's row, keeping the concept's own `concept_ref`, description and `refines`.
-4. Otherwise — a description-only or string-described concept — `prose` with `refines` ending in `native.Text`: this engine backs such a concept with a `TextContent` subclass, so that is a stated fact, not shape invention.
+4. Otherwise — a description-only or string-described concept — `prose`, with `refines` carrying the authored chain alone (absent when nothing was authored): a producer states only the links it holds, so no `native.Text` link is reconstructed — text-valuedness reaches the wire as the `prose` kind itself.
The crate the deriver reads is the current library's accumulated one, which holds the validated bundle and every `library_dirs` bundle loaded beside it — so a concept from a library dir, or a local concept refining one, follows the same rules as a local concept. A concept absent from that crate altogether is `unknown`.
-The table and rules above ARE the no-hint kind assignment — stated rules, not heuristics: with no applicable intent hint, a node's kind is exactly what they produce. An applicable authored `intent` (spec: MTHDS `intent-hints.md`) *feeds* that assignment, never competes with it: on a **text-valued** node — one whose site is a `text` field, a `native.Text`-chained or description-only concept, judged per item on plural sites — an effective `intent = "prose"` yields `kind: "prose"` and `intent = "label"` yields `kind: "text"`; an absent, unknown, or inapplicable intent leaves the no-hint kind untouched. On a **number-valued** node, `rating` and `quantity` never change `kind` (both are `number`; the union has no finer kind) — they ride the `hints` slot for the renderer to honor. A time-formatted `text` node and an `Html`-backed `prose` node are *not* text-valued sites, so no intent word applies to them.
+The table and rules above ARE the no-hint kind assignment — stated rules, not heuristics: with no applicable intent hint, a node's kind is exactly what they produce. An applicable authored `intent` (spec: MTHDS `intent-hints.md`) *feeds* that assignment, never competes with it: on a **text-valued** node — one whose site is a `text` field, a `native.Text`-chained or description-only concept, judged per item on plural sites — an effective `intent = "prose"` yields `kind: "prose"` and `intent = "label"` yields `kind: "text"`; an absent, unknown, or inapplicable intent leaves the no-hint kind untouched. On a **number-valued** node, `rating` and `quantity` never change `kind` (both are `number`; the union has no finer kind) — they ride the `hints` slot for the renderer to honor. A time-formatted `text` node is *not* a text-valued site, so no intent word applies to it (and `native.Html`, being an `object` node, never reaches the text-valued judgment at all).
| Native concept | Kind |
|---|---|
-| `Text`, `Html` | `prose` |
+| `Text` | `prose` |
| `Number` | `number` with `integer: false` |
| `YesNo` | `boolean` |
-| `Date` | `date` with `datetime: false` |
| `Time` | `text` with `format: "time"` |
| `Document` | `document` |
| `Image` | `image` |
-| `Page`, `TextAndImages`, `SearchResult` | `object` over the pinned blueprint's fields |
+| `Date`, `Html`, `Page`, `TextAndImages`, `SearchResult` | `object` over the pinned blueprint's fields |
| `Dynamic`, `Anything`, `JSON` | `unknown` |
-Nested structure fields map by their declared type: `text` → `text`; `integer` → `number` with `integer: true`; `number` → `number`; `boolean` → `boolean`; `date` → `date`; `datetime` → `date` with `datetime: true`; `time` → `text` with `format: "time"`; a field with `choices` → `enum` (choices win over `type`, matching the structure generator); `concept` → the concept's node, carrying its namespaced `concept_ref`; `list` → `list` whose `item` comes from `item_type` / `item_concept_ref` (a nested list's inner item is inexpressible and reports `unknown`); `dict` → `unknown`. The shorthand `field = "description"` form is a required `text`. Nested fields take the blueprint field's description and `required` over the concept's; a scalar flattened at the top level keeps the concept's description.
+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`; the `item` node carries no `name` member — a list's item has no authored name, and the index labels entries); `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 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.)
diff --git a/pipelex/core/concepts/native/pinned_blueprints.py b/pipelex/core/concepts/native/pinned_blueprints.py
index e357505c3..fdc1e8cff 100644
--- a/pipelex/core/concepts/native/pinned_blueprints.py
+++ b/pipelex/core/concepts/native/pinned_blueprints.py
@@ -6,7 +6,11 @@ pinned set: crate materialization looks definitions up here instead of reflectin
content classes, so two independent implementations byte-agree on materialized natives (and
therefore on crate fingerprints). Any edit here is a standard change and must land in the spec
page first; the consistency test in `tests/unit/pipelex/codegen/` proves each runtime content
-class still matches its pinned blueprint, so the two can never drift silently.
+class still matches its pinned blueprint, so the two can never drift silently — and
+`tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py` holds this set to the
+standard's page itself, read live from the sibling `mthds/` checkout (the `MTHDS standard
+conformance` CI workflow runs it against a fresh checkout on every pull request), so the day the
+standard moves a definition, this repo goes red instead of a downstream port.
The set below is the MTHDS 1.0.0 pinned set. Version-keyed lookup can come when a second
standard version exists; today `mthds_version` on the crate records which set was used.
@@ -98,7 +102,7 @@ def _pinned_structure(native_code: NativeConceptCode) -> dict[str, ConceptStruct
case NativeConceptCode.HTML:
return {
"inner_html": _text_field(description="The inner HTML of the content", required=True),
- "css_class": _text_field(description="The CSS class of the content", required=True),
+ "css_class": _text_field(description="The CSS class of the content"),
}
case NativeConceptCode.TEXT_AND_IMAGES:
return {
diff --git a/pipelex/core/stuffs/html_content.py b/pipelex/core/stuffs/html_content.py
index 3e7fc6d3d..915be5235 100644
--- a/pipelex/core/stuffs/html_content.py
+++ b/pipelex/core/stuffs/html_content.py
@@ -12,7 +12,7 @@ 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")
+ css_class: str | None = Field(default=None, description="The CSS class of the content")
@property
@override
@@ -44,4 +44,6 @@ class HtmlContent(StuffContent):
@override
def rendered_json(self) -> str:
+ if self.css_class is None:
+ return json.dumps({"html": self.inner_html})
return json.dumps({"html": self.inner_html, "css_class": self.css_class})
diff --git a/pipelex/kernel/compose_ops.py b/pipelex/kernel/compose_ops.py
index d89a27422..ccd8ba141 100644
--- a/pipelex/kernel/compose_ops.py
+++ b/pipelex/kernel/compose_ops.py
@@ -58,7 +58,7 @@ def build_composed_content(*, output_class: type[StuffContent], rendered_text: s
the `ValidationError` a mismatch raises, are identical either way.
"""
if issubclass(output_class, HtmlContent):
- return output_class.model_validate({"inner_html": rendered_text, "css_class": ""})
+ return output_class.model_validate({"inner_html": rendered_text})
return output_class.model_validate({"text": rendered_text})
diff --git a/pipelex/pipeline/input_form.py b/pipelex/pipeline/input_form.py
index 1c2d6786a..2b48ecd39 100644
--- a/pipelex/pipeline/input_form.py
+++ b/pipelex/pipeline/input_form.py
@@ -184,7 +184,7 @@ class InputFormDeriver:
description=node.description,
required=True,
hints=effective_hints,
- item=_with_effective_hints(node=node, hints=effective_hints),
+ item=_as_list_item(node=_with_effective_hints(node=node, hints=effective_hints)),
item_count=item_count,
)
else:
@@ -288,21 +288,25 @@ class InputFormDeriver:
node_ref = concept_ref or native_code.concept_ref
text = description or pinned.description
match native_code:
- case NativeConceptCode.TEXT | NativeConceptCode.HTML:
+ case NativeConceptCode.TEXT:
return ProseField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True)
case NativeConceptCode.NUMBER:
return NumberField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True, integer=False)
case NativeConceptCode.YES_NO:
return BooleanField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True)
- case NativeConceptCode.DATE:
- return DateField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True, datetime=False)
case NativeConceptCode.TIME:
return TextField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True, format="time")
case NativeConceptCode.DOCUMENT:
return DocumentField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True)
case NativeConceptCode.IMAGE:
return ImageField(name=name, concept_ref=node_ref, refines=refines, description=text, required=True)
- case NativeConceptCode.PAGE | NativeConceptCode.TEXT_AND_IMAGES | NativeConceptCode.SEARCH_RESULT:
+ case (
+ NativeConceptCode.DATE
+ | NativeConceptCode.HTML
+ | NativeConceptCode.PAGE
+ | NativeConceptCode.TEXT_AND_IMAGES
+ | NativeConceptCode.SEARCH_RESULT
+ ):
pinned_structure = pinned.structure if isinstance(pinned.structure, dict) else {}
return ObjectField(
name=name,
@@ -375,7 +379,7 @@ class InputFormDeriver:
that table is empty. The distinction is the engine's own: `ConceptFactory` branches on
`structure is not None`, so an authored-but-empty table is backed by a field-less structured
model with an empty object schema — not by `TextContent`. Testing truthiness here would report
- that concept as `prose` with a `native.Text` refines link nobody authored.
+ that concept as `prose`, contradicting the object schema the engine emits beside it.
"""
merged: dict[str, ConceptStructureBlueprintType] | None = None
for ref in [*reversed(chain), concept_ref]:
@@ -432,7 +436,7 @@ class InputFormDeriver:
required=field.required,
default_value=field.default_value,
hints=effective_hints,
- item=_with_effective_hints(node=item, hints=effective_hints),
+ item=_as_list_item(node=_with_effective_hints(node=item, hints=effective_hints)),
)
case ConceptStructureBlueprintFieldType.DICT | None:
unknown = _unknown_node(name=name, description=field.description, required=field.required, default_value=field.default_value)
@@ -477,6 +481,16 @@ class InputFormDeriver:
return _scalar_field(field_type=item_type, name=name, required=True)
+def _as_list_item(*, node: InputFormField) -> InputFormField:
+ """A node in `item` position: a list's `item` has no authored name and carries no `name` member.
+
+ The spec states the absence outright (the index labels items, and a sentinel would be a value
+ two producers could pick differently), so the element node built from the list's own facts
+ drops the name it was derived under.
+ """
+ return node.model_copy(update={"name": None})
+
+
def _with_effective_hints(*, node: InputFormField, hints: dict[str, str] | None) -> InputFormField:
"""Stamp a node's FINAL effective hints; an applicable `intent` word feeds `kind`, never competes.
@@ -535,8 +549,9 @@ def _node_site_kind(node: InputFormField) -> HintSiteValueKind:
Recomputed from node facts, mirroring the lint's structural judgment (the known divergences are
recorded in wip/engine-hints/deferred.md): `number` nodes come only from `integer`/`number`
fields and `native.Number` chains, so the kind IS the judgment; `text`/`prose` nodes are
- text-valued EXCEPT a time-formatted text (`type = "time"` is neither) and an `Html`-backed node
- (`prose` presentation, but the chain reaches `native.Html`, not `native.Text`).
+ text-valued EXCEPT a time-formatted text (`type = "time"` is neither). A `native.Html` chain
+ derives an `object` node since the standard put it on the object arm, so it never reaches the
+ text-valued case.
"""
match node:
case NumberField():
@@ -544,9 +559,6 @@ def _node_site_kind(node: InputFormField) -> HintSiteValueKind:
case TextField() | ProseField():
if node.format is not None:
return HintSiteValueKind.OTHER
- html_ref = NativeConceptCode.HTML.concept_ref
- if node.concept_ref == html_ref or (node.refines is not None and html_ref in node.refines):
- return HintSiteValueKind.OTHER
return HintSiteValueKind.TEXT_VALUED
case DateField() | BooleanField() | EnumField() | DocumentField() | ImageField() | ObjectField() | ListField() | UnknownField():
return HintSiteValueKind.OTHER
@@ -631,11 +643,16 @@ def _with_reflected_constraints(*, node: InputFormField, field_info: FieldInfo)
def _prose_promoted_node(*, name: str, concept_ref: str, description: str, chain: list[str]) -> InputFormField:
- """A description-only or string-described concept: this engine backs it with a `TextContent` subclass."""
+ """A description-only or string-described concept: this engine backs it with a `TextContent` subclass.
+
+ `refines` is the authored chain alone, terminating wherever it actually terminates — the spec
+ forbids reconstructing links the producer does not hold, so no `native.Text` link is appended.
+ Text-valuedness reaches the wire as `kind: "prose"`.
+ """
return ProseField(
name=name,
concept_ref=concept_ref,
- refines=[*chain, NativeConceptCode.TEXT.concept_ref],
+ refines=chain or None,
description=description,
required=True,
)
diff --git a/tests/integration/pipelex/pipeline/test_input_form.py b/tests/integration/pipelex/pipeline/test_input_form.py
index 75d267a1b..c779f8add 100644
--- a/tests/integration/pipelex/pipeline/test_input_form.py
+++ b/tests/integration/pipelex/pipeline/test_input_form.py
@@ -204,7 +204,7 @@ class TestBuildInputForm:
stringnote = _field_by_name(refined, "stringnote")
assert stringnote.kind == FieldKind.PROSE
assert stringnote.concept_ref == "input_semantics_probe.StringNote"
- assert stringnote.refines == ["native.Text"], "A string-described concept is this engine's TextContent fact"
+ assert stringnote.refines is None, "No refines was authored, and none is reconstructed — text-valuedness is `kind: prose`"
note = _field_by_name(input_form["input_semantics_probe.probe_single"], "note")
assert note.kind == FieldKind.PROSE
@@ -300,14 +300,32 @@ class TestBuildInputForm:
number_in = _field_by_name(natives, "number_in")
assert number_in.kind == FieldKind.NUMBER
assert number_in.integer is False
- date_in = _field_by_name(natives, "date_in")
- assert date_in.kind == FieldKind.DATE
- assert date_in.datetime is False
time_in = _field_by_name(natives, "time_in")
assert time_in.kind == FieldKind.TEXT
assert time_in.format == "time"
- assert _field_by_name(natives, "html_in").kind == FieldKind.PROSE
assert _field_by_name(natives, "yesno_in").kind == FieldKind.BOOLEAN
+
+ # `native.Date` and `native.Html` sit on the standard's object arm: fields from the pinned
+ # definition, like the other structured natives.
+ date_in = _field_by_name(natives, "date_in")
+ assert date_in.kind == FieldKind.OBJECT
+ date_fields = fields_by_name(date_in)
+ assert list(date_fields) == ["date", "time"], "Pinned-blueprint fields, in pinned order"
+ assert date_fields["date"].kind == FieldKind.DATE
+ assert date_fields["date"].datetime is False
+ assert date_fields["date"].required is True
+ assert date_fields["time"].kind == FieldKind.TEXT
+ assert date_fields["time"].format == "time"
+ assert date_fields["time"].required is False
+
+ html_in = _field_by_name(natives, "html_in")
+ assert html_in.kind == FieldKind.OBJECT
+ html_fields = fields_by_name(html_in)
+ assert list(html_fields) == ["inner_html", "css_class"], "Pinned-blueprint fields, in pinned order"
+ assert html_fields["inner_html"].kind == FieldKind.TEXT
+ assert html_fields["inner_html"].required is True
+ assert html_fields["css_class"].kind == FieldKind.TEXT
+ assert html_fields["css_class"].required is False
for field in natives.fields:
assert field.concept_ref is not None
assert field.concept_ref.startswith("native."), f"{field.name} states its native ref, got {field.concept_ref!r}"
@@ -346,7 +364,7 @@ class TestBuildInputForm:
memo = _field_by_name(descriptor, "memo")
assert memo.kind == FieldKind.PROSE
assert memo.description == "A short memo"
- assert memo.refines == ["native.Text"]
+ assert memo.refines is None, "A description-only concept authored no refines, and none is fabricated"
special = _field_by_name(descriptor, "special")
assert special.kind == FieldKind.OBJECT
@@ -569,8 +587,8 @@ class TestKindAssignmentTable:
async def test_an_authored_but_empty_structure_table_is_an_object_with_no_fields(self, load_empty_library: Callable[[], str]) -> None:
"""The engine branches on `structure is not None` (`ConceptFactory`), so an empty `[concept.X.structure]`
table is backed by a field-less structured model whose schema is `{"type": "object", "properties": {}}`.
- The descriptor states that same fact: testing truthiness instead would report the concept as `prose`
- with a `native.Text` refinement link nobody authored, contradicting the schema beside it.
+ The descriptor states that same fact: testing truthiness instead would report the concept as `prose`,
+ contradicting the object schema beside it.
"""
input_form = await self._derive_kind_table(load_empty_library)
empties = input_form["input_form_kinds.empty_structures"]
diff --git a/tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py b/tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py
new file mode 100644
index 000000000..6f12a1016
--- /dev/null
+++ b/tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py
@@ -0,0 +1,108 @@
+"""The pinned native-concept set, held against the standard's own page.
+
+`pipelex/core/concepts/native/pinned_blueprints.py` is a *copy* — the MTHDS standard pins the
+normative definitions in `mthds/docs/spec/native-concepts.md`, and a copy that nothing compares is
+a copy that drifts. Drift here is not cosmetic: the materialized natives are hashed into a crate's
+fingerprint, so one reworded field description gives two conforming producers two different digests
+for the same library. The consistency probe in `tests/unit/pipelex/codegen/test_native_expansion.py`
+compares this repo's two copies (the pinned set and the runtime content classes) to *each other*;
+this module is the missing third leg — the comparison against the authority both answer to.
+
+The page is read live from the sibling `mthds/` checkout, at whatever state that checkout is in —
+deliberately unpinned, because the standard is the authority this implementation answers to, and
+reading a pinned copy would only re-assert that two files this repo controls still match. Two
+consequences follow, both by design:
+
+- **A red here can arrive with no pipelex commit involved.** When the standard ships a definition
+ change, this check goes red on every PR until the pinned set catches up. That red means "the
+ standard moved" — it is not the PR's fault, and the remedy is a dedicated change bringing
+ `pinned_blueprints.py` (and the matching runtime content class) to the page, never a tweak to
+ whatever PR happened to be open.
+- **Absence is named, never silently passed over.** Without the sibling checkout the module skips
+ with the reason below — kept so a contributor does not need the whole workspace to run the
+ suite. It is not an opt-out: the `MTHDS standard conformance` workflow checks the standard out
+ beside this repo and runs this module on every pull request, so a disagreement with the page
+ fails the merge either way.
+"""
+
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.native.pinned_blueprints import make_pinned_native_blueprint
+
+# This repo and the standard's repo as siblings — the documented workspace layout, reproduced on
+# CI runners by the `MTHDS standard conformance` workflow's double checkout.
+_REPO_ROOT = Path(__file__).resolve().parents[5]
+SPEC_PAGE = _REPO_ROOT.parent / "mthds" / "docs" / "spec" / "native-concepts.md"
+
+pytestmark = pytest.mark.skipif(
+ not SPEC_PAGE.exists(),
+ reason=(
+ "needs the standard's own repository checked out at ../mthds — without it the pinned set is compared "
+ "against nothing here (the codegen consistency probe still runs, and the 'MTHDS standard conformance' "
+ "CI workflow runs this module against a fresh checkout on every pull request)"
+ ),
+)
+
+_DISAGREEMENT_REMEDY = (
+ "if this change did not touch the pinned set, the MTHDS standard moved and this repo is behind it — "
+ "that red is not this PR's fault; bring pinned_blueprints.py and the matching runtime content class "
+ "to the page in a dedicated change"
+)
+
+
+def read_spec_definitions() -> list[tuple[str, dict[str, Any]]]:
+ """The `### native.<Code>` definitions, read out of the spec page's fenced TOML blocks.
+
+ Every fenced `toml` block on that page is one definition, written as an author would write the
+ concept — the same structure language the pinned set is authored in, so the comparison below is
+ a plain deep equality rather than a projection. Returned as a list so section *order* is
+ comparable too.
+ """
+ page = SPEC_PAGE.read_text(encoding="utf-8")
+ definitions: list[tuple[str, dict[str, Any]]] = []
+ for block in re.findall(r"```toml\n(.*?)```", page, flags=re.DOTALL):
+ table = tomllib.loads(block)
+ for code, definition in table.get("concept", {}).items():
+ definitions.append((code, definition))
+ return definitions
+
+
+class TestPinnedNativesAgreeWithTheStandard:
+ def test_pins_the_same_natives_in_the_pages_own_section_order(self):
+ page_codes = [code for code, _ in read_spec_definitions()]
+ assert page_codes == [code.value for code in NativeConceptCode], (
+ f"the standard's page and this repo's pinned set disagree on which natives exist, or in what order — {_DISAGREEMENT_REMEDY}"
+ )
+
+ @pytest.mark.parametrize("native_code", list(NativeConceptCode))
+ def test_transcribes_the_definition_exactly_as_the_page_states_it(self, native_code: NativeConceptCode):
+ """Deep equality, definition for definition and field for field, descriptions included.
+
+ The page's authored TOML parses into the same `ConceptBlueprint` model the pinned set is
+ built from, so one comparison covers every member — a field added, a type changed, a
+ `required` flipped, a description reworded — and the model's closed shape (extra="forbid")
+ makes a member it does not know a loud failure rather than a silent drop.
+ """
+ page_definition = dict(read_spec_definitions()).get(native_code.value)
+ assert page_definition is not None, f"the page has no definition for native.{native_code.value}"
+ assert make_pinned_native_blueprint(native_code) == ConceptBlueprint.model_validate(page_definition), (
+ f"native.{native_code.value}: the pinned blueprint disagrees with the standard's page — {_DISAGREEMENT_REMEDY}"
+ )
+
+ @pytest.mark.parametrize("native_code", list(NativeConceptCode))
+ def test_keeps_the_structure_fields_in_the_pages_order(self, native_code: NativeConceptCode):
+ """Field order is normative (it governs the crate's emitted encodings), and dict equality cannot see it."""
+ page_definition: dict[str, Any] = dict(read_spec_definitions()).get(native_code.value) or {}
+ page_structure: dict[str, Any] = page_definition.get("structure") or {}
+ pinned_structure = make_pinned_native_blueprint(native_code).structure
+ pinned_keys = list(pinned_structure.keys()) if isinstance(pinned_structure, dict) else []
+ assert pinned_keys == list(page_structure.keys()), (
+ f"native.{native_code.value}: the pinned structure's field order disagrees with the page — {_DISAGREEMENT_REMEDY}"
+ )
diff --git a/tests/unit/pipelex/core/stuffs/html_content/test_data.py b/tests/unit/pipelex/core/stuffs/html_content/test_data.py
index 33f05381b..371ac5dc7 100644
--- a/tests/unit/pipelex/core/stuffs/html_content/test_data.py
+++ b/tests/unit/pipelex/core/stuffs/html_content/test_data.py
@@ -8,12 +8,15 @@ class TestData:
# Expected outputs for smart_dump
EXPECTED_SMART_DUMP: ClassVar[dict[str, Any]] = {"inner_html": "<p>Hello World</p>", "css_class": "my-class"}
+ EXPECTED_SMART_DUMP_NO_CLASS: ClassVar[dict[str, Any]] = {"inner_html": "<p>Hello World</p>", "css_class": None}
# Expected outputs for render methods
EXPECTED_RENDERED_PLAIN = "<p>Hello World</p>"
EXPECTED_RENDERED_MARKDOWN = "<p>Hello World</p>"
EXPECTED_RENDERED_HTML = '<div class="my-class"><p>Hello World</p></div>'
EXPECTED_RENDERED_JSON = '{"html": "<p>Hello World</p>", "css_class": "my-class"}'
+ EXPECTED_RENDERED_JSON_NO_CLASS = '{"html": "<p>Hello World</p>"}'
+ EXPECTED_RENDERED_HTML_NO_CLASS = "<p>Hello World</p>"
EXPECTED_RENDERED_FOR_PROMPT = "<p>Hello World</p>"
# XSS protection test cases
diff --git a/tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py b/tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py
index b73ef1f9e..4c99902e4 100644
--- a/tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py
+++ b/tests/unit/pipelex/core/stuffs/html_content/test_html_content_renders.py
@@ -27,11 +27,21 @@ class TestHtmlContentRenders:
content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML, css_class=TestData.XSS_CSS_CLASS)
assert content.rendered_html() == TestData.EXPECTED_XSS_PROTECTED_HTML
+ def test_rendered_html_without_css_class(self):
+ """An unset css_class renders the raw inner_html with no wrapping div."""
+ content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML)
+ assert content.rendered_html() == TestData.EXPECTED_RENDERED_HTML_NO_CLASS
+
def test_rendered_json(self):
"""Verify rendered_json returns JSON string with html and css_class keys."""
content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML, css_class=TestData.SAMPLE_CSS_CLASS)
assert content.rendered_json() == TestData.EXPECTED_RENDERED_JSON
+ def test_rendered_json_without_css_class(self):
+ """An unset css_class is omitted from the JSON rendering, never emitted as null."""
+ content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML)
+ assert content.rendered_json() == TestData.EXPECTED_RENDERED_JSON_NO_CLASS
+
def test_rendered_for_prompt(self):
"""Verify rendered_for_prompt returns markdown format (which is inner_html for HtmlContent)."""
content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML, css_class=TestData.SAMPLE_CSS_CLASS)
diff --git a/tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py b/tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py
index 7cb2b02c4..811899efd 100644
--- a/tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py
+++ b/tests/unit/pipelex/core/stuffs/html_content/test_html_content_smart_dump.py
@@ -16,15 +16,21 @@ class TestHtmlContentSmartDump:
assert result == TestData.EXPECTED_SMART_DUMP
assert isinstance(result, dict)
+ def test_smart_dump_without_css_class(self):
+ """An unset optional css_class dumps as None — the field stays in the payload, unset."""
+ content = HtmlContent(inner_html=TestData.SAMPLE_INNER_HTML)
+ assert content.smart_dump() == TestData.EXPECTED_SMART_DUMP_NO_CLASS
+
@pytest.mark.parametrize(
("inner_html", "css_class", "expected_output"),
[
("", "", {"inner_html": "", "css_class": ""}),
("<div>test</div>", "container", {"inner_html": "<div>test</div>", "css_class": "container"}),
("plain text", "highlight", {"inner_html": "plain text", "css_class": "highlight"}),
+ ("<p>bare</p>", None, {"inner_html": "<p>bare</p>", "css_class": None}),
],
)
- def test_smart_dump_various_inputs(self, inner_html: str, css_class: str, expected_output: dict[str, Any]):
+ def test_smart_dump_various_inputs(self, inner_html: str, css_class: str | None, expected_output: dict[str, Any]):
"""Verify smart_dump handles various inputs correctly."""
content = HtmlContent(inner_html=inner_html, css_class=css_class)
result = content.smart_dump()
diff --git a/tests/unit/pipelex/libraries/test_fingerprint_pins.py b/tests/unit/pipelex/libraries/test_fingerprint_pins.py
index 0836810d5..f4096d75e 100644
--- a/tests/unit/pipelex/libraries/test_fingerprint_pins.py
+++ b/tests/unit/pipelex/libraries/test_fingerprint_pins.py
@@ -22,8 +22,12 @@ _PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "p
# 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.
+# The normalized pin was recomputed again when MTHDS v0.9.0 made `native.Html`'s `css_class`
+# optional: normalization materializes the pinned natives into the crate, so a standard change to
+# a pinned definition legitimately moves every conforming implementation's normalized digest — the
+# content pin, which hashes only authored content, did not move.
_PINNED_CONTENT_FINGERPRINT = "053d3ce1a1963feffcea1aaea21e6329a7d2d2371cecdb92eb4a1e51269b0043"
-_PINNED_NORMALIZED_FINGERPRINT = "0a2aac25fe00afb191d52eb12bed7a778a4cab6687bbd1c0455b016e7eae1847"
+_PINNED_NORMALIZED_FINGERPRINT = "8d6fd88088228beb4f5fdad5b204a30146e8fcfc9392df93caa7df37d4ed471a"
_MTHDS_TEST_VERSION = "0.0.0-test"
diff --git a/tests/unit/pipelex/pipeline/test_input_form_models.py b/tests/unit/pipelex/pipeline/test_input_form_models.py
index f1ec5c98d..b8cf0e083 100644
--- a/tests/unit/pipelex/pipeline/test_input_form_models.py
+++ b/tests/unit/pipelex/pipeline/test_input_form_models.py
@@ -78,7 +78,6 @@ class TestInputFormSerialization:
gating=True,
item_count=2,
item=ObjectField(
- name="gadgets",
concept_ref="demo.Gadget",
required=True,
fields=[TextField(name="label", required=True)],
@@ -92,5 +91,6 @@ class TestInputFormSerialization:
item_node = list_node["item"]
assert "presence" not in item_node, "Nested fields never carry pipe-slot facts"
assert "gating" not in item_node
+ assert "name" not in item_node, "A list's item has no authored name and carries no name member"
nested = item_node["fields"][0]
assert nested == {"kind": "text", "name": "label", "required": True}
diff --git a/wip/github-actions-sha-pinning.md b/wip/github-actions-sha-pinning.md
new file mode 100644
index 000000000..cc02b211e
--- /dev/null
+++ b/wip/github-actions-sha-pinning.md
@@ -0,0 +1,18 @@
+# Deferred: pin third-party GitHub Actions to reviewed commit SHAs?
+
+Deferred from PR [#1155](https://github.com/Pipelex/pipelex/pull/1155) review round 1 (2026-08-27). Reported by Greptile and cubic on `.github/workflows/mthds-standard-check.yml:41`:
+
+- [Greptile thread](https://github.com/Pipelex/pipelex/pull/1155#discussion) — `PRRT_kwDOOwmMFc6cwNy5`
+- [cubic thread](https://github.com/Pipelex/pipelex/pull/1155#discussion) — `PRRT_kwDOOwmMFc6cwZvg`
+
+## The issue
+
+The new `mthds-standard-check.yml` workflow references `actions/checkout@v4` and `astral-sh/setup-uv@v7` by mutable major-version tag. A moved tag would silently change the code executed with the workflow's workspace and token permissions. The bots recommend pinning to full commit SHAs.
+
+## Why it deferred
+
+This is not a defect in the PR — it is the repo's standing convention. Existing workflows reference standard actions by mutable tag throughout (`actions/checkout@v4`, `astral-sh/setup-uv@v7`, `actions/setup-python@v5`, …), and SHA pins are reserved for the credential-bearing publish path (`sigstore/gh-action-sigstore-python`, `pypa/gh-action-pypi-publish`, `actions/dependency-review-action`). Pinning three references in one new workflow would change nothing about the repo's supply-chain posture while diverging from its own style. Whether to pin is a repo-wide policy decision, not a per-workflow fix.
+
+## Recommendation
+
+Decide once, for the whole repo: either keep the current tags-for-standard-actions / SHAs-for-privileged-actions split as deliberate policy, or pin every third-party action to a reviewed SHA across all workflows in one sweep (with Dependabot or pin tooling such as `pinact` to keep the pins moving). If pinning wins, the sweep should cover all workflows in `.github/workflows/`, not just the new one.