mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/samples/weather.grib2/2.0.0/hrrr_2m_temperature/expected.json

@@ -0,0 +1,54 @@
+{
+  "column_names": [
+    "point_id",
+    "variable",
+    "level",
+    "run_time",
+    "valid_time",
+    "value",
+    "matched_grid_lat",
+    "matched_grid_lon",
+    "message_sha256"
+  ],
+  "decode_options": {
+    "admission_allowlist_version": 1,
+    "points": [
+      {
+        "id": "denver",
+        "latitude": "39.7392",
+        "longitude": "-104.9903"
+      },
+      {
+        "id": "chicago",
+        "latitude": "41.8781",
+        "longitude": "-87.6298"
+      },
+      {
+        "id": "houston",
+        "latitude": "29.7604",
+        "longitude": "-95.3698"
+      }
+    ],
+    "variable": {
+      "discipline": 0,
+      "name": "temperature_2m",
+      "parameter_category": 0,
+      "parameter_number": 0,
+      "surface_type": 103,
+      "surface_value": 2
+    }
+  },
+  "family_id": "weather.grib2",
+  "family_version": "2.0.0",
+  "flags": [],
+  "normalized_sha256": "5b3daf9a43608fbd424e119393ef19973d003ecba8f14fc9c39ece82b7feb801",
+  "provenance": {
+    "licence": "Public domain. A work of the United States Government under 17 U.S.C. 105, redistributed by NOAA through the NOAA Open Data Dissemination programme with no restriction on reuse or redistribution.",
+    "origin": "https://noaa-hrrr-bdp-pds.s3.amazonaws.com/hrrr.20260805/conus/hrrr.t12z.wrfsfcf00.grib2, bytes 34694688-35889177 (record 71 of the .grib2.idx sidecar)",
+    "retrieved": "2026-08-07",
+    "why": "The same certified HRRR message as 1.0.0 discriminates the versioned evidence-bearing output: level, run time, valid time, matched coordinates and message digest are all derived from these exact admitted bytes."
+  },
+  "row_count": 3,
+  "sample_file": "hrrr-2m-temperature.grib2",
+  "warm_up": true
+}

mostlyright/data_harness/readers/samples.py

