mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/serving.py

@@ -0,0 +1,1975 @@
+"""Serving: the one door into a sealed version, and the index that points at one.
+
+A request reaches a dataset's bytes through exactly one function here, and that function verifies
+the build before it returns anything. Four boundaries this module holds on purpose:
+
+* **It serves only what review admits.** Every read runs :func:`recipe.verify_recipe_candidate` and
+  then requires ``drift_report.status == "passed"`` — the same pair
+  :func:`deploy.build_deployment_request` already established as what "reviewed and sealed" means in
+  this repository. Standing on that exact pair is deliberate: anything looser serves an unreviewed
+  draft, and anything different creates a second definition of reviewed, after which the two drift.
+  There is no parameter anywhere on this path that skips the gate, which is a property of the
+  signatures rather than of a filter.
+* **It never fetches an origin.** The only bytes any path through this module reads are a sealed run
+  directory's. The network call that authorizes a caller happens at the edge, in a different module,
+  on purpose: keeping it out of here is what makes "no origin fetch" checkable by reading this file.
+* **It never writes.** No path through this module creates, moves, or truncates anything, including
+  the version index.
+* **The recipe defines the build, never the serving.** A dataset's shape is read from the sealed
+  tree — ``evidence/profile.json``, ``plan.json`` and ``table_card.md`` — and no field of
+  :class:`recipe.FrozenRecipe` other than identity is consulted. A serving clause in a recipe would
+  make two datasets need two serving code paths.
+
+**The version index is evidence, never authority.** The Vault and Current do not exist in this
+repository yet, so a read resolves one through an operator-supplied canonical JSON document that
+this module READS and never writes. That document is deliberately weak: every field it states —
+dataset id, version id, version number, version digest — is re-derived from the sealed run directory
+before a byte is served, and any disagreement is a refusal naming both values. A corrupted or
+hostile index therefore cannot cause an unsealed or wrong serve; the worst it can do is refuse.
+Directory scanning is prohibited because target selection must be explicit.
+
+**What this ordering costs, stated rather than hidden.** Every request runs one full verification,
+deterministic replay included, so a read is slow in exactly the way a proof is slow — a whole
+sealed build is re-derived and re-digested before the first byte is handed back. The resulting
+verified snapshot retains its authenticated descriptor lease through the response and supplies the
+Parquet reader directly; serving then holds one Arrow batch plus the bounded response window while
+it iterates row groups. Verification is intentionally per request. Any future cross-request cache
+would need a written invalidation contract tied to the version digest before it could preserve the
+same proof boundary.
+
+Refusals are quiet and typed. Every declining path raises :class:`ServingRefused` with named
+reasons, and every reason is a plain sentence carrying at most a bracketed machine code. The
+engineering vocabulary of the exception a reason was translated from does not travel with it; see
+:func:`_refusal_for`.
+
+**One envelope, and one crossing between the two vocabularies.** Every shape this surface answers
+returns a :class:`ServingResult`, and every response is rendered from
+:meth:`ServingResult.to_dict` — the JSON body and the human lines alike. That is what makes "every
+response carries the version digest it was served from" a property of one class rather than a habit
+four handlers share. It is also the single place where the engineering names on
+:class:`SealedVersion` become the plain wire names ``version_digest`` and ``table_digest``; the
+decision, its scope and its cost are written out on :meth:`ServingResult.to_dict`.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import re
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+import pyarrow as pa
+import pyarrow.compute as pc
+
+from mostlyright.data_harness import canonical, deploy, events, pipeline, recipe, rowset
+from mostlyright.data_harness.local_contracts import is_single_plain_line
+
+#: Every wire name this surface reads or emits is registered under this prefix, in the convention
+#: ``deploy.DEPLOYMENT_REQUEST_SCHEMA`` already uses: one product-scoped name and one integer
+#: version, bumped whenever the fields change meaning.
+SERVING_SCHEMA_PREFIX = "mostlyright-"
+
+# Defense in depth for a synthetic or legacy result that bypassed the sealed-version opener. The
+# authoritative recipe boundary rejects these bytes; this map keeps the human renderer one-line
+# even if a caller constructs a result directly. U+009B and bidi controls are intentionally not
+# escaped here: their terminal policy remains the separately recorded M16 decision.
+_DISPLAY_LINE_BOUNDARY_ESCAPES = str.maketrans(
+    {
+        "\n": r"\n",
+        "\r": r"\r",
+        "\v": r"\v",
+        "\f": r"\f",
+        "\x1c": r"\u001c",
+        "\x1d": r"\u001d",
+        "\x1e": r"\u001e",
+        "\x85": r"\u0085",
+        "\u2028": r"\u2028",
+        "\u2029": r"\u2029",
+    }
+)
+
+#: The operator-written document that says which sealed directories may be served, and which
+#: version each dataset's Current names.
+VERSION_INDEX_SCHEMA = f"{SERVING_SCHEMA_PREFIX}table-version-index.v1"
+
+#: The envelope EVERY serving response is rendered from, whatever shape answered it. One name for
+#: one body: a caller parses one document shape and finds the version digest in the same place
+#: whether it asked what a dataset is, for one row, or for a slice.
+SERVING_RESULT_SCHEMA = f"{SERVING_SCHEMA_PREFIX}table-serving-result.v1"
+
+#: The status word an answered discovery carries.
+STATUS_DATASET_DESCRIBED = "dataset_described"
+
+#: The status word every refusal carries, whatever declined it. A caller branches on ``ok``; the
+#: status says which question was being answered when it was declined, and there is only one
+#: refusing answer to give.
+STATUS_REFUSED = "serving_refused"
+
+#: A status is a plain lowercase machine word. It is emitted, so it is scanned by 32.6-08's sweep.
+_STATUS = re.compile(r"\A[a-z][a-z0-9_]{0,63}\Z")
+
+# These two bounds are not a product limit and must not be read as one. The index is a file an
+# operator writes by hand or a future refresh path generates, and it is parsed before anything about
+# it is known to be true; the bounds exist so a malformed or hostile file is cheap to refuse rather
+# than expensive to walk. They are set far above any plausible real catalog for that reason: if a
+# deployment ever approaches either number, the answer is a real catalog store, not a larger
+# constant here.
+MAX_INDEXED_DATASETS = 256
+MAX_INDEXED_VERSIONS_PER_DATASET = 1_024
+
+# The index is untrusted mutable input read by a long-lived process. This ceiling is deliberately
+# generous for the closed dataset/version counts above while still refusing before an attacker can
+# make a request allocate an arbitrary local file.
+MAX_VERSION_INDEX_BYTES = 8 * 1024 * 1024
+
+#: The largest ``run_dir`` this reader accepts, and the largest single component of one. The
+#: component bound is POSIX ``NAME_MAX``, so nothing longer can name a directory on a filesystem
+#: this product runs on; the whole-path bound is far above any layout an operator writes by hand and
+#: is here for the reason the two index bounds above are.
+MAX_RUN_DIR_CHARS = 1_024
+MAX_RUN_DIR_COMPONENT_CHARS = 255
+
+#: The largest dataset id this surface reads or echoes. :data:`_IDENT` bounds a dataset id at 128
+#: characters, so nothing longer can name a listed dataset and nothing longer needs to be repeated
+#: back to the caller who asked for it.
+MAX_DATASET_ID_CHARS = 128
+
+#: The largest pin this surface reads or echoes. The longest spelling the grammar admits is
+#: ``version:`` followed by a 128-character version id.
+#:
+#: Both bounds live HERE, in the module that owns the grammar, and the transport references them
+#: rather than declaring its own. A transport bound that can drift from the library's is a second
+#: policy, and the one that binds is whichever runs first.
+MAX_PIN_CHARS = 256
+
+#: The pin vocabulary is CLOSED and is exactly these three spellings.
+PIN_CURRENT = "current"
+_PIN_VERSION_PREFIX = "version:"
+_PIN_DIGEST_PREFIX = "sha256:"
+
+_DIGEST = re.compile(r"\A[0-9a-f]{64}\Z")
+
+# The identifier shape ``recipe._IDENT`` already admits for a dataset id and a version id. Reusing
+# it rather than inventing a second one keeps an id that a sealed execution record accepts from
+# being an id the index cannot spell.
+_IDENT = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\Z")
+
+_INDEX_KEYS = frozenset({"schema_version", "datasets"})
+_DATASET_KEYS = frozenset({"dataset_id", "table_id", "current_version_id", "versions"})
+_VERSION_KEYS = frozenset(
+    {
+        "version_id",
+        "version_number",
+        "version_digest",
+        "run_dir",
+        "predecessor_version_id",
+    }
+)
+
+
+class ServingRefused(RuntimeError):
+    """A read was declined, with every reason named. Never a partial answer.
+
+    Shaped exactly like :class:`deploy.DeployRefused`: one type for a caller to catch, at least one
+    named reason, and no path that returns half an answer. A refusal is an expected outcome — an
+    unreviewed build, a corrupted index, a pin naming nothing — and every one of them is something
+    the operator or the caller can act on.
+    """
+
+    def __init__(self, *reasons: str) -> None:
+        cleaned = tuple(reason.strip() for reason in reasons if reason and reason.strip())
+        if not cleaned:
+            raise ValueError("a refusal must name at least one reason")
+        self.reasons: tuple[str, ...] = cleaned
+        super().__init__("; ".join(cleaned))
+
+
+@dataclass(frozen=True)
+class IndexedVersion:
+    """One version's row in the index: what the operator SAYS about a sealed directory.
+
+    Every field here is a claim, not a fact. :func:`open_sealed_version` re-derives all of them from
+    the sealed tree and refuses any disagreement, so nothing downstream may treat these values as
+    authoritative.
+
+    ``version_digest`` carries the wire name because this dataclass mirrors an operator-written
+    document one field for one key. :class:`SealedVersion` mirrors
+    :class:`pipeline.VerifiedCandidate` instead and therefore keeps that type's engineering names
+    (``candidate_digest``, ``table_sha256``). The asymmetry is deliberate: each dataclass carries
+    the names of the thing it mirrors, and the one place the two vocabularies meet is
+    ``ServingResult.to_dict``.
+
+    ``run_dir`` is the resolved absolute path. Resolution happens in the parser so no later code has
+    to remember to do it, and so a path refusal is raised before any filesystem access.
+    """
+
+    dataset_id: str
+    version_id: str
+    version_number: int
+    version_digest: str
+    run_dir: Path
+    predecessor_version_id: str | None
+
+
+@dataclass(frozen=True)
+class IndexedDataset:
+    """One dataset's block in the index: the versions it lists, and which one Current names."""
+
+    dataset_id: str
+    table_id: str
+    current_version_id: str
+    versions: tuple[IndexedVersion, ...]
+
+    def version(self, version_id: str) -> IndexedVersion | None:
+        """Return the listed version with this id, or nothing."""
+
+        for entry in self.versions:
+            if entry.version_id == version_id:
+                return entry
+        return None
+
+
+@dataclass(frozen=True)
+class VersionIndex:
+    """A whole parsed index: which datasets exist, where their versions are, and what Current is."""
+
+    schema: str
+    root: Path
+    datasets: tuple[IndexedDataset, ...]
+
+    def dataset(self, dataset_id: str) -> IndexedDataset | None:
+        """Internal Table lookup retained while callers migrate to :meth:`table`."""
+
+        for entry in self.datasets:
+            if entry.table_id == dataset_id:
+                return entry
+        return None
+
+    def table(self, dataset_id: str, table_id: str) -> IndexedDataset | None:
+        """Return only an exact parent Dataset/Table coordinate; never infer a parent."""
+
+        for entry in self.datasets:
+            if entry.dataset_id == dataset_id and entry.table_id == table_id:
+                return entry
+        return None
+
+    @property
+    def dataset_ids(self) -> tuple[str, ...]:
+        """Every dataset id this index lists, in the order it lists them."""
+
+        return tuple(entry.table_id for entry in self.datasets)
+
+
+def _one_plain_line(value: Any, limit: int) -> bool:
+    """Whether ``value`` is text, one plain line, and within ``limit`` characters.
+
+    ``deploy._PLAIN_LINE`` (``deploy.py:63``) is the rule and it is REFERENCED rather than restated:
+    text with no ASCII control, DEL, or Unicode line boundary anywhere in it, which is the same
+    regular expression ``deploy`` already applies to every name it prints. A second spelling of
+    this rule is how one surface comes to admit a character another refuses.
+
+    Two kinds of string reach this function and both need the same answer. One is a piece of an
+    operator's version index that becomes a filesystem path, where a control character is a fault
+    the path checks below cannot see: ``PurePosixPath('version-1\\x00extra').as_posix()`` is
+    byte-identical to what went in, so every shape rule that path spelling can express passes, and
+    the refusal only arrives as a ``ValueError`` out of the first ``stat``. The other is a piece of
+    a request this surface echoes back — a dataset id, a pin — which :func:`serving_lines` renders
+    beside real facts like ``version checksum:``. A value carrying a newline could forge one of
+    those lines; a value carrying a hundred kilobytes is not a name.
+    """
+
+    return (
+        isinstance(value, str)
+        and len(value) <= limit
+        and deploy._PLAIN_LINE.fullmatch(value) is not None
+    )
+
+
+def _text(value: Any, label: str) -> str:
+    if not isinstance(value, str) or _IDENT.fullmatch(value) is None:
+        raise ServingRefused(
+            f"the version index does not name {label} in the agreed shape: a name is up to 128 "
+            "letters, digits, dots, dashes or underscores [SERVING_INDEX_FIELD]"
+        )
+    return value
+
+
+def _closed_keys(value: Any, expected: frozenset[str], label: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise ServingRefused(
+            f"the version index must describe {label} as a JSON object [SERVING_INDEX_SHAPE]"
+        )
+    if "candidate_digest" in value and "version_digest" not in value:
+        # The one plausible wrong spelling, named rather than reported as an unknown key: the
+        # engineering name for this value really is candidate_digest, so an operator who read the
+        # build's own JSON output would write it in good faith.
+        raise ServingRefused(
+            "the version index names each version's digest version_digest, and this one carries "
+            "candidate_digest instead [SERVING_INDEX_FIELD]"
+        )
+    unknown = sorted(set(value) - expected)
+    if unknown:
+        raise ServingRefused(
+            f"the version index names fields on {label} that this reader does not know: "
+            + ", ".join(unknown)
+            + " [SERVING_INDEX_FIELD]"
+        )
+    missing = sorted(expected - set(value))
+    if missing:
+        raise ServingRefused(
+            f"the version index leaves fields off {label}: "
+            + ", ".join(missing)
+            + " [SERVING_INDEX_FIELD]"
+        )
+    return value
+
+
+def _indexed_run_dir(value: Any, root: Path, label: str) -> Path:
+    """Resolve one ``run_dir`` against the index root, refusing anything that could leave it.
+
+    The rules and their wording follow ``pipeline._validated_source_relative_path``, and the
+    absolute form is taken with ``pipeline._absolute_lexical_path`` — which makes a path absolute
+    WITHOUT resolving or following any filesystem component. Both are cited rather than
+    reimplemented so this module does not become a third path policy that can disagree with the
+    other two. All of it happens before any filesystem access, so a hostile index cannot make the
+    reader stat a path outside its own directory even once.
+
+    **Every component is one plain line, and that check comes first.** The shape rules below are
+    about where a path points, and none of them can see a control character: a component holding a
+    NUL round-trips through :class:`PurePosixPath` byte-identically and satisfies all of them, so
+    without this gate the refusal arrives as a ``ValueError`` out of the first ``stat`` — which is a
+    fault rather than a refusal, and this module's contract is that a hostile index can only ever
+    make it refuse. The rule is :func:`_one_plain_line`, which is ``deploy._PLAIN_LINE``.
+
+    The refusing sentence names the field and never repeats the value back, for the same reason the
+    rule exists: a value that failed the plain-line check is exactly the value that must not reach a
+    log line.
+    """
+
+    if not isinstance(value, str) or not value or "\\" in value:
+        raise ServingRefused(
+            f"the version index must name {label} as a relative path using '/' separators "
+            "[SERVING_INDEX_PATH]"
+        )
+    pure = PurePosixPath(value)
+    if not _one_plain_line(value, MAX_RUN_DIR_CHARS) or any(
+        not _one_plain_line(part, MAX_RUN_DIR_COMPONENT_CHARS) for part in pure.parts
+    ):
+        raise ServingRefused(
+            f"the version index must name {label} as plain path components of at most "
+            f"{MAX_RUN_DIR_COMPONENT_CHARS} characters each, with no control character in any of "
+            "them [SERVING_INDEX_PATH]"
+        )
+    if (
+        pure.is_absolute()
+        or not pure.parts
+        or any(part in {"", ".", ".."} for part in pure.parts)
+        or pure.as_posix() != value
+    ):
+        raise ServingRefused(
+            f"the version index names a directory outside its own folder for {label}: {value} "
+            "[SERVING_INDEX_PATH]"
+        )
+    resolved = pipeline._absolute_lexical_path(root / pure)
+    if not pipeline._is_relative_to(resolved, root):
+        raise ServingRefused(
+            f"the version index names a directory outside its own folder for {label}: {value} "
+            "[SERVING_INDEX_PATH]"
+        )
+    return resolved
+
+
+def _indexed_version(value: Any, *, dataset_id: str, root: Path) -> IndexedVersion:
+    version = _closed_keys(value, _VERSION_KEYS, f"a version of dataset {dataset_id}")
+    version_id = _text(version["version_id"], f"a version of dataset {dataset_id}")
+    number = version["version_number"]
+    if type(number) is not int or number < 1:
+        raise ServingRefused(
+            f"the version number of {version_id} must be a whole number of at least 1 "
+            "[SERVING_INDEX_FIELD]"
+        )
+    digest = version["version_digest"]
+    if not isinstance(digest, str) or _DIGEST.fullmatch(digest) is None:
+        raise ServingRefused(
+            f"the version digest of {version_id} must be a 64-character lowercase hex digest "
+            "[SERVING_INDEX_FIELD]"
+        )
+    predecessor = version["predecessor_version_id"]
+    if predecessor is not None:
+        predecessor = _text(predecessor, f"the version {version_id} follows")
+    return IndexedVersion(
+        dataset_id=dataset_id,
+        version_id=version_id,
+        version_number=number,
+        version_digest=digest,
+        run_dir=_indexed_run_dir(version["run_dir"], root, f"version {version_id}"),
+        predecessor_version_id=predecessor,
+    )
+
+
+def _indexed_dataset(value: Any, *, root: Path) -> IndexedDataset:
+    dataset = _closed_keys(value, _DATASET_KEYS, "a dataset")
+    dataset_id = _text(dataset["dataset_id"], "a dataset")
+    table_id = _text(dataset["table_id"], f"a table in dataset {dataset_id}")
+    versions = dataset["versions"]
+    if not isinstance(versions, list) or not versions:
+        raise ServingRefused(
+            f"the version index lists no versions for dataset {dataset_id} [SERVING_INDEX_SHAPE]"
+        )
+    if len(versions) > MAX_INDEXED_VERSIONS_PER_DATASET:
+        raise ServingRefused(
+            f"the version index lists more than {MAX_INDEXED_VERSIONS_PER_DATASET} versions for "
+            f"dataset {dataset_id} [SERVING_INDEX_BOUNDS]"
+        )
+    parsed = tuple(_indexed_version(item, dataset_id=table_id, root=root) for item in versions)
+    seen: set[str] = set()
+    for entry in parsed:
+        if entry.version_id in seen:
+            raise ServingRefused(
+                f"the version index lists version {entry.version_id} of dataset {dataset_id} more "
+                "than once, so it does not say which directory that version is "
+                "[SERVING_INDEX_AMBIGUOUS]"
+            )
+        seen.add(entry.version_id)
+    digests: set[str] = set()
+    for entry in parsed:
+        if entry.version_digest in digests:
+            # A pin of the form sha256:<digest> names ONE version. Two entries carrying one digest
+            # would make that spelling ambiguous, and an ambiguous pin is not a pin.
+            raise ServingRefused(
+                f"the version index gives two versions of dataset {dataset_id} the same digest, so "
+                f"a read pinned to {entry.version_digest} would be ambiguous "
+                "[SERVING_INDEX_AMBIGUOUS]"
+            )
+        digests.add(entry.version_digest)
+    current = _text(dataset["current_version_id"], f"the current version of dataset {dataset_id}")
+    if current not in seen:
+        raise ServingRefused(
+            f"the version index says the current version of dataset {dataset_id} is {current}, and "
+            "does not list a version by that name [SERVING_INDEX_CURRENT]"
+        )
+    return IndexedDataset(
+        dataset_id=dataset_id,
+        table_id=table_id,
+        current_version_id=current,
+        versions=parsed,
+    )
+
+
+def parse_version_index(raw: bytes | str, *, root: Path) -> VersionIndex:
+    """Read the operator-supplied version index strictly, and trust it for nothing.
+
+    ``root`` is the directory the index file itself lives in. Every ``run_dir`` is resolved against
+    it lexically, and anything absolute, anything carrying a parent component, and anything whose
+    resolved form is not under ``root`` is refused before a single filesystem call is made.
+
+    The bytes are read with :func:`canonical.parse_canonical_json`, so a hand-edited or
+    re-serialized file is refused rather than acted on — the same discipline
+    ``governors.FileCapStore`` applies to its own store. Nothing about the returned index is treated
+    as true: it is a set of claims that
+    :func:`open_sealed_version` checks against the sealed trees they describe.
+
+    Raises:
+        ServingRefused: when the bytes are not canonical JSON, when the document is not
+            ``mostlyright-version-index.v1``, when any field is not the agreed shape, when a dataset
+            or version is listed twice, when Current names nothing, or when a ``run_dir`` could
+            leave the index's own directory.
+    """
+
+    index_root = pipeline._absolute_lexical_path(Path(root))
+    try:
+        document = canonical.parse_canonical_json(raw)
+    except canonical.CanonicalJSONError as error:
+        # Translated, not passed through: the parser's detail is written for an engineer reading a
+        # stack trace, and this sentence is printed to whoever wrote the file.
+        raise ServingRefused(
+            "the version index is not the canonical JSON this reader accepts, so it was not read "
+            f"[{error.code}]"
+        ) from error
+
+    top = _closed_keys(document, _INDEX_KEYS, "the version index")
+    schema = top["schema_version"]
+    if schema != VERSION_INDEX_SCHEMA:
+        found = schema if isinstance(schema, str) else type(schema).__name__
+        raise ServingRefused(
+            f"the version index must be {VERSION_INDEX_SCHEMA}, and this one says {found} "
+            "[SERVING_INDEX_SCHEMA]"
+        )
+    datasets = top["datasets"]
+    if not isinstance(datasets, list) or not datasets:
+        raise ServingRefused("the version index lists no datasets [SERVING_INDEX_SHAPE]")
+    if len(datasets) > MAX_INDEXED_DATASETS:
+        raise ServingRefused(
+            f"the version index lists more than {MAX_INDEXED_DATASETS} datasets "
+            "[SERVING_INDEX_BOUNDS]"
+        )
+    parsed = tuple(_indexed_dataset(item, root=index_root) for item in datasets)
+    seen: set[str] = set()
+    for entry in parsed:
+        if entry.table_id in seen:
+            raise ServingRefused(
+                f"the version index lists table {entry.table_id} more than once, so it does "
+                "not say which block describes it [SERVING_INDEX_AMBIGUOUS]"
+            )
+        seen.add(entry.table_id)
+    return VersionIndex(schema=VERSION_INDEX_SCHEMA, root=index_root, datasets=parsed)
+
+
+def read_version_index(path: Path) -> VersionIndex:
+    """Read the index document at ``path`` and parse it, resolving every ``run_dir`` beside it.
+
+    The read path's own reader: it turns a file into an index with a refusal a CUSTOMER may see, so
+    it names no path in its sentence. ``mr-data serve``'s start-up check reads the same document
+    through the command line's own file reader, which does name the path, because an operator who
+    mistyped one is the only reader of that sentence. Both end in :func:`parse_version_index`, so
+    there is one parser and two audiences rather than two readers. It reads and never writes, like
+    everything else here.
+
+    The index is read for each request so ``current`` resolves against the latest complete document.
+
+    Raises:
+        ServingRefused: when the file cannot be read, and for every reason
+            :func:`parse_version_index` refuses.
+    """
+
+    location = Path(path)
+    try:
+        raw = events.read_regular_bytes(location, max_bytes=MAX_VERSION_INDEX_BYTES)
+    except OSError as error:
+        # The operator's path is deliberately absent from the sentence: this refusal is rendered
+        # into a customer-facing envelope, and a response is not a place to publish where a
+        # deployment keeps its files. The errno stays on the exception this one is chained to.
+        raise ServingRefused(
+            "the version index could not be read, so no read was served [SERVING_INDEX_UNREADABLE]"
+        ) from error
+    return parse_version_index(raw, root=location.parent)
+
+
+def _elsewhere(
+    index: VersionIndex,
+    match: Callable[[IndexedVersion], bool],
+) -> tuple[str, str] | None:
+    """Return (dataset_id, version_id) for the first version in ANY dataset that matches."""
+
+    for dataset in index.datasets:
+        for entry in dataset.versions:
+            if match(entry):
+                return dataset.dataset_id, entry.version_id
+    return None
+
+
+def resolve_pin(index: VersionIndex, dataset_id: str, pin: str) -> IndexedVersion:
+    """Turn one pin into one listed version, or refuse.
+
+    The pin vocabulary is CLOSED and is exactly three spellings:
+
+    * ``"current"`` — whatever the index says this dataset's Current is right now.
+    * ``"version:<version id>"`` — one named version, whatever Current becomes.
+    * ``"sha256:<64 lowercase hex>"`` — one version by its digest.
+
+    The digest spelling leads because it is the only one that is self-authenticating against the
+    sealed tree WITHOUT the index: a caller holding a digest can check for itself that the bytes it
+    received are the bytes it asked for. The other two mean something only relative to a document.
+
+    A version NUMBER is deliberately not a pin spelling. Numbers resolve only through the index, and
+    the index is evidence; a pin has to be able to mean something without it, and "version 2" does
+    not.
+
+    **A pin and a dataset id are each one plain line, bounded, before either is repeated back.**
+    This is the library's own gate and not the transport's: the production topology is a library
+    caller — the Studio API edge, calling with an already-verified key id — so a bound that only
+    exists in ``serving_http`` is a bound production does not have. Both values reach a refusal
+    sentence here and the envelope's ``dataset_id`` and ``pin`` fields, which
+    :func:`serving_lines` renders beside ``version checksum:`` and ``table checksum:``. An
+    unbounded, unchecked echo there is how a caller writes a line into this product's own human
+    rendering that no sealed version produced. The rule is :func:`_one_plain_line`; a value that
+    fails it is refused without being quoted.
+
+    Raises:
+        ServingRefused: when the dataset is not listed, when the pin is spelled outside the closed
+            set, when it names no listed version, or when it names a version of another dataset.
+    """
+
+    if not _one_plain_line(pin, MAX_PIN_CHARS):
+        raise ServingRefused(
+            "a version is asked for as one plain line of at most "
+            f"{MAX_PIN_CHARS} characters: current, version:<version id>, or sha256:<digest> "
+            "[SERVING_PIN]"
+        )
+    if not _one_plain_line(dataset_id, MAX_DATASET_ID_CHARS):
+        raise ServingRefused(
+            "a dataset is named by one plain line of at most "
+            f"{MAX_DATASET_ID_CHARS} characters [SERVING_DATASET_UNKNOWN]"
+        )
+    dataset = index.dataset(dataset_id)
+    if dataset is None:
+        raise ServingRefused(
+            f"there is no dataset called {dataset_id} here [SERVING_DATASET_UNKNOWN]"
+        )
+
+    if pin == PIN_CURRENT:
+        current = dataset.version(dataset.current_version_id)
+        # The parser already refused an index whose Current names nothing, so this is unreachable
+        # from a parsed index; it is restated because the alternative is an assert that a caller
+        # holding a hand-built index could trip into returning None.
+        if current is None:  # pragma: no cover - refused at parse time
+            raise ServingRefused(
+                f"the current version of dataset {dataset_id} is not listed [SERVING_INDEX_CURRENT]"
+            )
+        return current
+
+    if pin.startswith(_PIN_VERSION_PREFIX):
+        wanted = pin[len(_PIN_VERSION_PREFIX) :]
+        found = dataset.version(wanted)
+        if found is not None:
+            return found
+        other = _elsewhere(index, lambda entry: entry.version_id == wanted)
+        if other is not None:
+            raise ServingRefused(
+                f"version {wanted} belongs to dataset {other[0]}, not to dataset {dataset_id} "
+                "[SERVING_PIN_DATASET]"
+            )
+        raise ServingRefused(
+            f"there is no version {wanted} of dataset {dataset_id} here [SERVING_VERSION_UNKNOWN]"
+        )
+
+    if pin.startswith(_PIN_DIGEST_PREFIX):
+        wanted = pin[len(_PIN_DIGEST_PREFIX) :]
+        if _DIGEST.fullmatch(wanted) is None:
+            raise ServingRefused(
+                "a version pinned by digest is asked for as sha256: followed by 64 lowercase hex "
+                "characters [SERVING_PIN]"
+            )
+        for entry in dataset.versions:
+            if entry.version_digest == wanted:
+                return entry
+        other = _elsewhere(index, lambda entry: entry.version_digest == wanted)
+        if other is not None:
+            raise ServingRefused(
+                f"the version with digest {wanted} belongs to dataset {other[0]}, not to dataset "
+                f"{dataset_id} [SERVING_PIN_DATASET]"
+            )
+        raise ServingRefused(
+            f"there is no version with digest {wanted} of dataset {dataset_id} here "
+            "[SERVING_VERSION_UNKNOWN]"
+        )
+
+    raise ServingRefused(
+        "a version is asked for as current, as version:<version id>, or as sha256:<digest>, and "
+        f"{pin} is none of those [SERVING_PIN]"
+    )
+
+
+@dataclass(frozen=True)
+class SealedVersion:
+    """One verified, reviewed version, opened: identity, digests, shape, and small evidence.
+
+    A value of this type exists only on the far side of :func:`open_sealed_version`, which is the
+    only function that constructs one. That is the structural half of "serves only sealed versions":
+    there is no other way to obtain these facts, and no argument that produces one without the
+    gate. The potentially large Parquet member deliberately does not live on this value; row
+    serving reads it through the retained :class:`pipeline.VerifiedSnapshot` descriptor.
+
+    Its digest attributes are ``candidate_digest`` and ``table_sha256`` — the names
+    :class:`pipeline.VerifiedCandidate` uses — because this type mirrors that one. The rename to the
+    wire names ``version_digest`` and ``table_digest`` happens exactly once in
+    ``ServingResult.to_dict``. This type does not carry both names.
+
+    ``pin_kind`` is ``"current"`` or ``"pinned"``: which question the caller asked, recorded so a
+    response can say whether the digest it carries is a moving target or a promise.
+
+    ``sources``, ``join``, ``quality`` and ``lineage`` are the sealed evidence documents decoded,
+    and they live here rather than being re-read by a shape that wants them. That is the whole
+    point of the single opening: the tree is observed once, under one lease, and every fact a
+    response can carry comes out of that observation. A second read could observe different bytes.
+    """
+
+    dataset_id: str
+    version_id: str
+    version_number: int
+    candidate_digest: str
+    table_sha256: str
+    columns: tuple[str, ...]
+    column_types: tuple[tuple[str, str], ...]
+    grain: tuple[str, ...]
+    row_count: int
+    question: str
+    table_card: bytes
+    pin_kind: str
+    sources: tuple[Any, ...]
+    join: Mapping[str, Any]
+    quality: Mapping[str, Any]
+    lineage: Mapping[str, Any]
+
+
+def _named(entry: IndexedVersion) -> str:
+    """The phrase every refusal about one version opens with, written once."""
+
+    return f"version {entry.version_id} of dataset {entry.dataset_id}"
+
+
+def _refusal_for(error: Exception, entry: IndexedVersion) -> str:
+    """Turn a typed build or recipe failure into one plain sentence a customer can read.
+
+    TRANSLATE; do not pass through. The verifier's own free-text detail is written in the
+    engineering vocabulary — "is not a recipe candidate" — and ``docs/VOCABULARY.md`` supersedes the
+    word at its centre. These sentences are read by whoever called the serving surface. The failing
+    part and the bracketed code travel, because the code is the precise greppable handle and
+    ``mr-data recipe-verify`` on the same directory prints the full engineering text; the
+    engineering sentence itself does not travel. ``deploy._refusal_for`` established this shape and
+    the reason for it, including the special case for a missing predecessor — a different next
+    action for the operator, which must not be paraphrased as a verification failure.
+    """
+
+    if isinstance(error, recipe.RecipeError) and error.code == "RECIPE_PREDECESSOR":
+        return (
+            f"{_named(entry)} follows an earlier version, and the version index does not say which "
+            "one, so it was not served [SERVING_PREDECESSOR]"
+        )
+    if isinstance(error, recipe.RecipeError):
+        return (
+            f"{_named(entry)} is not a reviewed, sealed build that can be served: {error.path} "
+            f"[{error.code}]"
+        )
+    if isinstance(error, pipeline.BuildError):
+        # A directory with no sealed build in it at all is refused one layer below the recipe
+        # rules, so the greppable handle here is the build gate's finding id rather than a recipe
+        # code. The next action is the same either way: point the index at a reviewed build.
+        return (
+            f"{_named(entry)} is not a reviewed, sealed build that can be served "
+            f"[{error.finding_id}]"
+        )
+    return (
+        f"{_named(entry)} could not be read as a reviewed, sealed build "
+        f"[{type(error).__name__.upper()}]"
+    )
+
+
+def _predecessor_run_dir(index: VersionIndex, entry: IndexedVersion) -> Path | None:
+    """Resolve the directory holding the version this one follows, or refuse."""
+
+    if entry.predecessor_version_id is None:
+        return None
+    dataset = index.dataset(entry.dataset_id)
+    previous = None if dataset is None else dataset.version(entry.predecessor_version_id)
+    if previous is None:
+        raise ServingRefused(
+            f"{_named(entry)} follows {entry.predecessor_version_id}, and the version index does "
+            "not list a version by that name, so it was not served [SERVING_PREDECESSOR]"
+        )
+    return previous.run_dir
+
+
+def _sealed_document(members: Mapping[str, bytes], path: str, entry: IndexedVersion) -> Any:
+    """Read one sealed JSON member, keeping every non-integer number as its exact sealed text.
+
+    Its bytes are digest-bound by the manifest already verified, so the only question here is how
+    they are decoded, and ``parse_float=str`` is the whole answer. The sealed members are written
+    with ``pipeline.canonical_json_line_bytes``, which admits non-integer numbers —
+    ``evidence/join.json`` really does carry ``"row_multiplier": 1.0`` — while
+    :func:`canonical.canonical_json_bytes`, the encoder every response goes out through, raises on
+    any float. Decoding such a value into a binary float and re-rendering it would be a second
+    wording of a sealed fact and would make the response unencodable besides. Taking the sealed
+    TEXT instead means the number a caller reads is the number the seal covers, character for
+    character, and no float ever exists on this path to be rounded.
+    """
+
+    try:
+        return json.loads(members[path], parse_float=str)
+    except (KeyError, UnicodeError, json.JSONDecodeError) as error:
+        raise ServingRefused(
+            f"{_named(entry)} does not describe its own shape, so it was not served "
+            "[SERVING_VERSION_SHAPE]"
+        ) from error
+
+
+def _sealed_json(members: Mapping[str, bytes], path: str, entry: IndexedVersion) -> Any:
+    """Read one sealed JSON member that must be an object."""
+
+    value = _sealed_document(members, path, entry)
+    if not isinstance(value, dict):
+        raise ServingRefused(
+            f"{_named(entry)} does not describe its own shape, so it was not served "
+            "[SERVING_VERSION_SHAPE]"
+        )
+    return value
+
+
+def _disagreement(entry: IndexedVersion, field: str, stated: object, sealed: object) -> str:
+    """One sentence for one corroboration failure, naming BOTH values in that order.
+
+    The index's value comes first because an operator reading this is holding the index file open.
+    """
+
+    return (
+        f"the version index says the {field} of {_named(entry)} is {stated}, and the sealed files "
+        f"say it is {sealed}, so nothing was served [SERVING_INDEX_DISAGREES]"
+    )
+
+
+def open_sealed_version(index: VersionIndex, dataset_id: str, pin: str) -> SealedVersion:
+    """Open one reviewed sealed version from one retained replay-verified snapshot."""
+
+    entry = resolve_pin(index, dataset_id, pin)
+    with _open_sealed_version_snapshot(index, entry, pin) as (version, _snapshot):
+        return version
+
+
+@contextmanager
+def _open_sealed_version_snapshot(
+    index: VersionIndex,
+    entry: IndexedVersion,
+    pin: str,
+) -> Iterator[tuple[SealedVersion, pipeline.VerifiedSnapshot]]:
+    """Keep the verified snapshot leased for consumers that need its lazy Parquet handle."""
+
+    previous_run_dir = _predecessor_run_dir(index, entry)
+    try:
+        with pipeline.open_verified_snapshot(entry.run_dir) as verified_snapshot:
+            version = _open_sealed_version_from_snapshot(
+                entry,
+                pin,
+                previous_run_dir=previous_run_dir,
+                verified_snapshot=verified_snapshot,
+            )
+            yield version, verified_snapshot
+    except (
+        recipe.RecipeError,
+        pipeline.BuildError,
+        canonical.CanonicalJSONError,
+        OSError,
+    ) as error:
+        raise ServingRefused(_refusal_for(error, entry)) from error
+
+
+def _open_sealed_version_from_snapshot(
+    entry: IndexedVersion,
+    pin: str,
+    *,
+    previous_run_dir: Path | None,
+    verified_snapshot: pipeline.VerifiedSnapshot,
+) -> SealedVersion:
+    """Open one reviewed, sealed version. The only way into a version's bytes.
+
+    The order below is the contract, not an implementation detail:
+
+    1. **Resolve the pin once.** The entry is bound, and everything after is derived from the bound
+       entry — the pointer is never re-read inside one request. The failure this prevents is a
+       refresh landing between the digest stamp and the rows.
+    2. **Verify.** :func:`recipe.verify_recipe_candidate` over the bound directory, with the
+       predecessor taken from the index entry and ``None`` for an initial build. Every typed failure
+       is translated into a plain sentence; none is passed through.
+    3. **Require the build to have passed its own checks.** ``drift_report.status == "passed"``, the
+       same condition ``deploy.build_deployment_request`` applies. A sealed build that drifted is an
+       unreviewed draft and is refused with its finding codes named.
+    4. **Corroborate within the retained observation.** Compare the candidate digest derived by
+       recipe inspection with the replay-verified identity carried by the same
+       :class:`pipeline.VerifiedSnapshot`, then revalidate that snapshot's retained descriptors.
+       There is no pathname reopen and no second tree observation on this path; disagreement means
+       two derivations from the one leased snapshot failed to describe the same candidate, while a
+       lease validation failure means its namespace changed during the operation.
+    5. **Corroborate the index against the sealed execution record.** Dataset id, version id,
+       version number and digest must all agree, and any disagreement refuses naming both values.
+       The check exists because the index is a convenience whose corruption must not be able to
+       cause a wrong or unsealed serve — so it is checked against the thing it describes rather than
+       believed. Without this step, an index entry pointing one version id at another version's
+       directory would serve the wrong bytes under the right name, and every digest in the response
+       would agree with itself.
+    6. **Read the shape from the sealed tree only** — never from the recipe.
+
+    No parameter bypasses these checks. A signature test enforces that interface.
+
+    Raises:
+        ServingRefused: when the pin names nothing, when the directory holds no reviewed sealed
+            build, when the build did not pass its own checks, when its predecessor is not named,
+            when the retained snapshot lease detects a namespace change, when the snapshot's
+            derived identities disagree, or when the index disagrees with the sealed record.
+    """
+
+    try:
+        inspection, embedded = recipe.verify_recipe_candidate(
+            entry.run_dir,
+            # Always passed explicitly: this module's boundary is where the default lives, so the
+            # verifier's own required keyword is never silently omitted.
+            previous_run_dir=previous_run_dir,
+            _snapshot=verified_snapshot,
+        )
+    except (
+        recipe.RecipeError,
+        pipeline.BuildError,
+        canonical.CanonicalJSONError,
+        OSError,
+    ) as error:
+        raise ServingRefused(_refusal_for(error, entry)) from error
+
+    drift_report = embedded["drift_report"]
+    if drift_report.status != "passed":
+        # Release eligibility is what ``mr-data recipe-verify`` reports, and a build that failed its
+        # own checks is not a version to serve. Each code is bracketed separately so the whole
+        # sentence still reads as prose plus machine handles.
+        codes = " ".join(
+            f"[{code}]" for code in sorted({item.code for item in drift_report.findings})
+        )
+        raise ServingRefused(
+            f"{_named(entry)} did not pass its own checks, so it is not a version to serve: "
+            f"{codes or '[REPAIR_REQUIRED]'}"
+        )
+
+    verified = verified_snapshot.verified
+    members = verified_snapshot.members
+    verified_snapshot.validate()
+    if verified.candidate_digest != inspection.candidate_digest:
+        raise ServingRefused(
+            f"the sealed files behind {_named(entry)} changed while they were being read, so "
+            "nothing was served [SERVING_TREE_MOVED]"
+        )
+
+    execution = embedded["execution"]
+    if execution.table_id != entry.dataset_id:
+        raise ServingRefused(_disagreement(entry, "table", entry.dataset_id, execution.table_id))
+    if execution.table_version_id != entry.version_id:
+        raise ServingRefused(
+            _disagreement(entry, "table version id", entry.version_id, execution.table_version_id)
+        )
+    if execution.table_version_number != entry.version_number:
+        raise ServingRefused(
+            _disagreement(
+                entry, "table version number", entry.version_number, execution.table_version_number
+            )
+        )
+    if entry.version_digest != verified.candidate_digest:
+        # Named by the WIRE name, because whoever reads this sentence is holding the index file
+        # open and the key they are looking at is spelled version_digest.
+        raise ServingRefused(
+            _disagreement(entry, "version digest", entry.version_digest, verified.candidate_digest)
+        )
+
+    profile = _sealed_json(members, "evidence/profile.json", entry)
+    plan = _sealed_json(members, "plan.json", entry)
+    sources = _sealed_document(members, "evidence/sources.json", entry)
+    join = _sealed_json(members, "evidence/join.json", entry)
+    quality = _sealed_json(members, "evidence/quality.json", entry)
+    lineage = _sealed_json(members, "evidence/lineage.json", entry)
+    if not isinstance(sources, list):
+        raise ServingRefused(
+            f"{_named(entry)} does not describe its own shape, so it was not served "
+            "[SERVING_VERSION_SHAPE]"
+        )
+    try:
+        # Checked here rather than where the card is served, so every "can this version be
+        # answered from" question is settled in one place and a shape that renders the card cannot
+        # raise where it is supposed to refuse.
+        members["table_card.md"].decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ServingRefused(
+            f"{_named(entry)} does not describe its own shape, so it was not served "
+            "[SERVING_VERSION_SHAPE]"
+        ) from error
+    columns = profile.get("columns")
+    types = profile.get("types")
+    row_count = profile.get("row_count")
+    grain = plan.get("grain")
+    question = plan.get("question")
+    if (
+        not isinstance(columns, list)
+        or not all(isinstance(item, str) for item in columns)
+        or not isinstance(types, dict)
+        or set(types) != set(columns)
+        or type(row_count) is not int
+        or not isinstance(grain, list)
+        or not all(isinstance(item, str) for item in grain)
+        or not is_single_plain_line(question)
+    ):
+        raise ServingRefused(
+            f"{_named(entry)} does not describe its own shape, so it was not served "
+            "[SERVING_VERSION_SHAPE]"
+        )
+
+    return SealedVersion(
+        dataset_id=execution.table_id,
+        version_id=execution.table_version_id,
+        version_number=execution.table_version_number,
+        candidate_digest=verified.candidate_digest,
+        table_sha256=verified.table_sha256,
+        columns=tuple(columns),
+        column_types=tuple(sorted((str(key), str(value)) for key, value in types.items())),
+        grain=tuple(grain),
+        row_count=row_count,
+        question=question,
+        table_card=members["table_card.md"],
+        pin_kind=PIN_CURRENT if pin == PIN_CURRENT else "pinned",
+        sources=tuple(sources),
+        join=join,
+        quality=quality,
+        lineage=lineage,
+    )
+
+
+@dataclass(frozen=True)
+class ServingResult:
+    """The verdict on one serving read: what was served, or the reasons nothing was.
+
+    Invariant: ``ok`` is true if and only if ``refusals`` is empty and ``payload`` is not None.
+    Only two shapes exist, exactly as in :class:`deploy.GoLiveResult`. A refusing result never
+    hands back a payload, because a payload in hand is the thing a caller reads.
+
+    The bound version's identity and digests are optional and are present on **every answering
+    shape**. They are also present on a refusal that got far enough to bind a version, and null on
+    one that did not — a refusal before resolution has no version to name, and inventing one would
+    be worse than saying nothing. ``table_digest`` stays null on every refusal in this plan: the
+    table's digest is a sealed fact that only opening the version produces, and a refusal never
+    opened it. On a refusal ``version_digest`` is the digest the read was FOR, as the version index
+    states it; it is not a claim that anything was verified, and ``ok`` is false beside it.
+
+    ``payload`` holds whatever the answering shape answered with. The envelope does not know or
+    care which shape that was. The answering/refusing invariant belongs to this class rather than
+    to individual handlers, so it cannot hold for three shapes and fail for the fourth.
+    """
+
+    ok: bool
+    refusals: tuple[str, ...]
+    status: str
+    dataset_id: str
+    pin: str
+    pin_kind: str | None
+    version_id: str | None
+    version_number: int | None
+    version_digest: str | None
+    table_digest: str | None
+    payload: Mapping[str, Any] | None
+    # V3 Dataset/Table responses carry the child identity independently. Historical local reads
+    # retain their original table-only envelope and leave this absent.
+    table_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if type(self.ok) is not bool:
+            raise ServingRefused("ok must be a boolean verdict")
+        if type(self.refusals) is not tuple or any(
+            type(item) is not str or not item.strip() for item in self.refusals
+        ):
+            raise ServingRefused("refusals must be a tuple of named reasons")
+        if not isinstance(self.status, str) or _STATUS.fullmatch(self.status) is None:
+            raise ServingRefused("a serving result always carries one plain status word")
+        for name in ("dataset_id", "pin"):
+            if not isinstance(getattr(self, name), str):
+                raise ServingRefused(
+                    "a serving result records the dataset and pin it was asked for"
+                )
+        if self.table_id is not None and not isinstance(self.table_id, str):
+            raise ServingRefused("a V3 serving result records a Table identifier as text")
+        if self.pin_kind is not None and self.pin_kind not in {PIN_CURRENT, "pinned"}:
+            raise ServingRefused("a bound version was asked for as current or as a pin")
+        if self.version_number is not None and (
+            type(self.version_number) is not int or self.version_number < 1
+        ):
+            raise ServingRefused("a bound version number is a whole number of at least 1")
+        for name in ("version_digest", "table_digest"):
+            value = getattr(self, name)
+            if value is not None and (
+                not isinstance(value, str) or _DIGEST.fullmatch(value) is None
+            ):
+                raise ServingRefused("a digest is 64 lowercase hex characters or nothing at all")
+        if self.payload is not None and not isinstance(self.payload, Mapping):
+            raise ServingRefused("a payload is a mapping of named facts or nothing")
+        if self.refusals and self.payload is not None:
+            raise ServingRefused("a refused read never hands back a payload")
+        clean = not self.refusals and self.payload is not None
+        if self.ok is not clean:
+            raise ServingRefused(
+                "a read is ok only when there are no refusals and something was answered"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the one fact set both renderings are built from.
+
+        Every human line and every JSON field this product prints for a serving read comes from
+        here, so the two cannot report different things.
+
+        This function maps engineering field names to the customer response fields:
+
+        ==================  ==========================================
+        Wire name emitted   Engineering name it is read from
+        ==================  ==========================================
+        ``version_digest``  :attr:`SealedVersion.candidate_digest`
+        ``table_digest``  :attr:`SealedVersion.table_sha256`
+        ==================  ==========================================
+
+        A JSON key a production caller parses is the most user-visible string this surface emits,
+        and ``docs/VOCABULARY.md`` records "sealed candidate" as superseded by "Draft / Build" — so
+        a field called ``candidate_digest`` would satisfy the digest-on-every-response gate by
+        breaking the plain-vocabulary one. The rename happens here, in one function.
+        ``pipeline.VerifiedCandidate`` and :class:`SealedVersion` keep their own names, because the
+        engineering vocabulary is correct where the engineering lives.
+
+        ``table_digest`` is renamed from ``table_sha256`` for a WEAKER reason, and the weaker
+        reason is stated as weaker: "sha256" is not superseded by anything, and the rename exists so
+        the pair does not read as one digest and one algorithm. The cost is real — ``mr-data build``
+        emits ``table_sha256`` in its own JSON — and it is paid off by publishing the table above
+        in ``docs/SERVING.md``, so a caller cross-referencing the two can see the correspondence
+        rather than guess it. Without that published mapping a later reader "fixes" the
+        inconsistency in one direction or the other, and one of the two gates rots.
+
+        **What is deliberately absent.** A response carries no served-at time, no request
+        identifier, no key id, no host, no port and no filesystem path. Each of the first three
+        would, alone, make a pinned read impossible to keep byte-identical — the gate says the same
+        pinned request encodes to the same bytes forever, and one clock in the payload ends that in
+        one line. The last three would leak the deployment's internals to a caller who asked about
+        data. This is said here, in the module, and not only in a test, because a later reader will
+        otherwise add a served-at timestamp as an obvious improvement.
+
+        Every number this envelope carries is a whole number or text.
+        :func:`canonical.canonical_json_bytes` raises on any non-integer number, so a float
+        anywhere in a payload would not be a rendering wart — it would be a response that cannot be
+        encoded at all.
+        """
+
+        result = {
+            "schema_version": SERVING_RESULT_SCHEMA,
+            "status": self.status,
+            "ok": self.ok,
+            "refusals": list(self.refusals),
+            "dataset_id": self.dataset_id,
+            "pin": self.pin,
+            "pin_kind": self.pin_kind,
+            "version_id": self.version_id,
+            "version_number": self.version_number,
+            "version_digest": self.version_digest,
+            "table_digest": self.table_digest,
+            "payload": None if self.payload is None else dict(self.payload),
+        }
+        if self.table_id is not None:
+            result["table_id"] = self.table_id
+        return result
+
+    def canonical_bytes(self) -> bytes:
+        """Return the response body: canonical bytes over :meth:`to_dict`.
+
+        Identical facts are identical bytes, because nothing time-varying, request-varying or
+        caller-varying is in the fact set. This is the function every transport should encode
+        through, so no shape can invent a second serialization that only mostly agrees.
+        """
+
+        return canonical.canonical_json_bytes(self.to_dict())
+
+    def digest(self) -> str:
+        """Return the content digest of this response, in ``DeploymentRequest.digest``'s shape."""
+
+        return canonical.canonical_sha256(self.to_dict())
+
+
+def serving_lines(result: ServingResult) -> list[str]:
+    """Render one serving result as plain lines, from the same facts the JSON body carries.
+
+    Both renderings read :meth:`ServingResult.to_dict`, so human and JSON output use the same data.
+
+    Only facts the envelope actually carries are rendered, so a shape whose payload does not hold a
+    given fact simply prints one line fewer. No line is composed from anything outside ``to_dict``.
+    """
+
+    body = result.to_dict()
+    lines = [
+        f"dataset: {body['dataset_id']}",
+        f"version asked for: {body['pin']}",
+    ]
+    if body["version_id"] is not None:
+        lines.append(f"version: {body['version_id']}")
+    if body["version_number"] is not None:
+        lines.append(f"version number: {body['version_number']}")
+    if body["pin_kind"] is not None:
+        lines.append(f"pin kind: {body['pin_kind']}")
+    if body["version_digest"] is not None:
+        lines.append(f"version checksum: {body['version_digest']}")
+    if body["table_digest"] is not None:
+        lines.append(f"table checksum: {body['table_digest']}")
+    if not body["ok"]:
+        lines.append("this read was refused")
+        lines.extend(body["refusals"])
+        return lines
+
+    lines.append(f"status: {body['status']}")
+    payload = body["payload"] or {}
+    if "question" in payload:
+        question = payload["question"]
+        if isinstance(question, str) and not is_single_plain_line(question):
+            question = question.translate(_DISPLAY_LINE_BOUNDARY_ESCAPES)
+        lines.append(f"question: {question}")
+    if "columns" in payload:
+        lines.append("columns: " + ", ".join(payload["columns"]))
+    if "column_types" in payload:
+        lines.append(
+            "column types: "
+            + ", ".join(f"{name}={kind}" for name, kind in sorted(payload["column_types"].items()))
+        )
+    if "grain" in payload:
+        lines.append("grain: " + ", ".join(payload["grain"]))
+    if "row_count" in payload:
+        lines.append(f"rows: {payload['row_count']}")
+    # The rows shape's own counts. Each line is guarded on its key, in the same block, so a shape
+    # whose payload does not hold a fact prints one line fewer rather than needing its own renderer.
+    # The rows THEMSELVES are not rendered here: a table is a display decision, and the command that
+    # owns the human surface owns it.
+    for key, label in (
+        ("total_row_count", "rows in this version"),
+        ("matched_row_count", "rows matching this filter"),
+        ("offset", "offset"),
+        ("limit", "limit"),
+        ("truncated", "truncated"),
+    ):
+        if key in payload:
+            lines.append(f"{label}: {payload[key]}")
+    return lines
+
+
+def _asked_for(value: Any, limit: int) -> str:
+    """Echo what the caller asked for, as text, and only when it is one plain line.
+
+    A dataset id or a pin that is not text is itself a refusal, and the refusal has already been
+    raised by the time this runs; the coercion exists so the envelope reporting that refusal can
+    still be built rather than raising a second, less useful error on top of the first.
+
+    The same is true one step further out, and is the reason this is not a bare ``isinstance``: a
+    value that failed :func:`_one_plain_line` is precisely the value that must not be repeated into
+    a response, because the envelope's ``dataset_id`` and ``pin`` fields are rendered by
+    :func:`serving_lines` beside the digests. An unrenderable ask is echoed as nothing; the
+    refusals beside it already say what was wrong with it.
+    """
+
+    return value if _one_plain_line(value, limit) else ""
+
+
+def _refused_result(
+    dataset_id: Any,
+    pin: Any,
+    refusal: ServingRefused,
+    entry: IndexedVersion | None,
+) -> ServingResult:
+    """Turn one raised refusal into the one shape every caller of this module renders.
+
+    ``entry`` is the version the pin bound, or nothing when the refusal happened before a pin could
+    resolve. When a version was bound, the envelope carries its identity and the digest the index
+    states for it — the digest the read was FOR — so a caller can tell which version was declined.
+    ``table_digest`` stays null: the table's digest is a sealed fact that only opening the version
+    produces, and this read did not open one. Nothing here is a claim that anything verified; ``ok``
+    is false and ``refusals`` says why.
+    """
+
+    return ServingResult(
+        ok=False,
+        refusals=refusal.reasons,
+        status=STATUS_REFUSED,
+        dataset_id=_asked_for(dataset_id, MAX_DATASET_ID_CHARS),
+        pin=_asked_for(pin, MAX_PIN_CHARS),
+        pin_kind=None if entry is None else (PIN_CURRENT if pin == PIN_CURRENT else "pinned"),
+        version_id=None if entry is None else entry.version_id,
+        version_number=None if entry is None else entry.version_number,
+        version_digest=None if entry is None else entry.version_digest,
+        table_digest=None,
+        payload=None,
+    )
+
+
+def describe_dataset(index: VersionIndex, dataset_id: str, pin: str) -> ServingResult:
+    """Answer "what is this dataset" for one version: its sealed card, its schema, its evidence.
+
+    Everything answered here comes from one :func:`open_sealed_version` call and nothing else. If a
+    fact belongs in a response and is not on :class:`SealedVersion`, it goes on
+    :class:`SealedVersion` — not into a second read of the run directory from here. A second read
+    is a second observation, and the single opening is what makes the digest this response carries
+    the digest these bytes came from.
+
+    **The table card is served verbatim, and that is a decision rather than an oversight.** The
+    card's bytes are digest-bound evidence: ``pipeline._table_card`` writes them, the manifest
+    covers them, and the version digest is over the whole tree that includes them. Paraphrasing
+    them here would create a second wording of a sealed fact, and rewriting them at the source
+    would change every version digest and break every golden. So the bytes go out decoded as UTF-8
+    and otherwise untouched.
+
+        The card is returned verbatim because it is part of the version digest. The response field
+        remains ``table_card``.
+
+    A refusal is an expected outcome of a data read — an unreviewed build, a corrupted index, a pin
+    naming nothing — so :class:`ServingRefused` is caught here and returned as a refusing
+    :class:`ServingResult`. It is never allowed to propagate, for the reason ``deploy.plan_go_live``
+    established: every caller of this surface should have exactly one shape to render.
+    """
+
+    entry: IndexedVersion | None = None
+    try:
+        # Resolved here as well as inside the door, so a refusal can say which version was
+        # declined. This is not a second read of a pointer: ``index`` is an already-parsed
+        # immutable value, so both resolutions read the same document and cannot disagree.
+        entry = resolve_pin(index, dataset_id, pin)
+        version = open_sealed_version(index, dataset_id, pin)
+    except ServingRefused as refusal:
+        return _refused_result(dataset_id, pin, refusal, entry)
+
+    # Plain names, all of them. P-01's ban on a superseded word covers the payload as well as the
+    # envelope, because a caller parses both out of one body.
+    payload: dict[str, Any] = {
+        "table_card": version.table_card.decode("utf-8"),
+        "columns": list(version.columns),
+        "column_types": dict(version.column_types),
+        "grain": list(version.grain),
+        "row_count": version.row_count,
+        "question": version.question,
+        "sources": list(version.sources),
+        "join": dict(version.join),
+        "quality": dict(version.quality),
+        "lineage": dict(version.lineage),
+    }
+    return ServingResult(
+        ok=True,
+        refusals=(),
+        status=STATUS_DATASET_DESCRIBED,
+        dataset_id=version.dataset_id,
+        pin=pin,
+        pin_kind=version.pin_kind,
+        version_id=version.version_id,
+        version_number=version.version_number,
+        version_digest=version.candidate_digest,
+        table_digest=version.table_sha256,
+        payload=payload,
+    )
+
+
+# ---------------------------------------------------------------------------
+# The filter: a closed structured predicate, never an expression
+# ---------------------------------------------------------------------------
+
+# Filters are structured data, never executable expressions. The source-level safety test scans
+# this module for prohibited execution and dynamic-import tokens.
+#
+# So a filter is a list of ``{column, op, value}``. The column must be a member of the sealed
+# schema, the operator comes from the closed frozen set below, and the value is validated against
+# that column's logical type as the sealed profile records it. Combination is AND-only, and that is
+# a stated scope boundary rather than an oversight: OR and grouping are a COMBINATION GRAMMAR, and
+# a grammar is the thing that grows into an expression language. A caller that needs OR issues two
+# reads.
+
+#: A filter names at most this many conditions. The number is small on purpose: every condition is
+#: a full pass over a sealed column, and a legitimate caller narrowing to a grain needs as many
+#: conditions as the grain has parts, not dozens.
+MAX_PREDICATES = 16
+
+#: The longest value list an ``in`` may carry. Sixteen conditions of sixty-four values each is the
+#: worst case a single request can ask this surface to evaluate, and it is bounded on purpose.
+MAX_IN_VALUES = 64
+
+#: The longest text a filter value may be. A sealed cell may legitimately be far longer, so this
+#: bounds the REQUEST rather than the data: nothing a caller sends needs to be a kilobyte to match
+#: a key, and an unbounded value is free work asked of a shared surface.
+MAX_FILTER_VALUE_CHARS = 1_024
+
+# **The row ceiling, and why it is this number.**
+#
+# ``canonical.MAX_CANONICAL_MEMBERS = 100_000`` is the hard ceiling, and it counts VALUE NODES: one
+# row contributes its own object plus one member per column, so a row costs ``columns + 1``. At
+# ``pipeline.MAX_COLUMNS = 256`` that is 257 members per row, and the whole payload must also carry
+# the envelope. 250 rows therefore costs 250 * 257 = 64,250 members at the widest dataset this
+# product will build — about a third of the ceiling left as headroom, so a wide dataset is bounded
+# by this constant rather than by an encoder error.
+#
+# It is deliberately NOT ``hosted_worker.MAX_TABLE_PREVIEW_ROWS = 200``. That is a PREVIEW bound —
+# how much of a build a reviewer is shown — and reusing it here would tie a customer's page size to
+# an internal review affordance, so that moving one would silently move the other. 250 is a page a
+# production caller can work with: four reads to a thousand rows, with a stable offset.
+#
+# ``pipeline.MAX_ROWS = 100_000`` is what a whole dataset may hold, and it exceeds
+# ``MAX_CANONICAL_MEMBERS`` on its own at any width. That arithmetic is the reason a bounded window
+# with an explicit truncation flag is the only shape that can work here at all.
+MAX_SERVED_ROWS = 250
+
+#: The byte budget one rows response is fitted to, in ``hosted_worker.MAX_TABLE_PREVIEW_BYTES``'s
+#: shape. A row count alone does not bound bytes — 250 rows of kilobyte strings is megabytes — so
+#: both bounds are applied and the byte one shrinks the window by whole rows.
+MAX_SERVED_BYTES = 4 * 1024 * 1024
+
+#: The status word an answered rows read carries.
+STATUS_ROWS_SERVED = "rows_served"
+
+
+def _is_in(column: Any, value: Any) -> Any:
+    return pc.is_in(column, value_set=value)
+
+
+def _is_null(column: Any, value: Any) -> Any:
+    return pc.is_null(column)
+
+
+def _is_not_null(column: Any, value: Any) -> Any:
+    return pc.is_valid(column)
+
+
+#: The CLOSED operator-to-function map: one operator name, one ``pyarrow.compute`` callable, held as
+#: module-level data. Every operator takes ``(column, value)`` so the apply loop has no branch of
+#: its own, and there is no path anywhere in this module that composes a query string — a reader can
+#: see that at a glance from this table rather than having to trust a claim about it.
+_PREDICATE_FUNCTIONS: dict[str, Callable[[Any, Any], Any]] = {
+    "eq": pc.equal,
+    "ne": pc.not_equal,
+    "lt": pc.less,
+    "le": pc.less_equal,
+    "gt": pc.greater,
+    "ge": pc.greater_equal,
+    "in": _is_in,
+    "is_null": _is_null,
+    "is_not_null": _is_not_null,
+}
+
+#: The operator vocabulary, derived from the function map so the two cannot disagree.
+PREDICATE_OPS = frozenset(_PREDICATE_FUNCTIONS)
+
+#: The two operators that ask about validity rather than about a value.
+_NULL_OPS = frozenset({"is_null", "is_not_null"})
+
+_PREDICATE_KEYS = frozenset({"column", "op"})
+
+#: The sealed logical types this query surface can compare. The build pipeline can also emit
+#: boolean and UTC timestamp columns; keeping those outside this narrower capability set preserves
+#: the existing typed refusal until their serving value syntax is specified independently.
+_SERVED_LOGICAL_TYPES = frozenset({"string", "int64", "float64", "date"})
+
+#: The logical types the recipe/build vocabulary admits but this serving surface cannot filter.
+#: Named rather than folded into "unknown" so the typed refusal remains explicit.
+_UNSERVED_LOGICAL_TYPES = frozenset(recipe.LOGICAL_TYPES) - _SERVED_LOGICAL_TYPES
+
+_WHOLE_NUMBER = re.compile(r"\A-?(0|[1-9][0-9]*)\Z")
+_DECIMAL_NUMBER = re.compile(r"\A-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][-+]?[0-9]+)?\Z")
+_CALENDAR_DATE = re.compile(r"\A\d{4}-\d{2}-\d{2}\Z")
+_MACHINE_CODE = re.compile(r"\A[A-Z][A-Z0-9_]{0,63}\Z")
+
+
+def _parse_string(raw: Any) -> str:
+    if not isinstance(raw, str) or len(raw) > MAX_FILTER_VALUE_CHARS:
+        raise ValueError
+    return raw
+
+
+def _parse_int64(raw: Any) -> int:
+    if type(raw) is bool:
+        raise ValueError
+    if type(raw) is int:
+        value = raw
+    elif isinstance(raw, str) and _WHOLE_NUMBER.fullmatch(raw) is not None:
+        value = int(raw)
+    else:
+        raise ValueError
+    if not -canonical.MAX_CANONICAL_INTEGER - 1 <= value <= canonical.MAX_CANONICAL_INTEGER:
+        raise ValueError
+    return value
+
+
+def _parse_float64(raw: Any) -> float:
+    # Text, and only text. A float64 cell leaves this surface as text — ``rowset.render_cell``
+    # renders it with ``.17g`` because the canonical encoder refuses every non-integer number — so a
+    # filter value spelled as a JSON number would be written in one domain and compared against
+    # another. One spelling in both directions is the whole point of the shared value domain.
+    if not isinstance(raw, str) or _DECIMAL_NUMBER.fullmatch(raw) is None:
+        raise ValueError
+    value = float(raw)
+    if value != value or value in (float("inf"), float("-inf")):  # pragma: no cover - regex-barred
+        raise ValueError
+    return value
+
+
+def _parse_date(raw: Any) -> datetime.date:
+    if not isinstance(raw, str) or _CALENDAR_DATE.fullmatch(raw) is None:
+        raise ValueError
+    return datetime.date.fromisoformat(raw)
+
+
+#: One parser per served logical type. Keyed by exactly ``_SERVED_LOGICAL_TYPES``, asserted by test.
+_VALUE_PARSERS: dict[str, Callable[[Any], Any]] = {
+    "string": _parse_string,
+    "int64": _parse_int64,
+    "float64": _parse_float64,
+    "date": _parse_date,
+}
+
+#: What a value has to look like, per logical type, said in the words a caller would use. Held as
+#: data beside the parsers so a refusal cannot describe one shape while the parser accepts another.
+_VALUE_SHAPES: dict[str, str] = {
+    "string": "text",
+    "int64": "a whole number, written as text or as a number",
+    "float64": "a number written as text",
+    "date": "a calendar date written as text, as 2026-07-15",
+}
+
+
+def _arrived(value: Any) -> str:
+    """Say what KIND of thing arrived, never what it was.
+
+    A refusal sentence is a terminal line. Interpolating a caller-supplied value into one would put
+    caller-controlled text — control characters included — in front of whoever is reading the log,
+    so every refusal below names the column and the expected shape and describes the arrival by its
+    kind alone.
+    """
+
+    if value is None:
+        return "nothing"
+    if type(value) is bool:
+        return "a true or false"
+    if type(value) is int:
+        return "a whole number"
+    if type(value) is float:
+        return "a number"
+    if isinstance(value, str):
+        return "text"
+    if isinstance(value, (list, tuple)):
+        return "a list"
+    if isinstance(value, Mapping):
+        return "an object"
+    return "something this surface does not accept"
+
+
+def _safe_column(value: Any) -> str | None:
+    """Return the column name only when it is safe to print, and nothing when it is not.
+
+    A caller-supplied column name is echoed back so a refusal is actionable, and it is echoed ONLY
+    after it matches ``rowset.COLUMN_NAME`` — the frozen shape a sealed dataset's columns may take.
+    A name outside that shape cannot be a sealed column anyway, so nothing is lost by refusing
+    without repeating it, and a name carrying control characters never reaches a terminal.
+    """
+
+    if isinstance(value, str) and rowset.COLUMN_NAME.fullmatch(value) is not None:
+        return value
+    return None
+
+
+@dataclass(frozen=True)
+class Predicate:
+    """One parsed, typed condition: a sealed column, a closed operator, and a domain value.
+
+    A value of this type exists only on the far side of :func:`parse_predicates`, so anything
+    downstream is holding a column that is in the sealed schema, an operator that is in
+    :data:`PREDICATE_OPS`, and a value already parsed into the column's own logical type. There is
+    no string here to interpret and nothing left to validate.
+
+    ``value`` is ``None`` for ``is_null`` and ``is_not_null``, a tuple for ``in``, and one parsed
+    value otherwise.
+    """
+
+    column: str
+    op: str
+    value: Any
+
+
+def _typed(raw: Any, *, column: str, logical: str) -> Any:
+    try:
+        return _VALUE_PARSERS[logical](raw)
+    except (ValueError, TypeError) as error:
+        raise ServingRefused(
+            f"the filter on column {column} needs {_VALUE_SHAPES[logical]}, because that column "
+            f"holds {logical}, and {_arrived(raw)} arrived instead [SERVING_FILTER_VALUE]"
+        ) from error
+
+
+def _predicate(
+    raw: Any,
+    *,
+    column_types: Mapping[str, str],
+    seen: set[tuple[str, str]],
+) -> Predicate:
+    if not isinstance(raw, Mapping):
+        raise ServingRefused(
+            "a filter is a list of conditions, each written as an object naming a column, an "
+            "operator and a value [SERVING_FILTER_SHAPE]"
+        )
+    op = raw.get("op")
+    if not isinstance(op, str) or op not in PREDICATE_OPS:
+        raise ServingRefused(
+            "a filter condition uses one of these operators: "
+            + ", ".join(sorted(PREDICATE_OPS))
+            + " [SERVING_FILTER_OP]"
+        )
+    column = _safe_column(raw.get("column"))
+    if column is None:
+        raise ServingRefused(
+            "a filter condition names its column as a name of up to 128 letters, digits, dots, "
+            "dashes, colons or underscores [SERVING_FILTER_COLUMN]"
+        )
+    if column not in column_types:
+        raise ServingRefused(
+            f"this dataset has no column called {column}, so it cannot be filtered on "
+            "[SERVING_FILTER_COLUMN]"
+        )
+
+    unknown = sorted(set(raw) - _PREDICATE_KEYS - {"value"})
+    if unknown:
+        raise ServingRefused(
+            f"the filter condition on column {column} names fields this surface does not know: "
+            + ", ".join(
+                sorted(_safe_column(item) or "one that cannot be printed" for item in unknown)
+            )
+            + " [SERVING_FILTER_SHAPE]"
+        )
+    if op in _NULL_OPS:
+        if "value" in raw:
+            raise ServingRefused(
+                f"the {op} filter on column {column} asks whether a cell is empty, so it takes no "
+                "value to compare against [SERVING_FILTER_VALUE]"
+            )
+    elif "value" not in raw:
+        raise ServingRefused(
+            f"the {op} filter on column {column} needs a value to compare against "
+            "[SERVING_FILTER_VALUE]"
+        )
+
+    logical = column_types[column]
+    if logical not in _VALUE_PARSERS:
+        if logical in _UNSERVED_LOGICAL_TYPES:
+            raise ServingRefused(
+                f"column {column} holds {logical}, which this surface cannot filter on yet "
+                "[SERVING_FILTER_TYPE]"
+            )
+        raise ServingRefused(
+            f"column {column} holds a kind of value this surface cannot filter on "
+            "[SERVING_FILTER_TYPE]"
+        )
+
+    pair = (column, op)
+    if pair in seen:
+        raise ServingRefused(
+            f"the filter names the {op} condition on column {column} more than once, so it does "
+            "not say which one to apply [SERVING_FILTER_DUPLICATE]"
+        )
+    seen.add(pair)
+
+    if op in _NULL_OPS:
+        return Predicate(column=column, op=op, value=None)
+    supplied = raw["value"]
+    if op == "in":
+        if not isinstance(supplied, (list, tuple)) or not supplied:
+            raise ServingRefused(
+                f"the in filter on column {column} needs a non-empty list of values to match "
+                "[SERVING_FILTER_VALUE]"
+            )
+        if len(supplied) > MAX_IN_VALUES:
+            raise ServingRefused(
+                f"the in filter on column {column} lists more than {MAX_IN_VALUES} values "
+                "[SERVING_FILTER_BOUNDS]"
+            )
+        return Predicate(
+            column=column,
+            op=op,
+            value=tuple(_typed(item, column=column, logical=logical) for item in supplied),
+        )
+    return Predicate(column=column, op=op, value=_typed(supplied, column=column, logical=logical))
+
+
+def parse_predicates(raw: Any, *, column_types: Mapping[str, str]) -> tuple[Predicate, ...]:
+    """Read a caller's filter as DATA, and refuse everything that is not exactly that.
+
+    ``column_types`` is the sealed schema's own logical types, as ``evidence/profile.json`` records
+    them and :attr:`SealedVersion.column_types` carries them. Every column a filter names has to be
+    a member of it, and every value is parsed into that column's logical type before anything
+    touches a byte of the table. Types outside this serving surface's narrower parser set are
+    refused by name rather than let through untyped, even when the sealed build can carry them.
+
+    Nothing here builds, accepts or evaluates an expression string. Combination is AND-only.
+
+    Raises:
+        ServingRefused: when the filter is not a list of objects, when it names too many
+            conditions, when an operator is outside :data:`PREDICATE_OPS`, when a column is not in
+            the sealed schema, when a value is not the column's logical type, when a value is
+            supplied for a validity test or left off a comparison, when an ``in`` list is empty or
+            too long, or when one column-operator pair is named twice.
+    """
+
+    if raw is None:
+        return ()
+    if isinstance(raw, (str, bytes)) or not isinstance(raw, Sequence):
+        raise ServingRefused(
+            "a filter is a list of conditions, each written as an object naming a column, an "
+            "operator and a value [SERVING_FILTER_SHAPE]"
+        )
+    if len(raw) > MAX_PREDICATES:
+        raise ServingRefused(
+            f"a filter names at most {MAX_PREDICATES} conditions [SERVING_FILTER_BOUNDS]"
+        )
+    seen: set[tuple[str, str]] = set()
+    return tuple(_predicate(item, column_types=column_types, seen=seen) for item in raw)
+
+
+# ---------------------------------------------------------------------------
+# The window: bounded, deterministic rows
+# ---------------------------------------------------------------------------
+
+#: One plain sentence per ``rowset.RowsetError`` code, held as module DATA so a new code cannot
+#: arrive without a sentence to answer it with.
+#:
+#: Translate internal rowset errors to serving terminology while preserving their codes.
+_ROWSET_REFUSALS: dict[str, str] = {
+    rowset.ROWS_INVALID: (
+        "the sealed table of {named} could not be read as rows within this surface's limits"
+    ),
+}
+
+
+def _rowset_refusal(error: rowset.RowsetError, entry: IndexedVersion) -> str:
+    """Turn one shared-value-domain failure into one plain sentence, in ``_refusal_for``'s shape."""
+
+    sentence = _ROWSET_REFUSALS.get(error.code)
+    code = error.code if _MACHINE_CODE.fullmatch(str(error.code)) else "SERVING_ROWS"
+    if sentence is None:
+        sentence = "the sealed table of {named} could not be read as rows"
+    return f"{sentence.format(named=_named(entry))} [{code}]"
+
+
+def _window(offset: Any, limit: Any) -> tuple[int, int]:
+    """Validate the window, and refuse anything that could ask for an unbounded payload."""
+
+    for name, value in (("offset", offset), ("limit", limit)):
+        if type(value) is not int or value < 0:
+            raise ServingRefused(
+                f"a read's {name} is a whole number of at least 0 [SERVING_WINDOW]"
+            )
+    if limit < 1:
+        raise ServingRefused("a read asks for at least one row [SERVING_WINDOW]")
+    if limit > MAX_SERVED_ROWS:
+        raise ServingRefused(
+            f"a read returns at most {MAX_SERVED_ROWS} rows at a time, so ask for that many and "
+            "page with the offset [SERVING_WINDOW]"
+        )
+    return offset, limit
+
+
+def _arrow_value(column: Any, predicate: Predicate) -> Any:
+    """Turn one typed predicate value into an Arrow value of the column's own type.
+
+    Built against the SEALED column's Arrow type rather than inferred, so a value that cannot be
+    represented in that column's domain is a refusal rather than a silent widening.
+    """
+
+    if predicate.op in _NULL_OPS:
+        return None
+    try:
+        if predicate.op == "in":
+            return pa.array(list(predicate.value), type=column.type)
+        return pa.scalar(predicate.value, type=column.type)
+    except (pa.ArrowInvalid, pa.ArrowTypeError, OverflowError, ValueError) as error:
+        raise ServingRefused(
+            f"the filter on column {predicate.column} asks for a value that column cannot hold "
+            "[SERVING_FILTER_VALUE]"
+        ) from error
+
+
+def _select_rows(table: pa.Table, predicates: Sequence[Predicate]) -> pa.Table:
+    """Apply every predicate to the sealed table and return the rows that match all of them.
+
+    Selection happens HERE, on Arrow, before anything is rendered: a filtered read must not
+    materialize the whole dataset in the response value domain to then throw most of it away.
+
+    The operator reaches its ``pyarrow.compute`` function through :data:`_PREDICATE_FUNCTIONS`, a
+    closed table of callables. There is no branch here that composes a string, and there is nothing
+    for one to be composed from — the predicate is already typed data.
+
+    A cell that is null compares as null, so a null never matches ``eq`` and is dropped by the
+    filter. ``is_null`` and ``is_not_null`` ask about VALIDITY instead, which is why they exist:
+    there is no sentinel value that means "empty" in this domain.
+    """
+
+    if not predicates:
+        return table
+    mask = None
+    for predicate in predicates:
+        column = table.column(predicate.column)
+        function = _PREDICATE_FUNCTIONS[predicate.op]
+        one = function(column, _arrow_value(column, predicate))
+        mask = one if mask is None else pc.and_(mask, one)
+    return table.filter(mask)
+
+
+def serve_rows(
+    index: VersionIndex,
+    dataset_id: str,
+    pin: str,
+    *,
+    predicates: Any = None,
+    offset: int = 0,
+    limit: int = MAX_SERVED_ROWS,
+    max_bytes: int | None = None,
+) -> ServingResult:
+    """Answer "give me these rows" for one version: a bounded, deterministic, filtered window.
+
+    A point lookup is not a second shape. It is this function with an equality condition on every
+    column of the sealed grain, and the answer is at most one row. An absent key returns an empty
+    row list with ``ok`` true — an empty answer is an answer, not a refusal.
+
+    The order is the contract:
+
+    1. Open the sealed version through :func:`open_sealed_version` and retain
+       its verified Parquet descriptor for bounded batch reads. The run directory is never opened
+       again from here, because a second observation could read different bytes.
+    2. **Parse the filter as data** against that version's own sealed schema.
+    3. **Select on Arrow**, through the closed operator table, before anything is rendered.
+    4. **Take the window** with ``offset`` and ``limit`` on the FILTERED order, so paging is stable.
+    5. **Render and fit** through the one shared value domain and the one byte-budget loop.
+
+    **Sealed file order is the ordering, and there is no ORDER BY.** The reason there is no ORDER BY
+    is that the sealed order already is one: the bytes are sealed and digest-bound, so row 7 of a
+    version is row 7 of that version forever, and two adjacent windows concatenate to the wider one.
+    A sort clause would be a second ordering that has to agree with the first.
+
+    ``max_bytes`` may only TIGHTEN the byte budget: it is clamped to :data:`MAX_SERVED_BYTES`, so no
+    caller can use it to ask for a larger payload than this surface's own bound. It exists so the
+    fit loop can be exercised on a small dataset without faking the condition by reaching into the
+    module.
+
+    Returns:
+        A :class:`ServingResult` — answering with ``status`` :data:`STATUS_ROWS_SERVED`, or refusing
+        with every reason named. A refusal is an expected outcome of a data read and is never raised
+        out of here, for the reason ``deploy.plan_go_live`` established.
+    """
+
+    entry: IndexedVersion | None = None
+    try:
+        entry = resolve_pin(index, dataset_id, pin)
+        window_offset, window_limit = _window(offset, limit)
+        budget = _byte_budget(max_bytes)
+        with _open_sealed_version_snapshot(index, entry, pin) as (version, snapshot):
+            filters = parse_predicates(predicates, column_types=dict(version.column_types))
+            return _rows_result(
+                version,
+                entry,
+                parquet=snapshot.parquet_file(),
+                pin=pin,
+                filters=filters,
+                offset=window_offset,
+                limit=window_limit,
+                budget=budget,
+            )
+    except ServingRefused as refusal:
+        return _refused_result(dataset_id, pin, refusal, entry)
+
+
+def _byte_budget(max_bytes: int | None) -> int:
+    if max_bytes is None:
+        return MAX_SERVED_BYTES
+    if type(max_bytes) is not int or max_bytes < 1:
+        raise ServingRefused(
+            "a read's byte budget is a whole number of at least 1 [SERVING_WINDOW]"
+        )
+    # Clamped, never taken as given: this parameter may tighten the surface's bound and may never
+    # loosen it, so it is not a way to ask for more than the surface will serve.
+    return min(max_bytes, MAX_SERVED_BYTES)
+
+
+def _rows_result(
+    version: SealedVersion,
+    entry: IndexedVersion,
+    *,
+    parquet: Any,
+    pin: str,
+    filters: tuple[Predicate, ...],
+    offset: int,
+    limit: int,
+    budget: int,
+) -> ServingResult:
+    """Read, filter, window, render and fit — and hand back the one envelope."""
+
+    try:
+        columns, total_row_count = rowset.inspect_sealed_parquet(
+            parquet,
+            max_columns=pipeline.MAX_COLUMNS,
+            max_rows=pipeline.MAX_ROWS,
+            max_uncompressed_bytes=pipeline.MAX_CANDIDATE_BYTES,
+        )
+        if tuple(columns) != version.columns:
+            raise ServingRefused(
+                f"{_named(entry)} does not describe its own shape, so it was not served "
+                "[SERVING_VERSION_SHAPE]"
+            )
+        matched_row_count, rendered = rowset.render_filtered_window(
+            parquet,
+            columns,
+            select=lambda batch: _select_rows(batch, filters),
+            offset=offset,
+            limit=limit,
+            exact_match_count=total_row_count if not filters else None,
+        )
+    except rowset.RowsetError as error:
+        raise ServingRefused(_rowset_refusal(error, entry)) from error
+
+    def result_for(prefix: int) -> ServingResult:
+        return ServingResult(
+            ok=True,
+            refusals=(),
+            status=STATUS_ROWS_SERVED,
+            dataset_id=version.dataset_id,
+            pin=pin,
+            pin_kind=version.pin_kind,
+            version_id=version.version_id,
+            version_number=version.version_number,
+            version_digest=version.candidate_digest,
+            table_digest=version.table_sha256,
+            payload={
+                "columns": list(columns),
+                "rows": rendered[:prefix],
+                "total_row_count": total_row_count,
+                "matched_row_count": matched_row_count,
+                "offset": offset,
+                "limit": limit,
+                # Honest in both directions: true when the byte budget shrank the window, and true
+                # when the window simply did not reach the end of the match set.
+                "truncated": offset + prefix < matched_row_count,
+            },
+        )
+
+    # The fit loop searches over row PREFIXES and hands back the encoding it selected. The prefix
+    # that produced those bytes is recovered rather than re-derived, so the response returned is the
+    # response that was measured — no second encoding that might differ from the one that fit.
+    measured: dict[bytes, int] = {}
+
+    def encode(prefix: int) -> bytes:
+        encoded = result_for(prefix).canonical_bytes()
+        measured[encoded] = prefix
+        return encoded
+
+    try:
+        fitted = rowset.fit_canonical_payload(encode, len(rendered), max_bytes=budget)
+    except rowset.RowsetError as error:
+        raise ServingRefused(_rowset_refusal(error, entry)) from error
+    return result_for(measured[fitted])
+
+
+__all__ = [
+    "MAX_DATASET_ID_CHARS",
+    "MAX_FILTER_VALUE_CHARS",
+    "MAX_INDEXED_DATASETS",
+    "MAX_INDEXED_VERSIONS_PER_DATASET",
+    "MAX_IN_VALUES",
+    "MAX_PIN_CHARS",
+    "MAX_PREDICATES",
+    "MAX_RUN_DIR_CHARS",
+    "MAX_RUN_DIR_COMPONENT_CHARS",
+    "MAX_SERVED_BYTES",
+    "MAX_SERVED_ROWS",
+    "PIN_CURRENT",
+    "PREDICATE_OPS",
+    "SERVING_RESULT_SCHEMA",
+    "SERVING_SCHEMA_PREFIX",
+    "STATUS_DATASET_DESCRIBED",
+    "STATUS_REFUSED",
+    "STATUS_ROWS_SERVED",
+    "VERSION_INDEX_SCHEMA",
+    "IndexedDataset",
+    "IndexedVersion",
+    "Predicate",
+    "SealedVersion",
+    "ServingRefused",
+    "ServingResult",
+    "VersionIndex",
+    "describe_dataset",
+    "open_sealed_version",
+    "parse_predicates",
+    "parse_version_index",
+    "read_version_index",
+    "resolve_pin",
+    "serve_rows",
+    "serving_lines",
+]