mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/grib2/decode.py

@@ -0,0 +1,1009 @@
+"""``weather.grib2``: named places, their values, and the arithmetic written down.
+
+This module is the join.  Everything it needs already exists and is certified on its own:
+``admission`` refuses an unknown grid or packing from the headers, before a value is read;
+``geometry`` computes coordinates in closed form and grades them against the publisher's own
+declaration on every message; the vendored binding unpacks the packed integers and cross-checks
+the template numbers it was told to expect.  What is added here is the composition, the recipe's
+own settings, and the one piece of arithmetic nobody else owns: turning a packed integer into a
+physical value.
+
+Mostly wiring, deliberately
+---------------------------
+If this module grows admission logic, projection maths, or bit unpacking, that logic has been
+duplicated out of the module that already owns it and the two copies will disagree.  What lives
+here is what lives nowhere else: the option schema, the variable and time the product section
+declares, the scaling rule, and the emitted table.
+
+Admission is structural rather than remembered
+----------------------------------------------
+``decode_admitted`` takes a ``MessageAdmission`` and there is no function here that takes message
+bytes without one -- the single exception is ``WeatherGrib2Reader.decode``, which is the Reader
+contract's own entry point, is handed bytes by the contract, and admits them before it does
+anything else.  ``tests/h3/test_readers_grib2.py`` parses this file and asserts both halves, so a
+second door has to be added to a named tuple in a reviewed edit rather than appearing quietly.
+The binding's own template cross-check is the second layer, for a call site that forgot.
+
+The recipe pins the allowlist it was written against
+----------------------------------------------------
+``admission_allowlist_version`` is a required setting.  The refusals in ``admission`` handle a
+message this product has never checked; this handles the other direction, where the Toolbox has
+learned a new template since the recipe was frozen and the same recipe would now decode a file it
+would previously have refused.  Both directions are the same property: a recipe's meaning must not
+drift while the recipe does not change.
+
+Row order is the recipe's
+-------------------------
+Rows come out in the order the recipe lists its points, not the order the grid stores them.  Grid
+order is an implementation detail of the file -- a model that reorganises its grid changes it
+without announcing anything -- and the recipe's order is what the author asked for and is stable
+across that.
+
+A missing value is a missing value
+----------------------------------
+A weather message may carry a bitmap marking points that have no value.  Such a point keeps its
+row and gets an empty cell.  Never a sentinel, which would be indistinguishable from a real
+reading, and never a non-finite value, which the sandbox IPC refuses outright -- the boundary
+telling us the right answer.  A decode that met one reports ``contains_masked_points``, so the
+empty cell is a fact the receipt carries rather than a gap a reader has to interpret.
+
+A coordinate is decimal text, and that is not a style choice
+------------------------------------------------------------
+Decode options are sealed through canonical JSON, which admits **no non-integer number at all**
+(``canonical.py``, ``JSON_NONINTEGER_NUMBER``): a sealed document whose numbers depend on a JSON
+writer's float formatting is a document that does not have one canonical form.  So a recipe
+states a latitude and a longitude as decimal text -- ``"39.7392"`` -- and this module converts it
+with the one correctly-rounded decimal-to-binary64 conversion the language has.  What is sealed
+is then the digits the author wrote, and it is the same digits on every host.  Exponent notation
+is refused: two spellings of one coordinate would seal to two digests for one recipe.
+
+Import discipline: ``formats``, ``readers.contracts``, ``readers.tabular``, ``readers.grib2``,
+the vendored binding, and the standard library.  Nothing from ``acquisition``, ``sources``,
+``recipe``, or ``pipeline``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from fractions import Fraction
+from typing import Any, NoReturn
+
+import mostlyright_grib
+
+from mostlyright.data_harness.canonical import sha256_bytes
+from mostlyright.data_harness.formats import (
+    FORMAT_MEDIA_TYPES,
+    FORMAT_SUFFIXES,
+    READER_CONTRACT_VERSION,
+    READER_OUTPUT_FORMATS,
+)
+from mostlyright.data_harness.readers.contracts import (
+    DECODE_FLAGS,
+    ReaderBudgets,
+    ReaderError,
+    ReaderPin,
+    ReaderResult,
+)
+from mostlyright.data_harness.readers.grib2.admission import (
+    ADMISSION_ALLOWLIST_VERSION,
+    ALLOWLIST_VERSION_CONSTANT,
+    MessageAdmission,
+    admit,
+)
+from mostlyright.data_harness.readers.grib2.geometry import (
+    build_grid,
+    nearest_grid_index,
+)
+from mostlyright.data_harness.readers.tabular import (
+    check_declared_size,
+    encode_canonical_csv,
+    sealed_filename,
+)
+
+_MISSING_BINDING_MEMBERS = tuple(
+    name for name in ("GribBindingError", "unpack") if not hasattr(mostlyright_grib, name)
+)
+if _MISSING_BINDING_MEMBERS:
+    raise ImportError(
+        "mostlyright-grib is incompatible: missing " + ", ".join(_MISSING_BINDING_MEMBERS)
+    )
+if not callable(mostlyright_grib.unpack) or not isinstance(mostlyright_grib.GribBindingError, type):
+    raise ImportError("mostlyright-grib is incompatible: binding API members have invalid types")
+
+__all__ = [
+    "ADMITTED_PRODUCT_TEMPLATES",
+    "ADMITTED_TIME_SIGNIFICANCE",
+    "ADMITTED_TIME_UNIT_SECONDS",
+    "COLUMN_NAMES",
+    "FLOAT_RULE",
+    "MASKED_POINT_FLAG",
+    "MAX_BINARY_SCALE_MAGNITUDE",
+    "MAX_DECIMAL_SCALE_MAGNITUDE",
+    "V2_COLUMN_NAMES",
+    "NamedPoint",
+    "Variable",
+    "WeatherGrib2Reader",
+    "WeatherGrib2ReaderV2",
+    "decode_admitted",
+    "decode_admitted_v2",
+    "physical_value",
+    "settings_from_options",
+]
+
+# The one encoding a Reader may seal, unpacked rather than restated.
+(_OUTPUT_FORMAT,) = READER_OUTPUT_FORMATS
+_OUTPUT_MEDIA_TYPE = sorted(FORMAT_MEDIA_TYPES[_OUTPUT_FORMAT])[0]
+_OUTPUT_SUFFIX = sorted(FORMAT_SUFFIXES[_OUTPUT_FORMAT])[0]
+
+# The fact a decode reports when the message marked one of the requested points absent.  Declared
+# in the closed vocabulary in ``readers/contracts.py`` and nowhere else; this line fails at import
+# if the two ever disagree, which is the loud failure rather than a flag the result would refuse.
+MASKED_POINT_FLAG = "contains_masked_points"
+if MASKED_POINT_FLAG not in DECODE_FLAGS:  # pragma: no cover - a contradiction caught at import
+    raise RuntimeError(f"{MASKED_POINT_FLAG} is not in the closed decode-flag vocabulary")
+
+# The emitted table, in this order, for every weather dataset this product builds.
+#
+# ``grid_latitude`` and ``grid_longitude`` are the coordinates of the cell that answered, and they
+# are carried because the attribution of a value to a place is either right or confidently wrong.
+# A reader of the dataset can see how far the answering point is from the place that was asked
+# for, without re-running anything; a table carrying only the request cannot be checked at all.
+COLUMN_NAMES: tuple[str, ...] = (
+    "point_id",
+    "requested_latitude",
+    "requested_longitude",
+    "grid_row",
+    "grid_column",
+    "grid_latitude",
+    "grid_longitude",
+    "valid_time",
+    "variable",
+    "value",
+)
+
+# Version 2 is the evidence-bearing row contract used when a range-selected message must remain
+# attributable after it becomes a table.  It is deliberately a second family version rather than
+# an edit to ``COLUMN_NAMES``: recipes that pin 1.0.0 keep producing byte-identical tables.
+V2_COLUMN_NAMES: tuple[str, ...] = (
+    "point_id",
+    "variable",
+    "level",
+    "run_time",
+    "valid_time",
+    "value",
+    "matched_grid_lat",
+    "matched_grid_lon",
+    "message_sha256",
+)
+
+# The product templates this family reads.  4.0 is an instantaneous value at a single level, which
+# is what every message on the admission allowlist declares.  A statistically processed product --
+# an accumulation or an average over a period -- is 4.8 and is refused, because its value is not
+# valid *at* a time but *over* one, and a table with a single valid-time column would state
+# something the message does not.  Admitting one is a reviewed edit here plus a column that says
+# what period the value covers.
+ADMITTED_PRODUCT_TEMPLATES: frozenset[int] = frozenset({0})
+
+# What octet 12 of the identification section may say the reference time means.  Analysis and
+# start-of-forecast are the two under which "valid time is the reference time plus the forecast
+# offset" is true.  Under verifying time or observation time the reference time already *is* the
+# valid time and adding the offset would move every stamp, so those are refused rather than
+# guessed at.
+ADMITTED_TIME_SIGNIFICANCE: frozenset[int] = frozenset({0, 1})
+
+# Code table 4.4, restricted to the units that are a fixed number of seconds.  A month, a year, a
+# decade, a normal, and a century are not durations -- they depend on which month and which year --
+# so a forecast measured in them has no valid time this Reader can compute, and it is refused
+# rather than approximated at 30 days.
+ADMITTED_TIME_UNIT_SECONDS: Mapping[int, int] = {
+    0: 60,
+    1: 3600,
+    2: 86400,
+    10: 3 * 3600,
+    11: 6 * 3600,
+    12: 12 * 3600,
+    13: 1,
+}
+
+# How large a scale exponent this Reader will do arithmetic with.  The bound is a resource bound
+# and it is stated as one: the rule below is exact integer arithmetic, so an unbounded exponent
+# means an unbounded integer, and an exponent of thirty thousand -- which the format's two-octet
+# sign-magnitude field can express -- would be a denial of service written in a header.  Both
+# bounds sit far outside anything published: the vendored messages carry decimal exponents of 0
+# and 1, and the largest reported in the wild is 27.  A message beyond them is refused by name.
+MAX_BINARY_SCALE_MAGNITUDE = 1100
+MAX_DECIMAL_SCALE_MAGNITUDE = 350
+
+# The magnitude of the surface scale factor this Reader reads, bounded for the same reason.
+_MAX_SURFACE_SCALE_MAGNITUDE = 20
+
+# The octet a missing one-byte field carries, and the value a missing four-byte one carries.
+_MISSING_OCTET = 0xFF
+_MISSING_SURFACE = 255
+
+# The shortest identification and product sections this Reader reads a field out of.
+_IDENTIFICATION_OCTETS = 21
+_PRODUCT_OCTETS = 34
+
+
+FLOAT_RULE = """Weather values follow these numeric and output invariants.
+
+The decoded value is the binary64 nearest to the exact rational
+
+    (R + X * 2^E) / 10^D
+
+where X is the packed integer, R is the binary32 reference value widened exactly to binary64, and
+E and D are the scale exponents. Integer arithmetic constructs the rational and rounds once at the
+end. Direct binary64 division or multiplication is rejected because it rounds intermediate values.
+No floating-point multiply-add exists on this path, so fused multiply-add contraction is impossible.
+
+Decoding is single-threaded. Scaling runs only for requested output points. Text output uses the
+shortest round-trip decimal representation. A missing point produces an empty cell; sentinels and
+non-finite values are not emitted.
+"""
+
+
+@dataclass(frozen=True)
+class NamedPoint:
+    """One place a recipe asked for: what to call it, and where it is."""
+
+    identity: str
+    latitude: float
+    longitude: float
+
+
+@dataclass(frozen=True)
+class Variable:
+    """The field a recipe wants, stated so the message can be held to it.
+
+    The name is the label that reaches the table.  The five numbers are the message's own
+    coordinates for a field -- discipline, parameter category, parameter number, and the surface
+    the value sits on -- and they are stated by the recipe rather than looked up from a name
+    table on purpose.  Variable names drift across decoder table versions even when the numbers
+    do not, so a name table would make a dataset's meaning depend on which tables were installed.
+    """
+
+    name: str
+    discipline: int
+    parameter_category: int
+    parameter_number: int
+    surface_type: int
+    surface_value: Fraction
+
+
+@dataclass(frozen=True)
+class DecodeSettings:
+    """Everything the recipe decides, in one typed record."""
+
+    variable: Variable
+    points: tuple[NamedPoint, ...]
+    allowlist_version: int
+
+
+@dataclass(frozen=True)
+class _Product:
+    """What the identification and product sections declare about the field and its time."""
+
+    template: int
+    discipline: int
+    parameter_category: int
+    parameter_number: int
+    surface_type: int
+    surface_value: Fraction
+    run_time: datetime.datetime
+    valid_time: datetime.datetime
+
+
+# --- The options, which are the whole of what a recipe decides ------------------------------
+
+_OPTION_KEYS = ("variable", "points", "admission_allowlist_version")
+_VARIABLE_KEYS = (
+    "name",
+    "discipline",
+    "parameter_category",
+    "parameter_number",
+    "surface_type",
+    "surface_value",
+)
+_POINT_KEYS = ("id", "latitude", "longitude")
+
+# A coordinate as a recipe states it: plain decimal text, bounded, no exponent and no leading
+# plus.  Twelve fractional digits is four orders of magnitude finer than the millionths of a
+# degree a message's own fields are quantised to, so nothing a publisher can express is lost.
+_COORDINATE = re.compile(r"^-?(0|[1-9][0-9]{0,3})(\.[0-9]{1,12})?$")
+
+
+def validate_options(options: Any, *, subject: str = "reader.weather.grib2.decode_options") -> dict:
+    """Admit this family's closed option set, refusing an unknown key by name.
+
+    Strict on purpose.  The options digest is sealed into the recipe forever, so a key that was
+    accepted and ignored would be an unreviewable difference between two recipes that read
+    identically to everyone who looks at them.
+    """
+
+    if not isinstance(options, Mapping):
+        _refuse("READER_OPTIONS", subject, "must be an object")
+    _closed(options, _OPTION_KEYS, subject, "this family takes")
+    variable = _variable_options(options.get("variable"), f"{subject}.variable")
+    points = _point_options(options.get("points"), f"{subject}.points")
+    version = options.get("admission_allowlist_version")
+    if type(version) is not int or version < 1:
+        _refuse(
+            "READER_OPTIONS",
+            f"{subject}.admission_allowlist_version",
+            f"states {version!r}, and it must be the positive integer version of the admission "
+            f"allowlist this recipe was written against. It is required because a recipe that did "
+            f"not state one would change meaning the day the Toolbox learned a template. This "
+            f"build admits version {ADMISSION_ALLOWLIST_VERSION}",
+        )
+    return {"variable": variable, "points": points, "admission_allowlist_version": version}
+
+
+def settings_from_options(
+    options: Any,
+    *,
+    subject: str = "reader.weather.grib2.decode_options",
+) -> DecodeSettings:
+    """The typed record the decode runs on, built from settings that have been admitted."""
+
+    admitted = validate_options(options, subject=subject)
+    variable = admitted["variable"]
+    return DecodeSettings(
+        variable=Variable(
+            name=str(variable["name"]),
+            discipline=int(variable["discipline"]),
+            parameter_category=int(variable["parameter_category"]),
+            parameter_number=int(variable["parameter_number"]),
+            surface_type=int(variable["surface_type"]),
+            surface_value=Fraction(int(variable["surface_value"])),
+        ),
+        points=tuple(
+            NamedPoint(str(point["id"]), float(point["latitude"]), float(point["longitude"]))
+            for point in admitted["points"]
+        ),
+        allowlist_version=int(admitted["admission_allowlist_version"]),
+    )
+
+
+def _closed(stated: Mapping[str, Any], keys: Sequence[str], subject: str, lead: str) -> None:
+    unknown = sorted(str(key) for key in stated if key not in keys)
+    if unknown:
+        _refuse(
+            "READER_OPTIONS",
+            subject,
+            f"names no such setting: {', '.join(unknown)}; {lead} {', '.join(sorted(keys))}",
+        )
+    missing = sorted(key for key in keys if key not in stated)
+    if missing:
+        _refuse("READER_OPTIONS", subject, f"does not state: {', '.join(missing)}")
+
+
+def _variable_options(stated: Any, subject: str) -> dict:
+    if not isinstance(stated, Mapping):
+        _refuse("READER_OPTIONS", subject, "must be an object naming the field this recipe wants")
+    _closed(stated, _VARIABLE_KEYS, subject, "a variable is stated as")
+    name = stated["name"]
+    if not isinstance(name, str) or not name.strip() or len(name) > 128:
+        _refuse("READER_OPTIONS", f"{subject}.name", "must be the label this field carries")
+    for key in ("discipline", "parameter_category", "parameter_number", "surface_type"):
+        value = stated[key]
+        if type(value) is not int or not 0 <= value <= 255:
+            _refuse(
+                "READER_OPTIONS",
+                f"{subject}.{key}",
+                "must be the octet the message states for it, between 0 and 255",
+            )
+    surface = stated["surface_value"]
+    if type(surface) is not int:
+        _refuse(
+            "READER_OPTIONS",
+            f"{subject}.surface_value",
+            "must be the whole number the level is stated at -- 2 for two metres above ground, "
+            "85000 for the 850 hPa level in pascals -- because a sealed decode option is "
+            "canonical JSON and canonical JSON carries no fractional number",
+        )
+    return dict(stated)
+
+
+def _point_options(stated: Any, subject: str) -> tuple[dict, ...]:
+    if isinstance(stated, (str, bytes)) or not isinstance(stated, Sequence) or not stated:
+        _refuse(
+            "READER_OPTIONS",
+            subject,
+            "must be a nonempty list of the places this dataset is built at; a weather file is "
+            "a grid and a dataset is the places you named, so naming none asks for nothing",
+        )
+    admitted: list[dict] = []
+    seen: set[str] = set()
+    for index, point in enumerate(stated):
+        where = f"{subject}[{index}]"
+        if not isinstance(point, Mapping):
+            _refuse("READER_OPTIONS", where, "must be an object")
+        _closed(point, _POINT_KEYS, where, "a place is stated as")
+        identity = point["id"]
+        if not isinstance(identity, str) or not identity.strip() or len(identity) > 128:
+            _refuse("READER_OPTIONS", f"{where}.id", "must be the name this place carries")
+        if identity in seen:
+            _refuse(
+                "READER_OPTIONS",
+                f"{where}.id",
+                f"repeats {identity}; two rows under one name is a table nobody can join on",
+            )
+        seen.add(identity)
+        for key in ("latitude", "longitude"):
+            value = point[key]
+            if not isinstance(value, str) or _COORDINATE.fullmatch(value) is None:
+                _refuse(
+                    "READER_OPTIONS",
+                    f"{where}.{key}",
+                    'must be plain decimal text such as "39.7392", with no exponent and no '
+                    "leading plus. It is text rather than a number because a sealed decode "
+                    "option is canonical JSON, which carries no fractional number at all -- so "
+                    "what is sealed is the digits written here, identically on every host",
+                )
+        admitted.append(dict(point))
+    return tuple(admitted)
+
+
+# --- The arithmetic ---------------------------------------------------------------------------
+
+
+def physical_value(
+    level: float,
+    *,
+    reference_value: float,
+    binary_scale: int,
+    decimal_scale: int,
+) -> float:
+    """Recover one physical value from one packed integer, under the rule in ``FLOAT_RULE``.
+
+    The whole rule is in that constant and this function is its one implementation.  The exact
+    rational is built with integer arithmetic and rounded to binary64 exactly once, by the
+    division on the last line -- ``Fraction.__float__`` divides two integers, which CPython
+    rounds correctly.  Nothing else on this path rounds.
+    """
+
+    if not isinstance(level, float) or not math.isfinite(level):
+        _refuse(
+            "READER_OUTPUT",
+            "reader.weather.grib2.level",
+            "a point with no value is an empty cell rather than a number, so it never reaches "
+            "the scaling rule",
+        )
+    if abs(binary_scale) > MAX_BINARY_SCALE_MAGNITUDE:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.binary_scale",
+            f"declares a binary scale exponent of {binary_scale}, beyond the "
+            f"{MAX_BINARY_SCALE_MAGNITUDE} this Reader computes with; the rule is exact integer "
+            f"arithmetic, so an unbounded exponent is an unbounded integer",
+        )
+    if abs(decimal_scale) > MAX_DECIMAL_SCALE_MAGNITUDE:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.decimal_scale",
+            f"declares a decimal scale exponent of {decimal_scale}, beyond the "
+            f"{MAX_DECIMAL_SCALE_MAGNITUDE} this Reader computes with; the rule is exact integer "
+            f"arithmetic, so an unbounded exponent is an unbounded integer",
+        )
+    exact = (Fraction(reference_value) + Fraction(level) * Fraction(2) ** binary_scale) / Fraction(
+        10
+    ) ** decimal_scale
+    value = float(exact)
+    if not math.isfinite(value):
+        _refuse(
+            "READER_OUTPUT",
+            "reader.weather.grib2.value",
+            f"scales to {exact.numerator}/{exact.denominator}, which is outside the range a "
+            f"binary64 value can carry; a value that cannot be represented is not rendered as "
+            f"one that can",
+        )
+    return value
+
+
+# --- What the message says about its field and its time ---------------------------------------
+
+
+def _product(admission: MessageAdmission, content: bytes) -> _Product:
+    """Read the field and the valid time out of the sections admission located."""
+
+    if admission.identification_length < _IDENTIFICATION_OCTETS:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.identification",
+            f"declares {admission.identification_length} bytes, too few to state the reference "
+            f"time a valid time is computed from",
+        )
+    if admission.product_length < _PRODUCT_OCTETS:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.product",
+            f"declares {admission.product_length} bytes, too few to state which field it holds",
+        )
+
+    template = int.from_bytes(
+        content[admission.product_start + 7 : admission.product_start + 9], "big"
+    )
+    if template not in ADMITTED_PRODUCT_TEMPLATES:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.product_template",
+            f"describes its field with product template 4.{template}, and this Reader reads "
+            f"4.{', 4.'.join(str(number) for number in sorted(ADMITTED_PRODUCT_TEMPLATES))}, an "
+            f"instantaneous value at one level. A product averaged or accumulated over a period "
+            f"is not valid at a time, so a table with one valid-time column would state something "
+            f"the message does not; admitting one means a reviewed edit plus a column saying what "
+            f"period each value covers",
+        )
+
+    surface_type = content[admission.product_start + 22]
+    if content[admission.product_start + 28] != _MISSING_SURFACE:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.product",
+            f"states a second fixed surface of type {content[admission.product_start + 28]}, so "
+            f"its values describe a layer between two surfaces rather than one surface; this "
+            f"Reader reads single-surface fields, and reading a layer as a surface would attach a "
+            f"value to a level it does not describe",
+        )
+
+    run_time = _reference_time(admission, content)
+    return _Product(
+        template=template,
+        discipline=admission.discipline,
+        parameter_category=content[admission.product_start + 9],
+        parameter_number=content[admission.product_start + 10],
+        surface_type=surface_type,
+        surface_value=_surface_value(admission, content),
+        run_time=run_time,
+        valid_time=_valid_time(admission, content, reference=run_time),
+    )
+
+
+def _surface_value(admission: MessageAdmission, content: bytes) -> Fraction:
+    """The level the values sit at, as the exact rational the message states."""
+
+    scale_octet = content[admission.product_start + 23]
+    scaled = _sign_magnitude(content[admission.product_start + 24 : admission.product_start + 28])
+    if scale_octet == _MISSING_OCTET:
+        return Fraction(0)
+    scale = _sign_magnitude(bytes([scale_octet]))
+    if abs(scale) > _MAX_SURFACE_SCALE_MAGNITUDE:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.surface",
+            f"scales its level by ten to the {scale}, which is not a level anything publishes",
+        )
+    return Fraction(scaled) / Fraction(10) ** scale
+
+
+def _reference_time(admission: MessageAdmission, content: bytes) -> datetime.datetime:
+    """Return the admitted UTC model-run coordinate declared by the message."""
+
+    start = admission.identification_start
+    significance = content[start + 11]
+    if significance not in ADMITTED_TIME_SIGNIFICANCE:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.reference_time",
+            f"says its reference time means significance {significance} rather than an analysis "
+            f"or the start of a forecast; under those two the valid time is the reference time "
+            f"plus the forecast offset, and under the others adding the offset would move every "
+            f"stamp in the table",
+        )
+    year = int.from_bytes(content[start + 12 : start + 14], "big")
+    try:
+        return datetime.datetime(
+            year,
+            content[start + 14],
+            content[start + 15],
+            content[start + 16],
+            content[start + 17],
+            min(content[start + 18], 59),
+            tzinfo=datetime.UTC,
+        )
+    except ValueError as error:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.reference_time",
+            f"states a reference time that is not a date: {error}",
+        )
+
+
+def _valid_time(
+    admission: MessageAdmission,
+    content: bytes,
+    *,
+    reference: datetime.datetime | None = None,
+) -> datetime.datetime:
+    """The reference time plus the forecast offset, in UTC, or a refusal naming what stopped it."""
+
+    if reference is None:
+        reference = _reference_time(admission, content)
+
+    unit = content[admission.product_start + 17]
+    if unit not in ADMITTED_TIME_UNIT_SECONDS:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.forecast_time",
+            f"measures its forecast offset in unit {unit} of code table 4.4, which is not a fixed "
+            f"number of seconds; a month and a year depend on which month and which year, so a "
+            f"valid time computed from one would be an approximation presented as a fact",
+        )
+    offset = _sign_magnitude(content[admission.product_start + 18 : admission.product_start + 22])
+    if offset < 0:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.forecast_time",
+            f"states a forecast offset of {offset}, which runs backwards from its own reference "
+            f"time",
+        )
+    seconds = offset * ADMITTED_TIME_UNIT_SECONDS[unit]
+    try:
+        return reference + datetime.timedelta(seconds=seconds)
+    except OverflowError:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.forecast_time",
+            f"states a forecast offset of {seconds} seconds, which is not a time",
+        )
+
+
+def _require_the_variable_the_recipe_asked_for(product: _Product, wanted: Variable) -> None:
+    """Hold the message to the field the recipe named, refusing a mismatch on any coordinate.
+
+    Pointing a recipe at the wrong file is the ordinary mistake here, and it is the one that
+    verifies clean: categorical rain and a temperature are both real numbers on the same grid at
+    the same time, and a table labelled with the recipe's variable name would carry the other
+    field's values under it without a mark.
+    """
+
+    stated = (
+        wanted.discipline,
+        wanted.parameter_category,
+        wanted.parameter_number,
+        wanted.surface_type,
+        wanted.surface_value,
+    )
+    declared = (
+        product.discipline,
+        product.parameter_category,
+        product.parameter_number,
+        product.surface_type,
+        product.surface_value,
+    )
+    if stated == declared:
+        return
+    _refuse(
+        "READER_ADMISSION",
+        "reader.weather.grib2.variable",
+        f"holds discipline {product.discipline}, parameter {product.parameter_category}."
+        f"{product.parameter_number} on surface type {product.surface_type} at "
+        f"{product.surface_value}, and the recipe asks for {wanted.name}: discipline "
+        f"{wanted.discipline}, parameter {wanted.parameter_category}.{wanted.parameter_number} on "
+        f"surface type {wanted.surface_type} at {wanted.surface_value}. A message carries one "
+        f"field, so this file is not the one this recipe describes; either the source points at "
+        f"the wrong record or the recipe names the wrong field",
+    )
+
+
+# --- The decode -------------------------------------------------------------------------------
+
+
+def _unpack(admission: MessageAdmission, content: bytes) -> Any:
+    """The one call into the vendored binding, which cannot be made without an admission result.
+
+    The template numbers handed over are the ones admission established, and the binding refuses
+    to decode a message declaring anything else -- the second layer, for a call site that skipped
+    the first.  The parameters it read out of Section 5 are then held against the ones admission
+    read out of the same octets, because two readings of one field that disagree mean one of them
+    is reading the wrong bytes and the values would be scaled by whichever won.
+
+    Translate ``GribBindingError`` to the typed Reader error used for corrupt or truncated packed
+    values. Raw runtime errors must not escape the Reader boundary.
+    """
+
+    try:
+        unpacked = mostlyright_grib.unpack(
+            content,
+            grid_template=admission.grid_template,
+            packing_template=admission.packing_template,
+        )
+    except mostlyright_grib.GribBindingError as error:
+        _refuse(
+            "READER_DECODE",
+            "reader.weather.grib2.message",
+            f"was admitted and then did not decode: {error.text} (decoder code {error.code}). "
+            f"The grid and packing this message declares are on the approved list, so the "
+            f"refusal is about the packed values themselves rather than about the format: the "
+            f"file is truncated or damaged. Fetch it again and compare the hash the receipt "
+            f"recorded; nothing was published and the version you already have is untouched",
+        )
+    declared = (admission.reference_value, admission.binary_scale, admission.decimal_scale)
+    read = (unpacked.reference_value, unpacked.binary_scale, unpacked.decimal_scale)
+    if declared != read:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.packing",
+            f"is read as {declared} by admission and as {read} by the decoder; two readings of "
+            f"one field that disagree mean one of them is reading the wrong bytes, and the values "
+            f"would be scaled by whichever answered",
+        )
+    if len(unpacked.levels) != admission.declared_points:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.packing",
+            f"unpacks {len(unpacked.levels)} values for a grid of {admission.declared_points} "
+            f"points",
+        )
+    return unpacked
+
+
+def decode_admitted(
+    admission: MessageAdmission,
+    content: bytes,
+    settings: DecodeSettings,
+    budgets: ReaderBudgets,
+) -> ReaderResult:
+    """Turn one admitted message into the rows the recipe asked for.
+
+    Takes an admission result, which is the only way this Reader decodes anything: a message
+    nobody admitted has nothing to pass here.  That is the same rule ``geometry.build_grid``
+    applies, for the same reason, and it is asserted structurally rather than described.
+    """
+
+    if not isinstance(admission, MessageAdmission):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.weather.grib2.admission",
+            "a message is decoded from an admission result, so an unadmitted message has nothing "
+            "to pass; this is the rule that makes decoding an unadmitted message inexpressible "
+            "rather than merely undone",
+        )
+    if not isinstance(settings, DecodeSettings):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.weather.grib2.settings",
+            "a decode runs on settings that have been admitted, not on a mapping",
+        )
+    if settings.allowlist_version != ADMISSION_ALLOWLIST_VERSION:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.admission_allowlist_version",
+            f"was written against allowlist version {settings.allowlist_version} and this build "
+            f"admits version {ADMISSION_ALLOWLIST_VERSION}. The list of grid and packing "
+            f"combinations this product opens has changed since the recipe was frozen, so the "
+            f"same recipe would now mean something different -- it would open files it used to "
+            f"refuse, or refuse files it used to open. Nothing is decoded until a person decides "
+            f"which meaning is wanted: re-approve the recipe against the current list, or build "
+            f"with the release that carried version {settings.allowlist_version}. The current "
+            f"version is {ALLOWLIST_VERSION_CONSTANT}",
+        )
+
+    check_declared_size(
+        row_count=len(settings.points),
+        column_count=len(COLUMN_NAMES),
+        budgets=budgets,
+        subject="reader.weather.grib2.table",
+    )
+
+    product = _product(admission, content)
+    _require_the_variable_the_recipe_asked_for(product, settings.variable)
+    grid = build_grid(admission, content)
+    unpacked = _unpack(admission, content)
+
+    stamp = product.valid_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+    rows: list[tuple[Any, ...]] = []
+    masked = False
+    for point in settings.points:
+        row, column = nearest_grid_index(grid, point.latitude, point.longitude, name=point.identity)
+        latitude, longitude = grid.coordinate_at(row, column)
+        level = unpacked.levels[grid.data_index(row, column)]
+        if math.isfinite(level):
+            value: float | None = physical_value(
+                level,
+                reference_value=admission.reference_value,
+                binary_scale=admission.binary_scale,
+                decimal_scale=admission.decimal_scale,
+            )
+        else:
+            value = None
+            masked = True
+        rows.append(
+            (
+                point.identity,
+                point.latitude,
+                point.longitude,
+                row,
+                column,
+                latitude,
+                longitude,
+                stamp,
+                settings.variable.name,
+                value,
+            )
+        )
+
+    return ReaderResult(
+        content=encode_canonical_csv(COLUMN_NAMES, rows, budgets=budgets),
+        data_format=_OUTPUT_FORMAT,
+        media_type=_OUTPUT_MEDIA_TYPE,
+        # The recipe's own name for the field, which is the one piece of text on this path a
+        # person wrote down deliberately.  A weather message carries no filename of its own.
+        filename=sealed_filename(settings.variable.name, suffix=_OUTPUT_SUFFIX),
+        row_count=len(rows),
+        column_names=COLUMN_NAMES,
+        declared_cell_count=max(admission.declared_points, len(rows) * len(COLUMN_NAMES)),
+        flags=(MASKED_POINT_FLAG,) if masked else (),
+    )
+
+
+def _level_coordinate(product: _Product) -> str:
+    """Spell the GRIB fixed-surface coordinate without a lossy unit-name lookup."""
+
+    value = product.surface_value
+    amount = str(value.numerator)
+    if value.denominator != 1:
+        amount = f"{amount}/{value.denominator}"
+    return f"{product.surface_type}:{amount}"
+
+
+def decode_admitted_v2(
+    admission: MessageAdmission,
+    content: bytes,
+    settings: DecodeSettings,
+    budgets: ReaderBudgets,
+) -> ReaderResult:
+    """Decode one admitted message into the evidence-bearing 2.0 row contract."""
+
+    if not isinstance(admission, MessageAdmission):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.weather.grib2.admission",
+            "a message is decoded from an admission result",
+        )
+    if not isinstance(settings, DecodeSettings):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.weather.grib2.settings",
+            "a decode runs on admitted settings",
+        )
+    if settings.allowlist_version != ADMISSION_ALLOWLIST_VERSION:
+        _refuse(
+            "READER_ADMISSION",
+            "reader.weather.grib2.admission_allowlist_version",
+            f"was written against allowlist version {settings.allowlist_version}, not "
+            f"{ADMISSION_ALLOWLIST_VERSION}",
+        )
+
+    check_declared_size(
+        row_count=len(settings.points),
+        column_count=len(V2_COLUMN_NAMES),
+        budgets=budgets,
+        subject="reader.weather.grib2.v2.table",
+    )
+    product = _product(admission, content)
+    _require_the_variable_the_recipe_asked_for(product, settings.variable)
+    grid = build_grid(admission, content)
+    unpacked = _unpack(admission, content)
+    message_digest = sha256_bytes(content)
+    run_time = product.run_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+    valid_time = product.valid_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+    level_coordinate = _level_coordinate(product)
+    rows: list[tuple[Any, ...]] = []
+    masked = False
+    for point in settings.points:
+        row, column = nearest_grid_index(grid, point.latitude, point.longitude, name=point.identity)
+        latitude, longitude = grid.coordinate_at(row, column)
+        level = unpacked.levels[grid.data_index(row, column)]
+        if math.isfinite(level):
+            value: float | None = physical_value(
+                level,
+                reference_value=admission.reference_value,
+                binary_scale=admission.binary_scale,
+                decimal_scale=admission.decimal_scale,
+            )
+        else:
+            value = None
+            masked = True
+        rows.append(
+            (
+                point.identity,
+                settings.variable.name,
+                level_coordinate,
+                run_time,
+                valid_time,
+                value,
+                latitude,
+                longitude,
+                message_digest,
+            )
+        )
+    return ReaderResult(
+        content=encode_canonical_csv(V2_COLUMN_NAMES, rows, budgets=budgets),
+        data_format=_OUTPUT_FORMAT,
+        media_type=_OUTPUT_MEDIA_TYPE,
+        filename=sealed_filename(settings.variable.name, suffix=_OUTPUT_SUFFIX),
+        row_count=len(rows),
+        column_names=V2_COLUMN_NAMES,
+        declared_cell_count=max(admission.declared_points, len(rows) * len(V2_COLUMN_NAMES)),
+        flags=(MASKED_POINT_FLAG,) if masked else (),
+    )
+
+
+@dataclass(frozen=True)
+class WeatherGrib2Reader:
+    """``weather.grib2``: a weather-model message read as the places a recipe named.
+
+    ``accepted_media_types`` admits what the mirrors actually serve.  That is an input-side
+    declaration and it is not a format table: what may be *sealed* is still canonical CSV alone.
+    """
+
+    family_id: str = "weather.grib2"
+    family_version: str = "1.0.0"
+    contract_version: str = READER_CONTRACT_VERSION
+    output_format: str = _OUTPUT_FORMAT
+    accepted_media_types: tuple[str, ...] = (
+        "application/octet-stream",
+        "application/wmo-grib2",
+    )
+    default_budgets: ReaderBudgets = field(default_factory=ReaderBudgets)
+
+    def validate_options(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
+        return validate_options(options)
+
+    def decode(self, content: bytes, pin: ReaderPin, budgets: ReaderBudgets) -> ReaderResult:
+        """The Reader contract's entry point: bytes in, sealed bytes out, admission first.
+
+        This is the one function here that receives message bytes without an admission result,
+        because the contract hands it bytes and this is the thing that admits them.  It admits
+        before it does anything else, and the test module asserts that from the syntax tree.
+        """
+
+        settings = settings_from_options(pin.decode_options)
+        admission = admit(content, budgets)
+        return decode_admitted(admission, content, settings, budgets)
+
+
+@dataclass(frozen=True)
+class WeatherGrib2ReaderV2:
+    """Evidence-bearing weather rows; co-installed beside byte-stable 1.0.0."""
+
+    family_id: str = "weather.grib2"
+    family_version: str = "2.0.0"
+    contract_version: str = READER_CONTRACT_VERSION
+    output_format: str = _OUTPUT_FORMAT
+    accepted_media_types: tuple[str, ...] = (
+        "application/octet-stream",
+        "application/wmo-grib2",
+    )
+    default_budgets: ReaderBudgets = field(default_factory=ReaderBudgets)
+
+    def validate_options(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
+        return validate_options(options)
+
+    def decode(self, content: bytes, pin: ReaderPin, budgets: ReaderBudgets) -> ReaderResult:
+        settings = settings_from_options(pin.decode_options)
+        admission = admit(content, budgets)
+        return decode_admitted_v2(admission, content, settings, budgets)
+
+
+def _sign_magnitude(raw: bytes) -> int:
+    """A GRIB2 signed integer: a sign bit and a magnitude, never two's complement.
+
+    The same rule admission and geometry each read their signed fields with, written out here
+    rather than imported across a module boundary for the reason recorded in ``geometry``, and
+    held to agree with both by test.
+    """
+
+    value = int.from_bytes(raw, "big")
+    sign = 1 << (8 * len(raw) - 1)
+    return -(value & ~sign) if value & sign else value
+
+
+def _refuse(code: str, subject: str, detail: str) -> NoReturn:
+    raise ReaderError(code, subject, detail)