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.

fix/Dead-natives-version-constant · L-260917-87199b (#1208)

Louis Choquel6700b9dc1cf6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b00dd58a5..68a820f7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Fixed
+
+- **`PINNED_NATIVES_MTHDS_VERSION` names the set it labels**: the constant read `1.0.0` while the standard pins the native set at `2.0.0`, so anything taking it as the answer to "which pinned set is this engine's" — a downstream port gating its own native goldens, for one — read a version the standard now describes as predating the pinning regime. It now reads `2.0.0`, and it is no longer a value nothing reads: the standard-conformance suite holds it to the page's own "Pinned at MTHDS" statement, and a check that needs no sibling checkout refuses a label later than the standard version this engine implements.
+
## [v0.59.0] - 2026-09-16
### Added
diff --git a/pipelex/core/concepts/native/pinned_blueprints.py b/pipelex/core/concepts/native/pinned_blueprints.py
index fdc1e8cff..fb2fe02ca 100644
--- a/pipelex/core/concepts/native/pinned_blueprints.py
+++ b/pipelex/core/concepts/native/pinned_blueprints.py
@@ -12,15 +12,25 @@ standard's page itself, read live from the sibling `mthds/` checkout (the `MTHDS
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.
+The set below is the one the standard pinned at MTHDS 2.0.0, named by
+`PINNED_NATIVES_MTHDS_VERSION`. Version-keyed lookup can come when a second pinned set exists;
+until then an implementation of standard version `V` materializes the greatest pinned set not
+above `V`, and this is the only one there is.
"""
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint, ConceptStructureBlueprintType
from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType
from pipelex.core.concepts.native.concept_native import NativeConceptCode
-PINNED_NATIVES_MTHDS_VERSION = "1.0.0"
+# The standard version in which the pinned set below last changed — the standard asks each
+# implementation to declare that number once, in one place, naming its source: the page's own
+# "The Pinned Set — Pinned at MTHDS <version>" heading in `mthds/docs/spec/native-concepts.md`.
+# It is NOT the standard version this engine implements (`MTHDS_STANDARD_VERSION`, which is what a
+# crate's `mthds_version` stamp records), and the two only coincide while the set's last re-pinning
+# is the latest release of the standard. `tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py`
+# holds this value to the page; `test_pinned_natives_version.py` beside it holds it to the standard
+# version this engine implements, which is the reading that needs no sibling checkout.
+PINNED_NATIVES_MTHDS_VERSION = "2.0.0"
def make_pinned_native_blueprint(native_code: NativeConceptCode) -> ConceptBlueprint:
diff --git a/tests/unit/pipelex/core/concepts/test_pinned_natives_version.py b/tests/unit/pipelex/core/concepts/test_pinned_natives_version.py
new file mode 100644
index 000000000..5d0ff8832
--- /dev/null
+++ b/tests/unit/pipelex/core/concepts/test_pinned_natives_version.py
@@ -0,0 +1,34 @@
+"""The label on the pinned native set, held against the standard this engine implements.
+
+`PINNED_NATIVES_MTHDS_VERSION` names the standard version in which the pinned native set last
+changed. The authority on that number is the standard's own page, and `test_pinned_natives_vs_standard.py`
+holds the constant to it — but that comparison reads the sibling `mthds/` checkout and skips without
+it, which is most contributors most of the time. This module is the reading that needs nothing but
+the installed `mthds`.
+
+It is a bound in one direction, deliberately: without the page, nothing here can know whether the
+standard re-pinned the set at its latest version, so a label that *lags* a re-pinning — which is how
+this constant sat at `1.0.0` across the standard's `2.0.0` cut — is the page comparison's to catch
+and not this one's. What this module catches is the other direction, a label naming a standard
+version this engine does not implement.
+"""
+
+from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION
+
+from pipelex.core.concepts.native.pinned_blueprints import PINNED_NATIVES_MTHDS_VERSION
+from pipelex.tools.misc.semver import parse_version
+
+
+class TestPinnedNativesVersionAgreesWithTheEngine:
+ def test_pinned_set_is_not_from_a_standard_version_this_engine_does_not_implement(self):
+ """An implementation of standard version `V` materializes the greatest pinned set not above `V`.
+
+ `pinned_blueprints.py` holds exactly one pinned set, so the rule reduces to a bound: the set
+ it holds cannot have been pinned by a standard version later than the one the installed
+ `mthds` implements. A pin bump that moves the standard backwards, or a re-pinning transcribed
+ into this repo ahead of the `mthds` bump that carries it, fails this without needing the page.
+ """
+ assert parse_version(PINNED_NATIVES_MTHDS_VERSION) <= parse_version(MTHDS_STANDARD_VERSION), (
+ f"the pinned native set is labelled {PINNED_NATIVES_MTHDS_VERSION!r}, later than the standard version this "
+ f"engine implements ({MTHDS_STANDARD_VERSION!r}) — this engine cannot materialize a set pinned in the future"
+ )
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
index 6f12a1016..1cf84e693 100644
--- a/tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py
+++ b/tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py
@@ -23,6 +23,13 @@ consequences follow, both by design:
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.
+
+`PINNED_NATIVES_MTHDS_VERSION` — the number naming *which* set this is — is held here too, because
+a value nothing reads is a value that goes stale in silence: it sat at `1.0.0` across the standard's
+`2.0.0` cut, and no test in this repo could say so. This module holds it to the page, and therefore
+skips with everything else when the checkout is absent; `test_pinned_natives_version.py` holds it to
+the standard version the installed `mthds` reports, which needs no checkout and so runs for every
+contributor.
"""
import re
@@ -34,7 +41,7 @@ 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
+from pipelex.core.concepts.native.pinned_blueprints import PINNED_NATIVES_MTHDS_VERSION, 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.
@@ -74,7 +81,34 @@ def read_spec_definitions() -> list[tuple[str, dict[str, Any]]]:
return definitions
+def read_spec_pinned_version() -> str:
+ """The standard version the page says the set below it was pinned at.
+
+ The page states it twice — once in prose ("The set below was pinned at MTHDS `2.0.0`") and once
+ in the heading that opens the set ("The Pinned Set — Pinned at MTHDS 2.0.0"). Both spellings are
+ collected and required to agree, so a half-done re-pinning on the page is a failure here rather
+ than a coin toss over which sentence this reader happened to match.
+ """
+ statements: list[str] = re.findall(r"[Pp]inned at MTHDS\s+`?(\d+\.\d+\.\d+)`?", SPEC_PAGE.read_text(encoding="utf-8"))
+ assert statements, "the standard's page no longer states the version its native set is pinned at"
+ assert len(set(statements)) == 1, f"the standard's page states more than one pinned version for its native set: {sorted(set(statements))}"
+ return statements[0]
+
+
class TestPinnedNativesAgreeWithTheStandard:
+ def test_names_the_version_the_page_pins_the_set_at(self):
+ """The set is a copy; `PINNED_NATIVES_MTHDS_VERSION` is the label on it, and a mislabelled copy misleads.
+
+ Nothing inside this package reads the constant, so a wrong value breaks nothing here — it
+ misleads whoever reads it as the answer to "which pinned set is this", which is what its
+ name promises, and a downstream port that reports it as this reference's natives version
+ then gates its own goldens against a dead number.
+ """
+ assert read_spec_pinned_version() == PINNED_NATIVES_MTHDS_VERSION, (
+ f"PINNED_NATIVES_MTHDS_VERSION says {PINNED_NATIVES_MTHDS_VERSION!r} but the standard's page pins the set at "
+ f"{read_spec_pinned_version()!r} — {_DISAGREEMENT_REMEDY}"
+ )
+
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], (
diff --git a/wip/pinned-natives-version/deferred-review-findings.md b/wip/pinned-natives-version/deferred-review-findings.md
new file mode 100644
index 000000000..54beb1ff7
--- /dev/null
+++ b/wip/pinned-natives-version/deferred-review-findings.md
@@ -0,0 +1,24 @@
+---
+status: active
+item: L-260917-87199b
+---
+
+# Deferred review findings — the pinned-natives version constant
+
+Two findings from the round-2 `/rev` pass on `fix/Dead-natives-version-constant` (profile 2, bar `defects`) that were real but not defects that matter at that bar. Both are unverified: no verifier was paid for them, because the bar would have deferred them whatever a verifier said.
+
+## The page-version reader matches "pinned at MTHDS" too loosely (unverified)
+
+`tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py`, in `read_spec_pinned_version`.
+
+The regex is `[Pp]inned at MTHDS\s+`?(\d+\.\d+\.\d+)`?`, collected over the whole page, with every match required to agree. Today the standard's `native-concepts.md` has exactly two matches and both say `2.0.0`, so the reader is correct and the unanimity check is what makes a half-done re-pinning on the page a failure rather than a coin toss.
+
+The claim is that `[Pp]inned` also matches inside `re-pinned`, `un-pinned` and `previously pinned`, so a page that one day writes "previously pinned at MTHDS `2.0.0`" beside a new "Pinned at MTHDS `3.0.0`" would fail the unanimity assertion with a message saying the page states more than one pinned version — a red that is neither a pipelex bug nor the drift the assertion exists to diagnose. Because this module reads the sibling checkout deliberately unpinned, such a red can land on an unrelated pull request.
+
+Nothing on the page has that shape today, so this is a robustness question about wordings the standard has not used. If it is ever worth narrowing, anchoring to the heading spelling alone — the `## The Pinned Set — Pinned at MTHDS <version>` line — is the change, and it trades the prose/heading cross-check away for it.
+
+## The changelog entry narrates its own test coverage (unverified)
+
+`CHANGELOG.md`, the `## [Unreleased]` entry for this constant.
+
+`.claude/rules/changelog.md` asks an entry to say the change a consumer can see and to leave out test rewrites. The entry's second half describes the two readers the change adds. The counter-argument, and why it was left alone: "has no reader" is half of what the ledger item reported as the bug, so the readers are the fix rather than tests incidental to it. The entry is within the rule's one-to-three-sentence bound either way. Worth a second look when the release entry is cut, where a shorter form may read better beside its neighbours.