From 1a874bd456df8725d74e37f54f173899da01c0db Mon Sep 17 00:00:00 2001 From: Polichinl Date: Mon, 10 Aug 2026 09:58:34 +0200 Subject: [PATCH] =?UTF-8?q?docs(adr-013):=20Erratum=20E3=20=E2=80=94=20lif?= =?UTF-8?q?t=20the=20pipeline=5Fcore=5Fversion=20caveat,=20in=20part?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #228 asked for this: §2.2 declared the field unreliable until pipeline-core cut a real release, and 3.0.0 shipped to PyPI on 2026-08-03. Condition met. But the lift is narrower than the request's suggested wording, and the difference is a released-versus-merged distinction worth getting right. authoritative when the producer ran a RELEASED distribution — a wheel's recorded version is written by the release that built it, so it cannot disagree with the code beside it. In force now. "unknown" when the producer ran an EDITABLE install — NOT yet in any released version. pipeline-core#403 makes that case report "unknown" instead of a stale number, and it merged 2026-08-04 13:58, a day and a half AFTER 3.0.0 was uploaded (2026-08-03 02:06). #228's suggested note states this half as current; it is not, and becomes true at pipeline-core's next release. Verified here rather than taken on trust: in this repo's environment importlib.metadata reports pipeline-core 2.3.0 while the source beside it is 3.0.0 — a full major version stale, exactly the value that would have been stamped into published provenance. With the fix present, _pipeline_core_version() returns "unknown". The operational point, which #228 got right: consumers must treat "unknown" as "do not infer the producing version", never as an error — and the set producing it will WIDEN at the next release, because every developer run joins it. Nothing in this repository changes. Hop-B re-embeds the Hop-A header untouched, so we forward this value and never compose it. contract_version stays 1.5. E3's claim that the fix is unreleased will expire, so it carries a check: test_e3s_claim_about_unreleased_behaviour_is_still_true fails if the installed pipeline-core is a released distribution past 3.0.0. Inert in an editable environment and live in CI, which installs from PyPI — stated in the docstring rather than left to be discovered. Mutation-proven against a synthetic 3.1.0 wheel. Suite 399 passed / 1 skipped / 40 xfailed; ruff clean. Co-Authored-By: Claude Opus 5 (1M context) --- .../013_sampled_forecast_wire_contract.md | 44 +++++++++++++++--- tests/test_falsify_adr013_s2.py | 45 +++++++++++++++++++ 2 files changed, 84 insertions(+), 5 deletions(-) diff --git a/docs/ADRs/013_sampled_forecast_wire_contract.md b/docs/ADRs/013_sampled_forecast_wire_contract.md index 6510bc8..35099b5 100644 --- a/docs/ADRs/013_sampled_forecast_wire_contract.md +++ b/docs/ADRs/013_sampled_forecast_wire_contract.md @@ -352,11 +352,10 @@ identifier arrays mean (`time` is the VIEWS month-id; `unit` is the `priogrid_id this platform has already paid once for leaving id vocabulary implicit (the gid/id epic: a past platform-wide cleanup needed just to disambiguate what its integer identifier columns meant). `provenance` is exactly the three keys shown (strings/bool). **Caveat:** -`pipeline_core_version` is self-reported and will be unreliable until pipeline-core's -release train (their #261) cuts real releases (status at adoption, 2026-07-15: none -yet) — consumers must not treat it as authoritative before then. The lift of this -caveat is tracked as a reminder in pipeline-core: their issue #279 (filed -2026-07-19) fires when the first real release ships. +`pipeline_core_version` is self-reported. It was declared unreliable at adoption +(2026-07-15) because pipeline-core's release train had cut no real releases yet, and +consumers were told not to treat it as authoritative. **That caveat is lifted in part — +see Erratum E3 below, which also explains why "in part" is the accurate word.** **§2.2a Amendment A2 — run maturity, drafted 2026-08-05, NOT YET IN FORCE.** @@ -933,6 +932,41 @@ runs can therefore never touch the live bucket by accident. Dated events after adoption. Errata correct errors in this document; other entries record execution progress against it. +- **2026-08-10 — Erratum E3 (§2.2, `pipeline_core_version`; `contract_version` stays + 1.5):** the adoption-time caveat said this field would be unreliable until pipeline-core + cut a real release. **views-pipeline-core 3.0.0 shipped to PyPI on 2026-08-03**, so the + condition is met — but the honest lift is narrower than "the field is now reliable", and + splits by how the *producing* pipeline-core was installed. + + **Authoritative when the producer ran a released distribution.** A wheel's recorded + version is written by the release that built it, so it cannot disagree with the code + beside it. In force now, for 3.0.0 onward. + + **`"unknown"` when the producer ran an editable install** — and this half is **not yet in + any released version**, which is the part the originating request (#228) stated too + strongly. An editable install's recorded version is fixed at the moment `pip install -e` + last ran and never tracks the source afterwards; pipeline-core#403 makes that case report + `"unknown"` instead of a stale number. That fix merged **2026-08-04**, a day and a half + *after* 3.0.0 was uploaded (2026-08-03 02:06 UTC), so **no released version contains it.** + It becomes true of producers at pipeline-core's next release. + + Verified here rather than taken on trust, 2026-08-10: in this repository's development + environment `importlib.metadata` reports pipeline-core **2.3.0** while the source beside + it is **3.0.0** — a full major version stale, exactly the value that would have been + stamped into published provenance. With the fix present, `_pipeline_core_version()` + returns `"unknown"` instead. + + **What consumers must do, and it is the operational point.** Treat `"unknown"` as *"do + not infer the producing version"*, never as an error. The set of runs producing + `"unknown"` will **widen** at pipeline-core's next release, because every developer run + joins it. A consumer that starts rejecting `"unknown"` on the strength of this lift would + break exactly those runs. + + This repository does not produce the value — Hop-B re-embeds the Hop-A header untouched + (`contract/wire/sink.py`) — so nothing here changes. The field is declared by this + contract, which is why the lift is recorded here. Arises from #228; pipeline-core #279 + (closed), #403, and their register C-280. + - **2026-08-05 — Amendment A2 drafted, not in force (§2.2a; `contract_version` stays 1.5):** views-postprocessing #133 asked for three declared fields on the run manifest — `maturity`, `source`, and a required schema version. Measured against what is actually diff --git a/tests/test_falsify_adr013_s2.py b/tests/test_falsify_adr013_s2.py index 7a751d2..7ce8cc4 100644 --- a/tests/test_falsify_adr013_s2.py +++ b/tests/test_falsify_adr013_s2.py @@ -79,3 +79,48 @@ def test_s2_2a_is_not_secretly_in_force(): "The field shipped and the amendment was never marked adopted — which leaves the " "§10 golden fixture, three repos' vendored copies, and this document disagreeing." ) + + +def test_e3s_claim_about_unreleased_behaviour_is_still_true(): + """Erratum E3 says a pipeline-core fix is in no released version. That expires. + + E3 lifts §2.2's `pipeline_core_version` caveat in two halves. The second — that an + editable install reports ``"unknown"`` rather than a stale number — landed in + pipeline-core on 2026-08-04, a day and a half *after* 3.0.0 was uploaded to PyPI. So + the erratum states plainly that **no released version contains it**, and that it + becomes true of producers at the next release. + + That is a dated claim about someone else's release history, in the document that + punishes those hardest. It stops being true the moment pipeline-core publishes again, + and nothing about this repository would change to signal it. + + So: if the pipeline-core we are running is a **released distribution** (not an + editable checkout) and its version is past 3.0.0, the next release has happened and + E3's wording is stale. CI installs from PyPI, so this is live there even though a + maintainer's editable environment leaves it inert — which is stated rather than + discovered, because a guard that only ever runs in one place is half a guard. + """ + pytest.importorskip("views_pipeline_core", reason="a declared dependency") + from importlib.metadata import PackageNotFoundError, version as dist_version + + import views_pipeline_core + + source = Path(views_pipeline_core.__file__).resolve() + if "site-packages" not in str(source): + pytest.skip( + "pipeline-core is an editable checkout here, so its recorded version says " + "nothing about what has been released. This check is live in CI, which " + "installs from PyPI." + ) + try: + installed = dist_version("views-pipeline-core") + except PackageNotFoundError: # pragma: no cover - not a distribution at all + pytest.skip("pipeline-core is not installed as a distribution") + + parts = tuple(int(p) for p in installed.split(".")[:3] if p.isdigit()) + assert parts <= (3, 0, 0), ( + f"pipeline-core {installed} is released and past 3.0.0, so Erratum E3's claim " + "that the editable-install fix is 'not yet in any released version' is out of " + "date. Re-read E3 against that release: the second half of the lift is probably " + "now in force, and the sentence saying it is not must go." + )