mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/registry.py

@@ -0,0 +1,514 @@
+"""The Toolbox: the closed table of Reader families the product ships with.
+
+Resolution is on an exact ``(family_id, family_version)`` key.  A near version is refused,
+never substituted, because a recipe pins the code that decoded its bytes and a substituted
+decoder would silently answer a different question. ``weather.grib2@1.0.0`` and
+``weather.grib2@2.0.0`` are co-installed so each Recipe resolves its exact pin.
+
+The table is closed and has no discovery path. Membership is exactly the frozen descriptors
+written into ``_CERTIFIED_FAMILIES`` below: there is no plugin scan, entry point, environment
+override, or recipe-controlled module. A descriptor imports its one literal module/factory only
+after exact coordinate resolution. Adding a family is a source edit that goes through
+Certification and review.
+
+The table is deliberately not derived from ``formats``.  The two answer different
+questions: ``formats`` answers "what encoding may be sealed", and this table answers "what
+code may run".  A format may be sealable with no family that produces it, and a family may
+be certified before any recipe pins it.  Deriving one from the other would make each answer
+the other's question.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass, field
+
+from mostlyright.data_harness.formats import DATA_FORMATS, READER_CONTRACT_VERSION
+from mostlyright.data_harness.readers.contracts import (
+    ReaderBudgets,
+    ReaderError,
+    ReaderFamily,
+    bulk_default_budgets,
+    identifier,
+    semver,
+)
+
+__all__ = ["TOOLBOX", "ReaderRegistry", "certified_descriptors"]
+
+
+_SPREADSHEET_DEFAULT_BUDGETS = ReaderBudgets(
+    max_uncompressed_bytes=32 * 1024 * 1024,
+    max_declared_cells=250_000,
+    max_rows=250_001,
+    max_columns=256,
+)
+_JSON_DEFAULT_BUDGETS = bulk_default_budgets()
+
+
+def spreadsheet_default_budgets() -> ReaderBudgets:
+    """Return the one certified budget value shared by lazy and loaded XLSX metadata."""
+
+    return _SPREADSHEET_DEFAULT_BUDGETS
+
+
+# What a family must answer before it may enter the table.  Checked at registration rather
+# than at first use, so a mis-shaped family fails when the process starts and not when a
+# refresh is halfway through.
+_REQUIRED_MEMBERS = (
+    "family_id",
+    "family_version",
+    "contract_version",
+    "output_format",
+    "accepted_media_types",
+    "default_budgets",
+    "validate_options",
+    "decode",
+)
+
+
+@dataclass(frozen=True)
+class _FamilyDescriptor:
+    """Static certified metadata plus one fixed lazy factory coordinate.
+
+    ``settings_summary`` is the one sentence a recipe author reads about this coordinate. It is
+    carried here rather than typed into the skill's settings table because that table, the closed
+    coordinate tables in the suite, and this tuple were three hand-kept copies of one fact, and
+    adding a family meant remembering all of them. ``scripts/generate_registry_tables.py`` emits
+    every one of those restatements from this tuple, and a test in the ordinary collection fails
+    when a checked-in copy and this tuple disagree. It is inert metadata: nothing in resolution,
+    decoding, or admission reads it.
+    """
+
+    family_id: str
+    family_version: str
+    module_name: str
+    factory_name: str
+    accepted_media_types: tuple[str, ...]
+    settings_summary: str
+    contract_version: str = READER_CONTRACT_VERSION
+    output_format: str = "csv"
+    default_budgets: ReaderBudgets = field(default_factory=ReaderBudgets)
+    optional_dependency: str | None = None
+
+    def __post_init__(self) -> None:
+        # A blank summary would emit a blank table cell rather than fail, so the emptiness is
+        # refused where the entry is written instead of surviving into a page somebody reads.
+        # The value has to *be* its one line, not merely split into one. ``splitlines`` honours
+        # every separator that would break a table row, including the vertical tab and the
+        # paragraph separator, but it drops a trailing one -- so a summary ending in a newline
+        # splits into a single line and would push the row after it out of the table anyway.
+        summary = self.settings_summary
+        lines = summary.splitlines() if isinstance(summary, str) else []
+        if (
+            not isinstance(summary, str)
+            or not summary.strip()
+            or "|" in summary
+            or len(lines) != 1
+            or lines[0] != summary
+        ):
+            raise ReaderError(
+                "READER_CONTRACT",
+                "toolbox.family.settings_summary",
+                "must be one nonempty line holding no table separator",
+            )
+        # The factory coordinate is written verbatim into a checked-in Python table, so its shape
+        # is refused here rather than trusted. A value carrying a quote would change the emitted
+        # tuple's arity instead of failing, and this is the field that decides what gets imported.
+        if not all(part.isidentifier() for part in self.module_name.split(".")) or (
+            not self.factory_name.isidentifier()
+        ):
+            raise ReaderError(
+                "READER_CONTRACT",
+                "toolbox.family.module_name",
+                "must be a dotted identifier naming one module and one factory",
+            )
+        # The other two fields reach the same emitted tuple through the same interpolation, and
+        # a quote in either would change that tuple's arity rather than fail. Validating only
+        # the import target would have been an arbitrary half of the same rule.
+        quoted = [
+            value
+            for value in (self.optional_dependency, *self.accepted_media_types)
+            if value is not None and ('"' in value or "\\" in value or value != value.strip())
+        ]
+        if quoted:
+            raise ReaderError(
+                "READER_CONTRACT",
+                "toolbox.family.accepted_media_types",
+                "must carry no quote, backslash, or surrounding space",
+            )
+
+    def load(self) -> ReaderFamily:
+        """Import the fixed factory, translating only optional absence/incompatibility."""
+
+        try:
+            module = importlib.import_module(self.module_name)
+            factory = getattr(module, self.factory_name)
+            family = factory()
+        except (AttributeError, ImportError) as exc:
+            if self.optional_dependency is None:
+                raise
+            raise ReaderError(
+                "READER_DEPENDENCY_UNAVAILABLE",
+                "recipe.sources.family_id",
+                f"optional dependency {self.optional_dependency} is unavailable or incompatible "
+                f"for {self.family_id}@{self.family_version}",
+            ) from exc
+        _validate_family(family)
+        for name in (
+            "family_id",
+            "family_version",
+            "contract_version",
+            "output_format",
+            "accepted_media_types",
+            "default_budgets",
+        ):
+            if getattr(family, name) != getattr(self, name):
+                raise ReaderError(
+                    "READER_CONTRACT",
+                    f"toolbox.family.{name}",
+                    "loaded family metadata differs from its certified lazy descriptor",
+                )
+        return family
+
+
+def _validate_family(family: ReaderFamily | _FamilyDescriptor) -> tuple[str, str]:
+    """Validate one concrete family or static descriptor and return its exact key."""
+
+    missing = [name for name in _REQUIRED_MEMBERS if not hasattr(family, name)]
+    if isinstance(family, _FamilyDescriptor):
+        missing = []
+    if missing:
+        raise ReaderError(
+            "READER_CONTRACT",
+            "toolbox.family",
+            f"does not answer the Reader contract: missing {', '.join(sorted(missing))}",
+        )
+    identifier(family.family_id, "toolbox.family.family_id")
+    semver(family.family_version, "toolbox.family.family_version")
+    if family.contract_version != READER_CONTRACT_VERSION:
+        raise ReaderError(
+            "READER_CONTRACT",
+            "toolbox.family.contract_version",
+            f"is not {READER_CONTRACT_VERSION}: a family built against another contract "
+            "cannot enter the table",
+        )
+    if family.output_format not in DATA_FORMATS:
+        raise ReaderError(
+            "READER_CONTRACT",
+            "toolbox.family.output_format",
+            "is not a format the table admits",
+        )
+    media_types = family.accepted_media_types
+    if (
+        not isinstance(media_types, tuple)
+        or not media_types
+        or any(not isinstance(item, str) or not item for item in media_types)
+        or tuple(sorted(set(media_types))) != media_types
+    ):
+        raise ReaderError(
+            "READER_CONTRACT",
+            "toolbox.family.accepted_media_types",
+            "must be a nonempty sorted tuple of distinct media types",
+        )
+    if not isinstance(family.default_budgets, ReaderBudgets):
+        raise ReaderError(
+            "READER_CONTRACT",
+            "toolbox.family.default_budgets",
+            "must be a typed budget object",
+        )
+    return family.family_id, family.family_version
+
+
+class ReaderRegistry:
+    """The closed Reader allowlist, keyed on exact identity and exact version."""
+
+    def __init__(self, families: tuple[ReaderFamily | _FamilyDescriptor, ...] = ()) -> None:
+        self._families: dict[tuple[str, str], ReaderFamily | _FamilyDescriptor] = {}
+        for family in families:
+            self.register(family)
+
+    def register(self, family: ReaderFamily | _FamilyDescriptor) -> None:
+        """Admit one certified family, refusing anything the contract does not allow."""
+
+        key = _validate_family(family)
+        if key in self._families:
+            raise ReaderError(
+                "READER_CONTRACT",
+                "toolbox",
+                f"family {key[0]}@{key[1]} is already registered",
+            )
+        self._families[key] = family
+
+    def resolve(self, family_id: str, family_version: str) -> ReaderFamily:
+        """Return the one family registered under this exact coordinate.
+
+        There is no fallback.  A version this table does not hold is refused by name, and
+        the refusal names the versions that are held, because "the recipe pins 1.0.1 and
+        this build ships 1.0.0" is the fix a person needs to read.
+        """
+
+        try:
+            family = self._families[(family_id, family_version)]
+        except KeyError:
+            available = sorted(
+                version for identity, version in self._families if identity == family_id
+            )
+            known = f"; this build ships {', '.join(available)}" if available else ""
+            raise ReaderError(
+                "READER_FAMILY_UNKNOWN",
+                "recipe.sources.family_id",
+                f"no certified Reader {family_id}@{family_version} is in the Toolbox{known}",
+            ) from None
+        if isinstance(family, _FamilyDescriptor):
+            loaded = family.load()
+            self._families[(family_id, family_version)] = loaded
+            return loaded
+        return family
+
+    def families(self) -> tuple[tuple[str, str], ...]:
+        """The sorted coordinates of every certified family, as a value and not the table."""
+
+        return tuple(sorted(self._families))
+
+    def widest_version(self, family_id: str) -> str:
+        """The highest certified version of one family: the coordinate a new source should pin.
+
+        A weak-label widening lands as a new coordinate rather than an edit to an existing one,
+        so that an already-approved recipe cannot silently begin admitting responses its review
+        never saw.  The cost of that rule is that the *base* version is the wrong default for a
+        source nobody has approved yet: pinning ``delimited_text@1.0.0`` for a brand-new source
+        refuses a publisher that merely declined to describe its file, and the author has to
+        know a version table to avoid it.
+
+        This is the one place that answers "which coordinate should a new pin name".  Highest is
+        decided on the parsed numeric version and never on the string: ``families()`` is sorted
+        lexicographically, where ``1.10.0`` sorts *before* ``1.9.0``, so taking its last entry
+        would answer ``1.9.0`` for a family that had certified ``1.10.0``.  No family carries a
+        double-digit component today, which is exactly why this would have gone unnoticed until
+        one did.
+
+        Choosing a coordinate is not the same as widening one.  This picks among what review has
+        already certified; it can never admit a media type no certified family carries.
+
+        It answers the version question and not the fitness question, and the two come apart on a
+        major bump.  A minor widening inherits ``decode`` untouched, so the highest version seals
+        the bytes the base version would have sealed and only admits more responses.  A major one
+        need not: ``weather.grib2@2.0.0`` emits columns ``1.0.0`` does not, so the highest
+        coordinate there is a different output contract rather than a wider door onto the same
+        one.  A caller pinning a new source still chooses deliberately for such a family; what
+        this removes is having to read a version table to avoid being refused for a label.
+        """
+
+        versions = [version for identity, version in self.families() if identity == family_id]
+        if not versions:
+            raise ReaderError(
+                "READER_FAMILY_UNKNOWN",
+                "toolbox.family",
+                f"{family_id} is not a certified Reader family",
+            )
+        return max(versions, key=lambda version: tuple(int(part) for part in version.split(".")))
+
+    def accepted_media_types(self) -> tuple[str, ...]:
+        """Every media type any certified family admits as input, sorted and de-duplicated.
+
+        A property of the Toolbox rather than of any caller, and the one derivation of it.
+        A fetch for a pinned source has to admit media types no wire format claims -- a zipped
+        source arrives as an archive -- and the answer to "which ones" is this table's to give.
+        Restating a media type outside the module that owns it is the drift the format table's
+        anti-duplication gate exists to catch, and it scans media types as well as format names
+        (the format table's own; a Reader-only media type such as an archive's is bound by each
+        family's certified descriptor and the load-time equality check instead).
+
+        The union is the outer bound.  A single pinned fetch narrows further, to the one
+        family's own declaration, because a source pinned to a zip Reader has no business
+        admitting a spreadsheet.
+        """
+
+        return tuple(
+            sorted(
+                {
+                    media_type
+                    for family in self._families.values()
+                    for media_type in family.accepted_media_types
+                }
+            )
+        )
+
+
+# Certified Reader families. Membership requires adversarial review, an exact decoder pin, and
+# known-good samples. The tuple has no provisional state.
+_CERTIFIED_FAMILIES: tuple[_FamilyDescriptor, ...] = (
+    _FamilyDescriptor(
+        "archive.zip",
+        "1.0.0",
+        "mostlyright.data_harness.readers.containers",
+        "ZipReader",
+        ("application/x-zip-compressed", "application/zip"),
+        settings_summary="`member`; `member_format` (`csv` or `tsv`); optional `header: true`.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.zip",
+        "1.1.0",
+        "mostlyright.data_harness.readers.containers",
+        "ZipReaderV1_1",
+        ("application/x-zip-compressed", "application/zip"),
+        settings_summary="Same, plus `member_format: semicolon` for publishers such as DWD.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.zip",
+        "1.2.0",
+        "mostlyright.data_harness.readers.containers",
+        "ZipReaderV1_2",
+        ("application/octet-stream", "application/x-zip-compressed", "application/zip"),
+        settings_summary=(
+            "Same as `archive.zip@1.1.0`; also accepts a response served as "
+            "`application/octet-stream`."
+        ),
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.gzip",
+        "1.0.0",
+        "mostlyright.data_harness.readers.containers",
+        "GzipReader",
+        ("application/gzip", "application/x-gzip"),
+        settings_summary="`member_format`; optional `header: true`. `member` is invalid.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.gzip",
+        "1.1.0",
+        "mostlyright.data_harness.readers.containers",
+        "GzipReaderV1_1",
+        ("application/gzip", "application/octet-stream", "application/x-gzip"),
+        settings_summary="Same; also accepts a response served as `application/octet-stream`.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.tar",
+        "1.0.0",
+        "mostlyright.data_harness.readers.containers",
+        "TarReader",
+        ("application/x-tar",),
+        settings_summary="Same as `archive.zip@1.0.0`.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "archive.tar",
+        "1.1.0",
+        "mostlyright.data_harness.readers.containers",
+        "TarReaderV1_1",
+        ("application/octet-stream", "application/x-tar"),
+        settings_summary="Same; also accepts a response served as `application/octet-stream`.",
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "spreadsheet.xlsx",
+        "1.0.0",
+        "mostlyright.data_harness.readers.spreadsheet",
+        "SpreadsheetReader",
+        ("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",),
+        settings_summary=(
+            "`sheet`, `header_row`, and `range`. The heading row must be the first row of the "
+            "range."
+        ),
+        default_budgets=spreadsheet_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "spreadsheet.xlsx",
+        "1.1.0",
+        "mostlyright.data_harness.readers.spreadsheet",
+        "SpreadsheetReaderV1_1",
+        (
+            "application/octet-stream",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ),
+        settings_summary="Same; also accepts a response served as `application/octet-stream`.",
+        default_budgets=spreadsheet_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "delimited_text",
+        "1.0.0",
+        "mostlyright.data_harness.readers.delimited",
+        "DelimitedTextReader",
+        ("text/csv", "text/tab-separated-values"),
+        settings_summary=(
+            "`delimiter` (comma or tab); optional `header: true`; optional `encoding: utf-8`."
+        ),
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "delimited_text",
+        "1.1.0",
+        "mostlyright.data_harness.readers.delimited",
+        "DelimitedTextReaderV1_1",
+        ("text/csv", "text/plain", "text/tab-separated-values"),
+        settings_summary=(
+            "Same; also accepts a response served as `text/plain` (common for public agency CSV "
+            "such as IEM)."
+        ),
+        default_budgets=bulk_default_budgets(),
+    ),
+    _FamilyDescriptor(
+        "json.tabular",
+        "1.0.0",
+        "mostlyright.data_harness.readers.json_tabular",
+        "JsonTabularReader",
+        ("application/json", "application/x-ndjson"),
+        settings_summary=(
+            "`columns` with output names and RFC 6901 pointers; optional `document_format` (`json` "
+            "or `ndjson`), `records_pointer`, and sequential `expand` pointers. Columns are "
+            "required unless they state `required: false`."
+        ),
+        default_budgets=_JSON_DEFAULT_BUDGETS,
+    ),
+    _FamilyDescriptor(
+        "json.tabular",
+        "1.1.0",
+        "mostlyright.data_harness.readers.json_tabular",
+        "JsonTabularReaderV1_1",
+        ("application/json", "application/x-ndjson", "text/plain"),
+        settings_summary=(
+            "Same; also accepts a response served as `text/plain` (common for public agency JSON "
+            "and NDJSON)."
+        ),
+        default_budgets=_JSON_DEFAULT_BUDGETS,
+    ),
+    _FamilyDescriptor(
+        "weather.grib2",
+        "1.0.0",
+        "mostlyright.data_harness.readers.grib2.decode",
+        "WeatherGrib2Reader",
+        ("application/octet-stream", "application/wmo-grib2"),
+        settings_summary="`variable`, `points`, and `admission_allowlist_version`.",
+        optional_dependency="mostlyright-grib",
+    ),
+    _FamilyDescriptor(
+        "weather.grib2",
+        "2.0.0",
+        "mostlyright.data_harness.readers.grib2.decode",
+        "WeatherGrib2ReaderV2",
+        ("application/octet-stream", "application/wmo-grib2"),
+        settings_summary=(
+            "Same settings as 1.0.0; output also includes time, level, matched coordinates, and "
+            "message digest."
+        ),
+        optional_dependency="mostlyright-grib",
+    ),
+)
+
+TOOLBOX = ReaderRegistry(_CERTIFIED_FAMILIES)
+
+
+def certified_descriptors() -> tuple[_FamilyDescriptor, ...]:
+    """The frozen certified descriptors, in table order, without loading a single decoder.
+
+    ``TOOLBOX.resolve`` imports the family it answers with, which for ``weather.grib2`` needs an
+    optional binding that a plain install does not carry. Everything restated about a coordinate
+    -- its media types, its factory, the sentence a recipe author reads -- is already on the
+    frozen descriptor, so the table generator reads it from here and never imports anything.
+    """
+
+    return _CERTIFIED_FAMILIES

mostlyright/data_harness/readers/samples/README.md

@@ -0,0 +1,110 @@
+# Known-good samples
+
+A known-good sample is a real file with its correct answer written down beside it. Certification
+requires one: a Reader lands with samples or it does not land.
+
+These samples have two consumers and one purpose. CI decodes every sample on every leg and fails
+if any answer has moved. A refresh re-opens one designated sample before it fetches anything, and
+halts if the answer has moved. Both read the bytes and the recorded answer from this tree through
+one loader (`readers/samples.py`) and compare through one function, so the number CI asserts and
+the number a refresh checks against cannot drift apart. Two copies of one constant is the defect
+this convention exists to prevent.
+
+The tree ships inside the package rather than under `tests/`, because the warm-up check runs in
+production and its sample must be installed with the wheel.
+
+## Layout
+
+```
+samples/<family_id>/<family_version>/<sample_name>/
+    <the sample file under its natural name>
+    expected.json
+```
+
+One directory per sample. The directory names are the identity: an `expected.json` that states a
+`family_id` or `family_version` its directory does not is refused rather than believed. A sample
+directory with no `expected.json` is a failure that names the directory; it is never a skip.
+
+## expected.json
+
+The key set is closed. Every key below is required except `warm_up`, and a key outside the set is
+refused by name.
+
+| Key | Meaning |
+|---|---|
+| `family_id` | The Reader that opens this file. Must equal the directory. |
+| `family_version` | The exact version of that Reader. Must equal the directory. |
+| `decode_options` | The settings the Reader runs with, exactly as a recipe would pin them. |
+| `sample_file` | The sample's filename. A bare name in this directory; never a path. |
+| `normalized_sha256` | The sha256 of the Reader's output bytes — the sealed form, not the input. |
+| `row_count` | How many rows the Reader produces. |
+| `column_names` | The column names it produces, in order. |
+| `flags` | The facts the decode reports about itself, from the closed decode vocabulary. |
+| `provenance` | Where this sample came from and what it proves. See below. |
+| `warm_up` | Optional, default false. Marks the one sample a refresh re-opens. |
+
+Exactly one sample per Reader version sets `warm_up`: it is the file a refresh re-opens before it
+fetches anything. A Reader that designates none cannot be warmed up, and the warm-up check refuses
+rather than passing — an unwarmed Reader is not a warmed one. A Reader that designates two is
+refused when the tree loads, because "one known file" is a property of this tree and not of
+whoever calls the check.
+
+### provenance
+
+Four facts, no more and no fewer:
+
+| Key | Meaning |
+|---|---|
+| `origin` | Where the bytes came from: a URL, or `authored for this test`. |
+| `retrieved` | The date they were obtained, as `YYYY-MM-DD`. |
+| `licence` | The terms the bytes may be redistributed under. |
+| `why` | One sentence on what this sample proves. |
+
+A sample with no provenance cannot pass Certification, because there is nothing to review. The
+loader refuses one, so a sample cannot enter this tree without a claim a person can check.
+
+## Size discipline
+
+Samples are committed bytes that ship in the wheel and are decoded before every refresh. Keep each
+one under 256 KiB. A larger sample is admissible only when the Reader's own plan records why a
+smaller one could not prove the same thing.
+
+That "only when" is checkable rather than a habit. `tests/test_reader_samples.py` holds
+`_OVERSIZE_BY_REVIEW`, one entry per oversize sample, each a path and the written reason. A sample
+over the ceiling with no entry fails; an entry naming a file that is absent, or one that now fits,
+fails too. So the ceiling still applies to every sample that is not on the list, and putting one on
+it is a reviewed source edit with the reason attached — not a raised ceiling.
+
+## Known-good samples are not goldens
+
+This is a rule with a reason, and the reason is the part that matters.
+
+Golden digests in this repository are minted on one authority: the x86_64 Linux `verify` job. Every
+golden-digest assertion therefore sits behind a check on the running machine's architecture, and
+skips when it does not match. That is correct for goldens and wrong for samples: a sample assertion
+built the same way would skip on every arm64 development host, leaving the gate live on CI alone
+while still reporting green on the machine a person is actually working on. (Until ADR 0021
+ADR 0021 there was a third case, the `macos-14` parity leg, which made it one live leg out of
+three; that leg retired with the local lane and the argument did not need it.)
+
+So, concretely:
+
+- Samples live here, never under `tests/fixtures/goldens/`.
+- Samples are never produced by `scripts/mint_goldens.py`, which has no discover-and-overwrite mode
+  by design and knows nothing about this tree.
+- An `expected.json` carrying an `environment` key is refused by name. An identity stamp is how a
+  golden records the machine that produced it, and a sample that recorded one would be asserting a
+  fact about a host instead of a fact about a Reader.
+- Sample assertions carry no architecture guard and no skip. They run, and can fail, everywhere.
+
+A sample's answer is a property of the Reader and the bytes. If it depends on the machine, the
+Reader is not deterministic and that is the finding, not an excuse to gate the assertion.
+
+## Adding a sample
+
+1. Put the file and its `expected.json` in a new directory under the Reader's version.
+2. Record the answer by decoding through the Reader itself — never by copying a number from a failing
+   test. A recorded answer that came from an observed failure records the bug.
+3. State the provenance, including what the sample proves that the existing ones do not.
+4. If it is the sample a refresh should warm up on, set `warm_up` to true and clear the flag from the
+   previous one.

mostlyright/data_harness/readers/samples/archive.gzip/1.0.0/cities_one_stream/expected.json

@@ -0,0 +1,24 @@
+{
+  "column_names": [
+    "city",
+    "population",
+    "note"
+  ],
+  "decode_options": {
+    "header": true,
+    "member_format": "csv"
+  },
+  "family_id": "archive.gzip",
+  "family_version": "1.0.0",
+  "flags": [],
+  "normalized_sha256": "09ffd82e7942d837974824bd381d76ad9fee3f916f51b9217e5df0cf034e64dd",
+  "provenance": {
+    "licence": "project-owned test fixture, redistributable with the package",
+    "origin": "authored for this test",
+    "retrieved": "2026-08-07",
+    "why": "proves the degenerate form of clause 2: one gzip stream with no member name, whose inner form the recipe still states, carrying a missing cell so the empty cell survives the round trip through the canonical emitter"
+  },
+  "row_count": 2,
+  "sample_file": "cities.csv.gz",
+  "warm_up": true
+}

mostlyright/data_harness/readers/samples/archive.gzip/1.1.0/cities_one_stream/expected.json

@@ -0,0 +1,24 @@
+{
+  "column_names": [
+    "city",
+    "population",
+    "note"
+  ],
+  "decode_options": {
+    "header": true,
+    "member_format": "csv"
+  },
+  "family_id": "archive.gzip",
+  "family_version": "1.1.0",
+  "flags": [],
+  "normalized_sha256": "09ffd82e7942d837974824bd381d76ad9fee3f916f51b9217e5df0cf034e64dd",
+  "provenance": {
+    "licence": "project-owned test fixture, redistributable with the package",
+    "origin": "authored for this test",
+    "retrieved": "2026-08-07",
+    "why": "proves the degenerate form of clause 2 \u2014 one gzip stream with no member name, whose inner form the recipe still states, carrying a missing cell so the empty cell survives the round trip through the canonical emitter \u2014 carried byte-for-byte from the archive.gzip@1.0.0 warm-up sample because this coordinate widens only the label a response may arrive under and inherits the decode unchanged."
+  },
+  "row_count": 2,
+  "sample_file": "cities.csv.gz",
+  "warm_up": true
+}