@@ -0,0 +1,582 @@
+"""Known-good samples: one packaged constant, one loader, one comparison.
+
+A known-good sample is a real file with its correct answer recorded beside it.  Certification
+requires one per Reader family, and this module is what makes "or it does not land" a test
+rather than a habit: ``load_samples`` reads the packaged tree, and the coverage gate in
+``tests/test_reader_samples.py`` fails naming any family in the Toolbox that has no sample.
+
+The constant has exactly one home.  CI asserts the recorded answer and a refresh checks the
+same recorded answer before it fetches anything, and both reach it through this loader.  Two
+copies of one number drift, and a check comparing against a drifted number reports confidence
+it does not have.
+
+``warm_up`` is the pre-refresh half of the same machinery: it re-opens the one sample a family
+designates and halts the refresh when the answer has moved.  It takes its decode route from
+its caller -- in process for CI, through the clean room for a refresh -- and does the
+comparison itself, so a caller may change how the answer was obtained and can never weaken
+what counts as the right answer.
+
+What a sample records is four facts and no more -- the digest of the Reader's output bytes, the
+row count, the column names, and the decode flags.  ``DecodedFacts`` is that same four-field
+shape, so a decode route can only offer what an expectation actually states.  ``compare_facts``
+is the single place that knows how a recorded expectation is checked; it returns a verdict
+rather than raising, so each consumer chooses its own reaction to a moved answer.
+
+Not goldens
+-----------
+Samples are not golden fixtures and must never acquire their machinery.  A golden digest in
+this repository is minted on the x86_64 Linux authority and every golden assertion is gated on
+the running architecture; a sample assertion built that way would skip on the arm64 development
+host and on the macOS parity leg, so the gate would be vacuous on two legs out of three while
+reporting green on all of them.  An expectation carrying an ``environment`` key is therefore
+refused by name -- that key is how a golden records the host that produced it, and a sample's
+answer is a property of the Reader and the bytes, never of the host.  ``samples/README.md``
+states the convention in full.
+
+Import discipline
+-----------------
+This module may reach ``readers.contracts``, ``readers.registry``, ``canonical``, and the
+standard library.  It may not import ``acquisition`` -- that back-edge would close an import
+cycle -- which is why the clean-room decode route arrives as an injected callable rather than
+as a sandbox call made here.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import pathlib
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, NoReturn
+
+from mostlyright.data_harness.canonical import sha256_bytes
+from mostlyright.data_harness.readers.contracts import (
+    DECODE_FLAGS,
+    ReaderError,
+    ReaderPin,
+    ReaderResult,
+    identifier,
+    semver,
+)
+from mostlyright.data_harness.readers.registry import TOOLBOX, ReaderRegistry
+
+__all__ = [
+    "SAMPLES_ROOT",
+    "DecodedFacts",
+    "FactComparison",
+    "ReaderSample",
+    "SampleProvenance",
+    "compare_facts",
+    "decode_in_process",
+    "load_samples",
+    "samples_for",
+    "verify_sample",
+    "warm_up",
+    "warm_up_sample",
+]
+
+# The packaged tree.  It ships inside the wheel because the warm-up check runs in production,
+# and a sample that lived under ``tests/`` would not be installed with the code that needs it.
+SAMPLES_ROOT = pathlib.Path(__file__).resolve().parent / "samples"
+
+_EXPECTATION_FILENAME = "expected.json"
+
+# The closed expectation vocabulary.  ``warm_up`` is the one optional key; everything else is
+# required, and anything outside the set is refused by name rather than ignored, because an
+# ignored key is an expectation someone believes they recorded.
+_REQUIRED_KEYS = frozenset(
+    {
+        "family_id",
+        "family_version",
+        "decode_options",
+        "sample_file",
+        "normalized_sha256",
+        "row_count",
+        "column_names",
+        "flags",
+        "provenance",
+    }
+)
+_OPTIONAL_KEYS = frozenset({"warm_up"})
+_EXPECTATION_KEYS = _REQUIRED_KEYS | _OPTIONAL_KEYS
+
+# The four reviewable provenance facts.  Exactly these: a sample with fewer cannot be reviewed,
+# and one with more has grown a field no reviewer was told to read.
+_PROVENANCE_KEYS = ("origin", "retrieved", "licence", "why")
+
+# A recorded digest is lower-case hex, so two spellings of one digest cannot both be admitted.
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+
+# A sample filename is a bare name in the sample's own directory: no separator, no parent
+# reference, no leading dot.  Same shape the Reader contract admits for a sealed snapshot.
+_SAMPLE_FILENAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,254}$")
+
+
+def _refuse(subject: str, detail: str) -> NoReturn:
+    raise ReaderError("READER_CONTRACT", subject, detail)
+
+
+@dataclass(frozen=True)
+class SampleProvenance:
+    """Where a sample came from and what it proves, in four reviewable facts."""
+
+    origin: str
+    retrieved: str
+    licence: str
+    why: str
+
+
+@dataclass(frozen=True)
+class ReaderSample:
+    """One known-good sample: the bytes, the settings, and the answer they must produce."""
+
+    family_id: str
+    family_version: str
+    sample_name: str
+    sample_file: str
+    decode_options: Mapping[str, Any]
+    content: bytes
+    normalized_sha256: str
+    row_count: int
+    column_names: tuple[str, ...]
+    flags: tuple[str, ...]
+    provenance: SampleProvenance
+    warm_up: bool = False
+
+    @property
+    def coordinate(self) -> str:
+        """The ``id@version`` coordinate of the family this sample belongs to."""
+
+        return f"{self.family_id}@{self.family_version}"
+
+    @property
+    def label(self) -> str:
+        """The name a refusal message carries, so an operator can find the file."""
+
+        return f"{self.coordinate}/{self.sample_name}"
+
+    @property
+    def pin(self) -> ReaderPin:
+        """The pin a recipe would seal to decode this sample the way it was recorded."""
+
+        return ReaderPin(self.family_id, self.family_version, self.decode_options)
+
+
+@dataclass(frozen=True)
+class DecodedFacts:
+    """Exactly the four facts an expectation records about one decode.
+
+    Four fields on purpose.  This record is the seam a decode route is injected across, and a
+    richer one would let a caller supply something that compares unequal for a reason the
+    expectation never stated.
+    """
+
+    normalized_sha256: str
+    row_count: int
+    column_names: tuple[str, ...]
+    flags: tuple[str, ...]
+
+    @classmethod
+    def from_result(cls, result: ReaderResult) -> DecodedFacts:
+        """Reduce a decode result to the recorded facts, digesting the output bytes."""
+
+        return cls(
+            sha256_bytes(result.content),
+            result.row_count,
+            tuple(result.column_names),
+            tuple(result.flags),
+        )
+
+
+@dataclass(frozen=True)
+class FactComparison:
+    """The verdict of one comparison: what was expected, what was observed, what moved."""
+
+    sample: ReaderSample
+    observed: DecodedFacts
+    differences: tuple[str, ...]
+
+    @property
+    def matches(self) -> bool:
+        """True when every recorded fact was reproduced exactly."""
+
+        return not self.differences
+
+    def describe(self) -> str:
+        """One line an operator can act on, naming the sample and every fact that moved."""
+
+        if self.matches:
+            return f"{self.sample.label}: every recorded fact was reproduced"
+        return f"{self.sample.label}: " + "; ".join(self.differences)
+
+
+def compare_facts(sample: ReaderSample, facts: DecodedFacts) -> FactComparison:
+    """The one comparison, shared by CI and by the pre-refresh check.
+
+    Returns a verdict rather than raising.  The CI gate turns a mismatch into a failed
+    assertion and a refresh turns the same mismatch into a halt, and both reach that decision
+    from one implementation of "did the answer move".
+    """
+
+    if not isinstance(facts, DecodedFacts):
+        _refuse(
+            f"reader.sample.{sample.label}",
+            "a decode route must return the four recorded facts and nothing else",
+        )
+    differences = [
+        f"{name}: expected {expected!r}, observed {observed!r}"
+        for name, expected, observed in (
+            ("normalized_sha256", sample.normalized_sha256, facts.normalized_sha256),
+            ("row_count", sample.row_count, facts.row_count),
+            ("column_names", sample.column_names, facts.column_names),
+            ("flags", sample.flags, facts.flags),
+        )
+        if expected != observed
+    ]
+    return FactComparison(sample, facts, tuple(differences))
+
+
+def decode_in_process(
+    sample: ReaderSample,
+    *,
+    registry: ReaderRegistry = TOOLBOX,
+) -> DecodedFacts:
+    """Decode one sample here, in this process, through the family it pins.
+
+    The default route.  It resolves the family from the closed Toolbox on the sample's exact
+    coordinate and calls it directly, which is the only route available on a leg with no
+    sandbox -- so this is what CI exercises.  ``registry`` is a keyword with a default, which
+    keeps the positional signature exactly ``(ReaderSample) -> DecodedFacts``.
+    """
+
+    family = registry.resolve(sample.family_id, sample.family_version)
+    result = family.decode(sample.content, sample.pin, family.default_budgets)
+    if not isinstance(result, ReaderResult):
+        raise ReaderError(
+            "READER_OUTPUT",
+            f"reader.sample.{sample.label}",
+            "the family returned something that is not a Reader result",
+        )
+    result.validate_for(family.output_format, family.default_budgets)
+    return DecodedFacts.from_result(result)
+
+
+def verify_sample(
+    sample: ReaderSample,
+    *,
+    registry: ReaderRegistry = TOOLBOX,
+) -> FactComparison:
+    """Decode one sample and check it against its recorded answer.
+
+    A two-line composition on purpose: there is exactly one place that knows how a recorded
+    expectation is checked, and every consumer -- the CI gate and the pre-refresh check --
+    goes through it.
+    """
+
+    return compare_facts(sample, decode_in_process(sample, registry=registry))
+
+
+def warm_up(
+    family_id: str,
+    family_version: str,
+    *,
+    decode: Callable[[ReaderSample], DecodedFacts] = decode_in_process,
+    root: pathlib.Path | None = None,
+) -> None:
+    """Re-open one known file and halt if the answer has moved.  Returns silently otherwise.
+
+    A decoder that answers differently on a file whose answer is known has changed the meaning
+    of every dataset it has ever produced.  That is why this is a halt and not a warning: the
+    datasets already sealed cannot be un-sealed, so the only useful moment to stop is before
+    the next one is built.  Stated for the user as: before every refresh, the Reader re-opens
+    one known file; a wrong answer halts the refresh.
+
+    The decode route is supplied by the caller, and there are exactly two callers.
+
+    * **The CI coverage gate** takes the default, ``decode_in_process``.  It resolves the
+      family from the closed Toolbox and calls it here, which is the only route available on a
+      leg with no sandbox.  It answers "does this family decode this file correctly".
+    * **A refresh** injects a callable backed by the clean room's ``decode_and_parse``.  It
+      answers "does this family decode this file correctly on the path production takes, under
+      the attested policy". The production-path check matters because a warm-up
+      that decoded by a route production does not take would clear a family whose failure
+      lives in the clean room.
+
+    The route arrives as a parameter rather than being called from here because ``readers/``
+    may not import ``acquisition/``; that back-edge would close an import cycle.  What the
+    parameter may supply is a decode and never a verdict: the callable returns
+    ``DecodedFacts`` and this function does the comparison itself through ``compare_facts``,
+    against the expectation the packaged tree records.  So a caller can change how the answer
+    was obtained and can never weaken what counts as the right answer.
+
+    A route that raises is a halt, not a pass.  A clean room refusing during warm-up is
+    exactly the condition a refresh must stop on, and treating the refusal as an absent check
+    would turn the loudest possible failure into silence.
+    """
+
+    sample = warm_up_sample(family_id, family_version, root=root)
+    subject = f"reader.warmup.{sample.label}"
+    try:
+        facts = decode(sample)
+    except ReaderError as error:
+        raise ReaderError(
+            "READER_WARMUP",
+            subject,
+            f"the decode route refused the warm-up sample: {error}",
+        ) from error
+    # Deliberately broad: any way a decode route can fail is a halt, and a route that failed
+    # in an unforeseen way is exactly the one that must not read as an absent check.
+    except Exception as error:
+        raise ReaderError(
+            "READER_WARMUP",
+            subject,
+            f"the decode route failed on the warm-up sample: {error!r}",
+        ) from error
+
+    outcome = compare_facts(sample, facts)
+    if outcome.matches:
+        return
+    raise ReaderError(
+        "READER_WARMUP",
+        subject,
+        f"{sample.coordinate} no longer reproduces its known-good sample "
+        f"{sample.sample_name}: expected sha256 {sample.normalized_sha256}, observed sha256 "
+        f"{facts.normalized_sha256} ({outcome.describe()})",
+    )
+
+
+def warm_up_sample(
+    family_id: str,
+    family_version: str,
+    *,
+    root: pathlib.Path | None = None,
+) -> ReaderSample:
+    """The one sample a refresh re-opens for this family, or a refusal.
+
+    Designation lives in the tree rather than in the caller, so "one known file" cannot vary
+    by who is asking.  A family with no sample at all raises here too: an unwarmed family is
+    not a warmed one, and a check that quietly passed when it had nothing to check would be
+    worse than no check.
+    """
+
+    coordinate = f"{family_id}@{family_version}"
+    recorded = samples_for(family_id, family_version, root=root)
+    designated = tuple(sample for sample in recorded if sample.warm_up)
+    if not designated:
+        detail = (
+            "ships no known-good sample, so there is nothing to warm up on"
+            if not recorded
+            else "designates no warm-up sample; set warm_up to true on exactly one of: "
+            + ", ".join(sample.sample_name for sample in recorded)
+        )
+        raise ReaderError("READER_WARMUP", f"reader.warmup.{coordinate}", detail)
+    return designated[0]
+
+
+def load_samples(root: pathlib.Path | None = None) -> tuple[ReaderSample, ...]:
+    """Every sample in the tree, in coordinate order, or a refusal naming what is malformed.
+
+    ``root`` defaults to the packaged tree.  It is a parameter so a test can load a copied
+    tree; production reads the installed one and passes nothing.
+    """
+
+    base = SAMPLES_ROOT if root is None else pathlib.Path(root)
+    if not base.is_dir():
+        _refuse("reader.samples", f"{base} is not a sample tree")
+    loaded: list[ReaderSample] = []
+    for family_dir in _child_directories(base, base, "holds no Reader version directory"):
+        for version_dir in _child_directories(family_dir, base, "holds no sample directory"):
+            for sample_dir in _child_directories(version_dir, base, "holds no sample"):
+                loaded.append(_load_one(sample_dir, base))
+    _refuse_a_second_warm_up_sample(loaded)
+    return tuple(loaded)
+
+
+def _refuse_a_second_warm_up_sample(loaded: Sequence[ReaderSample]) -> None:
+    """Two designated samples for one family is a malformed tree, refused when it loads.
+
+    Refused here rather than where the check runs, so the ambiguity cannot survive until a
+    refresh and then be resolved by whichever sample happened to sort first.
+    """
+
+    designated: dict[str, list[str]] = {}
+    for sample in loaded:
+        if sample.warm_up:
+            designated.setdefault(sample.coordinate, []).append(sample.sample_name)
+    for coordinate, names in sorted(designated.items()):
+        if len(names) > 1:
+            _refuse(
+                f"reader.samples.{coordinate}",
+                "designates more than one warm-up sample: "
+                + ", ".join(sorted(names))
+                + "; one known file is a property of this tree, not of the caller",
+            )
+
+
+def samples_for(
+    family_id: str,
+    family_version: str,
+    *,
+    root: pathlib.Path | None = None,
+) -> tuple[ReaderSample, ...]:
+    """The samples recorded for one exact family coordinate, and never a nearby one."""
+
+    return tuple(
+        sample
+        for sample in load_samples(root=root)
+        if (sample.family_id, sample.family_version) == (family_id, family_version)
+    )
+
+
+def _child_directories(
+    directory: pathlib.Path,
+    base: pathlib.Path,
+    complaint: str,
+) -> tuple[pathlib.Path, ...]:
+    """The sorted sub-directories of one level, refusing a level that holds none.
+
+    An empty level is refused rather than skipped: a sample tree missing its version layer
+    would otherwise load zero samples and report nothing, which is the silence the coverage
+    gate exists to break.  Files at a level are ignored, so ``README.md`` can live beside the
+    families it documents.
+    """
+
+    children = tuple(sorted(child for child in directory.iterdir() if child.is_dir()))
+    if not children and directory != base:
+        _refuse(f"reader.sample.{directory.relative_to(base).as_posix()}", complaint)
+    return children
+
+
+def _load_one(directory: pathlib.Path, base: pathlib.Path) -> ReaderSample:
+    relative = directory.relative_to(base)
+    subject = f"reader.sample.{relative.as_posix()}"
+    document = _expectation_document(directory, subject)
+
+    family_id = identifier(document["family_id"], f"{subject}.family_id")
+    family_version = semver(document["family_version"], f"{subject}.family_version")
+    if (family_id, family_version) != (relative.parts[0], relative.parts[1]):
+        _refuse(
+            subject,
+            f"records {family_id}@{family_version}, which is not the identity its directory "
+            "states; the directory is the identity",
+        )
+
+    sample_file = document["sample_file"]
+    if (
+        not isinstance(sample_file, str)
+        or _SAMPLE_FILENAME.fullmatch(sample_file) is None
+        or sample_file == _EXPECTATION_FILENAME
+    ):
+        _refuse(subject, "sample_file must be a bare filename in this directory")
+    sample_path = directory / sample_file
+    if not sample_path.is_file():
+        _refuse(subject, f"names {sample_file}, which is not in the sample directory")
+
+    warm_up_flag = document.get("warm_up", False)
+    if not isinstance(warm_up_flag, bool):
+        _refuse(subject, "warm_up must be true or false")
+
+    return ReaderSample(
+        family_id=family_id,
+        family_version=family_version,
+        sample_name=relative.parts[2],
+        sample_file=sample_file,
+        decode_options=MappingProxyType(dict(_decode_options(document, subject))),
+        content=sample_path.read_bytes(),
+        normalized_sha256=_digest(document["normalized_sha256"], subject),
+        row_count=_row_count(document["row_count"], subject),
+        column_names=_column_names(document["column_names"], subject),
+        flags=_flags(document["flags"], subject),
+        provenance=_provenance(document["provenance"], subject),
+        warm_up=warm_up_flag,
+    )
+
+
+def _expectation_document(directory: pathlib.Path, subject: str) -> dict[str, Any]:
+    path = directory / _EXPECTATION_FILENAME
+    if not path.is_file():
+        _refuse(
+            subject,
+            f"has no {_EXPECTATION_FILENAME}; a sample without its recorded answer is not a "
+            "known-good sample",
+        )
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        _refuse(subject, f"has an unreadable {_EXPECTATION_FILENAME}: {error}")
+    if not isinstance(document, dict):
+        _refuse(subject, f"{_EXPECTATION_FILENAME} must be a JSON object")
+    if "environment" in document:
+        _refuse(
+            subject,
+            "carries an environment key: that is the golden machinery leaking in.  A sample "
+            "records what a Reader answers, never the host it answered on",
+        )
+    unknown = sorted(str(key) for key in document if key not in _EXPECTATION_KEYS)
+    if unknown:
+        _refuse(subject, f"states a key the convention does not: {', '.join(unknown)}")
+    missing = sorted(_REQUIRED_KEYS - set(document))
+    if missing:
+        _refuse(subject, f"does not state: {', '.join(missing)}")
+    return document
+
+
+def _decode_options(document: Mapping[str, Any], subject: str) -> Mapping[str, Any]:
+    """The settings, admitted by building the pin a recipe would have sealed."""
+
+    options = document["decode_options"]
+    if not isinstance(options, Mapping):
+        _refuse(f"{subject}.decode_options", "must be an object")
+    return ReaderPin(document["family_id"], document["family_version"], options).decode_options
+
+
+def _digest(value: Any, subject: str) -> str:
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        _refuse(f"{subject}.normalized_sha256", "must be a lower-case hex sha256")
+    return value
+
+
+def _row_count(value: Any, subject: str) -> int:
+    if type(value) is not int or value < 0:
+        _refuse(f"{subject}.row_count", "must be a non-negative integer")
+    return value
+
+
+def _column_names(value: Any, subject: str) -> tuple[str, ...]:
+    if isinstance(value, str) or not isinstance(value, Sequence) or not value:
+        _refuse(f"{subject}.column_names", "must be a nonempty list of column names")
+    if any(not isinstance(name, str) or not name or "\x00" in name for name in value):
+        _refuse(f"{subject}.column_names", "must be nonempty text without a NUL byte")
+    if len(set(value)) != len(value):
+        _refuse(f"{subject}.column_names", "must not repeat a column name")
+    return tuple(value)
+
+
+def _flags(value: Any, subject: str) -> tuple[str, ...]:
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        _refuse(f"{subject}.flags", "must be a list of decode flags")
+    unknown = sorted(str(flag) for flag in value if flag not in DECODE_FLAGS)
+    if unknown:
+        _refuse(f"{subject}.flags", f"names no such decode flag: {', '.join(unknown)}")
+    return tuple(sorted(set(value)))
+
+
+def _provenance(value: Any, subject: str) -> SampleProvenance:
+    """Admit the four reviewable facts, refusing a sample no one could review."""
+
+    where = f"{subject}.provenance"
+    if not isinstance(value, Mapping):
+        _refuse(where, "must be an object")
+    if sorted(str(key) for key in value) != sorted(_PROVENANCE_KEYS):
+        _refuse(where, f"must state exactly: {', '.join(sorted(_PROVENANCE_KEYS))}")
+    for key in _PROVENANCE_KEYS:
+        if not isinstance(value[key], str) or not value[key].strip():
+            _refuse(where, f"{key} must be a nonempty statement")
+    try:
+        datetime.date.fromisoformat(value["retrieved"])
+    except ValueError:
+        _refuse(where, "retrieved must be an ISO date, as YYYY-MM-DD")
+    return SampleProvenance(**{key: value[key] for key in _PROVENANCE_KEYS})