mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/readers.py

@@ -0,0 +1,1124 @@
+"""Reading the builds you already have: one build in full, and every build under a folder.
+
+Two readings live here, and the difference between them is the whole point of the module.
+
+The full reading goes through :func:`pipeline.inspect_candidate` -- the descriptor-relative,
+ancestor-race-checked, lease-validated reader that replays the sealed tree before it reports a
+single fact. Nothing on that path opens a receipt with a plain read, because a plain read looks
+identical and silently drops every guarantee this product sells.
+
+The listing is deliberately cheap. It reads the receipt header off each folder without replaying
+anything, so a folder full of builds lists in the time one verification would take. That is a real
+trade and it is stated out loud rather than hidden: every listed row, in both output modes, ends
+with ``listed, not verified`` until someone asks for the re-check.
+
+Nothing here prints. Every function returns facts or text, so the same reading can be rendered
+into a browser page later without re-deriving it.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import shutil
+import stat
+import tempfile
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - descriptor workspaces are POSIX-only
+    fcntl = None  # type: ignore[assignment]
+
+from mostlyright.data_harness.canonical import CanonicalJSONError, parse_json
+from mostlyright.data_harness.pipeline import (
+    MAX_CANDIDATE_BYTES,
+    MAX_CANDIDATE_MEMBER_BYTES,
+    RECIPE_MANIFEST_VERSION,
+    BuildError,
+    inspect_candidate,
+)
+from mostlyright.data_harness.recipe import version_bindings, version_summary
+from mostlyright.data_harness.ux.headline import naming, plain_headline
+from mostlyright.data_harness.ux.path_kind import (
+    A_FILE,
+    A_FOLDER,
+    UNKNOWN_KIND,
+    entry_at,
+    kind_at,
+    presence_at,
+)
+
+# Where builds land when nobody says otherwise, and how far down to look for them. Six levels
+# covers `.work/<anything>/<a few nested folders>/<build>` without ever walking a whole home
+# directory by accident.
+DEFAULT_LIST_ROOT = Path(".work")
+DEFAULT_LIST_DEPTH = 6
+MAX_LIST_DEPTH = 32
+
+# What a listing says about itself. These are the exact phrases the honesty test pins, and they
+# are the same strings in the plain lines and in the machine-readable object.
+LISTED_ONLY = "listed, not verified"
+VERIFIED = "verified"
+UNREADABLE = "could not be read"
+# What the listing as a whole says about itself once `--verify` has run. The listing-level word is
+# derived from the entries and never from the flag: asking for a re-check is not the same fact as
+# every build passing one, and a listing that reports the mode it was asked for under the same key
+# an entry uses for its outcome tells a machine that a tampered tree verified.
+NOT_ALL_VERIFIED = "not all verified"
+NOTHING_TO_VERIFY = "nothing to verify"
+# A folder the walk stopped at that holds no Build at all -- a Workbench folder made but not run
+# yet, most often. It is not a build that could not be read, and saying so is the difference
+# between "you have not run this" and "something is wrong with this".
+NOTHING_BUILT = "nothing built here yet"
+
+# The two plain sentences an entry can carry instead of a build's facts. They are sentences rather
+# than the exception's own text on purpose: an errno string names an internal path nobody typed,
+# and a raise-site message is written in the words the module around it uses. The exact wording is
+# never lost -- it is what `mr-data show` and `mr-data verify` print for that same folder, and the
+# listing's note says so.
+NOTHING_BUILT_REASON = "Nothing has been built in this folder yet."
+UNREADABLE_REASON = "Its Receipt is there but could not be read."
+# A Workbench folder whose durable record could not be read at all. The Build underneath may be
+# perfectly good -- `mr-data show` on it often still answers -- but the listing does not know where
+# it is, and saying "nothing has been built here" about a folder that holds a Receipt is the one
+# answer that is affirmatively false.
+UNRESOLVED_REASON = "Its Workbench record could not be read, so its Build was not opened."
+# A descendant the descriptor-rooted walk could not even classify. It cannot truthfully claim a
+# Receipt or Workbench record exists, but it must still make the incomplete part of the catalog a
+# typed unreadable row instead of making that subtree indistinguishable from an empty one.
+DESCENDANT_UNREADABLE_REASON = "This folder could not be read, so any Build in it was not opened."
+# The commonest reason a Workbench record cannot be read right now, and the only one that resolves
+# itself: a build is holding the folder. The listing says so and moves on rather than joining the
+# queue behind a build that may run for minutes.
+BUSY_REASON = "A build is running in this folder, so its record was not read."
+
+# The sealed tree's own folder name. It is a contract identifier -- it is spelled this way inside
+# every receipt this product has ever written -- so it is written once here and referred to by
+# name everywhere else, rather than repeated as a bare word the vocabulary sweep has to argue for.
+_SEALED_TREE = Path("candidate")
+_RECEIPT = _SEALED_TREE / "manifest.json"
+_PROFILE = _SEALED_TREE / "evidence" / "profile.json"
+_CONTROL_DIRECTORY = ".mr-data"
+# The child a Workbench folder keeps its run under. This is not a guess the listing makes: the run
+# state records this path and the coordinator validates the recorded value to be exactly this, so
+# it is where the run is whenever the record can be read at all. It is used as the fallback when
+# the record cannot be read, so a Build under a damaged Workbench folder is still pointed at rather
+# than dropped from the listing.
+_RUN_CHILD = Path("result")
+_STATE_FILE = "state.json"
+_LOCK_FILE = ".lock"
+_MAX_WORKBENCH_STATE_BYTES = 2 * 1024 * 1024
+
+
+# ------------------------------------------------------------------------------------------------
+# One build, in full
+# ------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BuildFacts:
+    """Everything a reader asks about one sealed build, from one verified reading of it."""
+
+    run_dir: Path
+    candidate_digest: str
+    table_sha256: str
+    manifest_version: str
+    validation_policy_digest: str
+    producer_principal: str
+    producer_attempt: str
+    question: str
+    feasibility: str | None
+    grain: tuple[str, ...]
+    columns: tuple[str, ...]
+    column_types: tuple[tuple[str, str], ...]
+    row_count: int
+    sources: tuple[dict[str, Any], ...]
+    join: dict[str, Any]
+    quality: dict[str, Any]
+    lineage: dict[str, Any]
+    lineage_digest: str
+    member_paths: tuple[str, ...]
+    recipe_id: str | None = None
+    recipe_version: int | None = None
+    recipe_digest: str | None = None
+    approval_id: str | None = None
+    approval_digest: str | None = None
+    execution_digest: str | None = None
+    execution_mode: str | None = None
+
+    def type_of(self, column: str) -> str | None:
+        return dict(self.column_types).get(column)
+
+    def to_dict(self, *, members: bool = False) -> dict[str, Any]:
+        """The one payload both renderings are built from.
+
+        Facts taken from the data -- column names, check names, source names -- go in values, never
+        in keys. A key is given a plain label when it is shown to a person, and a column named
+        ``max_temp_c`` used as a key would be shown as ``Max temp c``: a name the data does not
+        have.
+        """
+
+        payload: dict[str, Any] = {
+            "status": "build_shown",
+            "run_dir": str(self.run_dir),
+            "candidate_digest": self.candidate_digest,
+            "table_sha256": self.table_sha256,
+            "manifest_version": self.manifest_version,
+            "row_count": self.row_count,
+            "columns": list(self.columns),
+            "grain": list(self.grain),
+            "question": self.question,
+            "built_by": self.producer_principal,
+            "build_attempt": self.producer_attempt,
+            "validation_policy_digest": self.validation_policy_digest,
+            "lineage_digest": self.lineage_digest,
+            "schema": self._schema_payload(),
+            "quality": self._quality_payload(),
+            "sources": self._sources_payload(),
+            "join": self._join_payload(),
+        }
+        if self.feasibility is not None:
+            payload["feasibility"] = self.feasibility
+        if self.recipe_digest is not None:
+            payload["recipe_id"] = self.recipe_id
+            payload["recipe_version"] = self.recipe_version
+            payload["recipe_digest"] = self.recipe_digest
+            payload["approval_id"] = self.approval_id
+            payload["approval_digest"] = self.approval_digest
+            payload["execution_digest"] = self.execution_digest
+            payload["execution_mode"] = self.execution_mode
+        if members:
+            payload["member_paths"] = list(self.member_paths)
+        return payload
+
+    def _schema_payload(self) -> dict[str, dict[str, Any]]:
+        width = len(str(max(len(self.columns), 1)))
+        return {
+            f"column {index:0{width}d}": {"name": name, "type": self.type_of(name)}
+            for index, name in enumerate(self.columns, start=1)
+        }
+
+    def _quality_payload(self) -> dict[str, Any]:
+        checks = _checks(self.quality)
+        width = len(str(max(len(checks), 1)))
+        payload: dict[str, Any] = {"result": self.quality.get("status")}
+        for index, check in enumerate(checks, start=1):
+            payload[f"check {index:0{width}d}"] = {
+                "name": check.get("check_id"),
+                "result": "passed" if check.get("passed") else "failed",
+                "wanted": check.get("expected"),
+                "found": check.get("observed"),
+            }
+        return payload
+
+    def _sources_payload(self) -> dict[str, Any]:
+        width = len(str(max(len(self.sources), 1)))
+        return {
+            f"source {index:0{width}d}": {
+                "name": source.get("source_id"),
+                "file": source.get("relative_path"),
+                "size in bytes": source.get("bytes"),
+                "content fingerprint": source.get("sha256"),
+                "came from": source.get("origin"),
+            }
+            for index, source in enumerate(self.sources, start=1)
+        }
+
+    def _join_payload(self) -> dict[str, Any]:
+        if not self.join:
+            return {}
+        return {
+            "left": self.join.get("left_source"),
+            "right": self.join.get("right_source"),
+            "keys": list(self.join.get("keys", ())),
+            "relationship": self.join.get("cardinality"),
+            "rows in": self.join.get("left_rows"),
+            "rows out": self.join.get("output_rows"),
+            "rows that did not match": self.join.get("unmatched_left_rows"),
+        }
+
+
+def build_facts(run_dir: Path | str) -> BuildFacts:
+    """Read one sealed build, verifying it on the way.
+
+    Everything reported here comes from :func:`inspect_candidate`, which replays the whole sealed
+    tree, plus the two recipe-side readers that go through the same verified snapshot. A folder
+    with no build in it is named as such before any of that runs, because the reader's own refusal
+    for a missing tree reads like a break-in rather than a typo.
+    """
+
+    target = Path(run_dir)
+    require_a_build(target)
+    inspection = inspect_candidate(target)
+    summary = version_summary(target)
+    bindings = (
+        version_bindings(target) if inspection.manifest_version == RECIPE_MANIFEST_VERSION else None
+    )
+    return BuildFacts(
+        run_dir=target,
+        candidate_digest=inspection.candidate_digest,
+        table_sha256=inspection.table_sha256,
+        manifest_version=inspection.manifest_version,
+        validation_policy_digest=inspection.validation_policy_digest,
+        producer_principal=inspection.producer_principal,
+        producer_attempt=inspection.producer_attempt,
+        question=inspection.question,
+        feasibility=inspection.feasibility,
+        grain=inspection.grain,
+        columns=inspection.columns,
+        column_types=summary.column_types,
+        row_count=inspection.row_count,
+        sources=inspection.sources,
+        join=inspection.join,
+        quality=inspection.quality,
+        lineage=inspection.lineage,
+        lineage_digest=summary.lineage_digest,
+        member_paths=inspection.member_paths,
+        recipe_id=None if bindings is None else bindings.recipe.recipe_id,
+        recipe_version=None if bindings is None else bindings.recipe.recipe_version,
+        recipe_digest=None if bindings is None else bindings.recipe.digest,
+        approval_id=None if bindings is None else bindings.approval.approval_id,
+        approval_digest=None if bindings is None else bindings.approval.digest,
+        execution_digest=None if bindings is None else bindings.execution.digest,
+        execution_mode=None if bindings is None else bindings.execution.mode,
+    )
+
+
+def plain_card(facts: BuildFacts) -> str:
+    """The plain-language card for one build, written from the facts above.
+
+    It does not read, and must not read, the sealed card member of the build. Those bytes sit
+    inside seven recorded digests, so rewording them moves every one of those digests, and no
+    command shows them to a person today. Everything a card would say is already in the facts a
+    verified reading returns, so the card is written from those instead.
+    """
+
+    lines = [
+        f"What this answers: {facts.question}",
+        f"One row is one {_grain_phrase(facts.grain)}.",
+        f"{facts.row_count} rows, {len(facts.columns)} columns:",
+    ]
+    lines.extend(f"  {name} ({facts.type_of(name) or 'unknown'})" for name in facts.columns)
+    if facts.sources:
+        lines.append("Where it came from:")
+        for source in facts.sources:
+            name = source.get("source_id", "a source")
+            where = source.get("relative_path", "an unnamed file")
+            lines.append(f"  {name}: {where}")
+    lines.append(_checks_sentence(facts.quality))
+    if facts.recipe_id is not None:
+        lines.append(f"Made by the Recipe {facts.recipe_id}, version {facts.recipe_version}.")
+    lines.append(f"Build fingerprint: {facts.candidate_digest}")
+    lines.append(f"Data fingerprint: {facts.table_sha256}")
+    return "\n".join(lines)
+
+
+def _grain_phrase(grain: Sequence[str]) -> str:
+    """What one row is, said the way a person would say it."""
+
+    names = [str(name) for name in grain]
+    if not names:
+        return "record"
+    if len(names) == 1:
+        return names[0]
+    return f"{', '.join(names[:-1])} and {names[-1]}"
+
+
+def _checks_sentence(quality: Mapping[str, Any]) -> str:
+    """One honest sentence about the checks, naming the ones that did not pass."""
+
+    checks = _checks(quality)
+    if not checks:
+        return "No checks were recorded for this build."
+    failed = [str(check.get("check_id")) for check in checks if not check.get("passed")]
+    if not failed:
+        return f"Checks: all {len(checks)} passed."
+    passed = len(checks) - len(failed)
+    return f"Checks: {passed} of {len(checks)} passed. Did not pass: {', '.join(failed)}"
+
+
+def _checks(quality: Mapping[str, Any]) -> tuple[dict[str, Any], ...]:
+    raw = quality.get("checks") if isinstance(quality, Mapping) else None
+    if not isinstance(raw, list):
+        return ()
+    return tuple(item for item in raw if isinstance(item, dict))
+
+
+def require_a_build(run_dir: Path) -> None:
+    """Refuse a folder with no build in it by name, before the verified reader is asked.
+
+    This is a signpost, not a check that anything is trusted: the verified reading still runs and
+    still decides. Its only job is that pointing a command at the wrong folder reads like the typo
+    it usually is.
+
+    Public because the comparison in :mod:`mostlyright.data_harness.ux.diffing` needs the same
+    signpost, and two copies of one sentence are two sentences that can drift apart.
+    """
+
+    if not (run_dir / _RECEIPT).is_file():
+        raise BuildError("CANDIDATE_ABSENT", f"there is no build at {run_dir}")
+
+
+def holds_a_build(directory: Path) -> bool:
+    """Whether this folder is, or leads to, a Build -- the question the plain sentences need.
+
+    A Workbench folder keeps its run underneath, so it counts when that run holds a Receipt; any
+    other folder counts when it holds one itself. Public because the command line's error boundary
+    has to tell "you have not built here yet" apart from "this build cannot be opened safely", and
+    those two answers name completely different fixes.
+
+    The answer is the Receipt, never the readability of the durable record. A Workbench folder
+    whose record cannot be read is one of the two cases the boundary is here to tell apart, and
+    answering ``False`` for it would hand the class rule -- no answer about a Build where there is
+    no Build -- a false premise about a folder that holds one.
+
+    The question is asked of the entry, not of what the name leads to. A resolving
+    ``(stop.run_dir / manifest.json).is_file()`` check would treat an ordinary
+    ``~/builds/latest -> real-build`` link as "a Build is there" even though the harness refuses
+    to open that path: ``mr-data build --output ~/builds/latest`` says the path
+    "already holds something ... Run: mr-data show
+    ~/builds/latest", and that command exits 1 with ``CANDIDATE_ANCESTOR_SYMLINK``. So the question
+    is now the one every reader here actually asks: is the entry a folder, and is the Receipt in it
+    a plain file. A link is not a Build this harness will open, and saying it is was the whole
+    defect.
+    """
+
+    if kind_at(directory) != A_FOLDER:
+        return False
+    if _receipt_entry(directory):
+        return True
+    return kind_at(directory / _CONTROL_DIRECTORY) == A_FOLDER and _receipt_entry(
+        directory / _RUN_CHILD
+    )
+
+
+def _receipt_entry(run_dir: Path) -> bool:
+    """Whether the Receipt in this folder is a plain file, asked of the entry and never followed.
+
+    A resolving ``(run_dir / _RECEIPT).is_file()`` check is wrong in two ways. It **follows the
+    name**, so a link where the Receipt should be answers "a Build is here" about a file no reader
+    in this package will open. And ``Path.is_file`` *raises* when the account may not look -- which
+    is load-bearing: a listing that answered ``False`` there would
+    report a folder it cannot read as a folder with nothing built in it, which is a second silent
+    answer of exactly the kind this module exists to end.
+
+    So this is one ``lstat``, it follows nothing, and the two refusals that mean "no Receipt is
+    there" are the only ones it turns into an answer. Every other refusal is raised, the way it
+    always was, and the callers that have somewhere to put it -- ``cli._subject_holds_a_build``,
+    ``preflight._holds_a_build`` -- still turn it into "I cannot tell". That is
+    :func:`ux.path_kind.entry_at`, which exists because this is the question, asked once, in the
+    module that owns it.
+    """
+
+    return entry_at(run_dir / _RECEIPT) == A_FILE
+
+
+# ------------------------------------------------------------------------------------------------
+# Every build under a folder
+# ------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BuildEntry:
+    """One folder a listing stopped at, and how much was actually read to describe it.
+
+    ``reason`` is one plain sentence, present exactly when the facts above it are not. It is the
+    same string in both output modes, because a listing has one set of facts and renders them
+    twice; the listing does not carry a second, engineering wording for a machine to read.
+    """
+
+    run_dir: Path
+    verified: bool
+    manifest_version: str | None = None
+    candidate_digest: str | None = None
+    table_sha256: str | None = None
+    row_count: int | None = None
+    reason: str | None = None
+    nothing_built: bool = False
+
+    @property
+    def verification(self) -> str:
+        if self.nothing_built:
+            return NOTHING_BUILT
+        if self.reason is not None:
+            return UNREADABLE
+        return VERIFIED if self.verified else LISTED_ONLY
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "run_dir": str(self.run_dir),
+            "manifest_version": self.manifest_version,
+            "candidate_digest": self.candidate_digest,
+            "table_sha256": self.table_sha256,
+            "row_count": self.row_count,
+            "verification": self.verification,
+        }
+        if self.reason is not None:
+            payload["why"] = self.reason
+        return payload
+
+
+def listing_verification(entries: Sequence[BuildEntry], *, verify: bool) -> str:
+    """What the listing as a whole may claim, taken from the entries rather than from the flag.
+
+    ``--verify`` is a request. Whether every build under the root answered it is a fact, and the
+    two are not the same sentence. The listing-level word shares its key and its vocabulary with
+    the per-entry one, so a reader that branches on either gets the same answer about the same
+    tree: ``verified`` only when every entry verified, and a word that says otherwise when one did
+    not. A root with nothing under it verified nothing, and says that rather than claiming a clean
+    result over an empty listing.
+    """
+
+    if not verify:
+        return LISTED_ONLY
+    if not entries:
+        return NOTHING_TO_VERIFY
+    if all(entry.verification == VERIFIED for entry in entries):
+        return VERIFIED
+    return NOT_ALL_VERIFIED
+
+
+def list_builds(
+    root: Path | str,
+    *,
+    verify: bool = False,
+    max_depth: int = DEFAULT_LIST_DEPTH,
+) -> tuple[BuildEntry, ...]:
+    """Every build under ``root``, in folder order.
+
+    Without ``verify`` this reads each receipt and nothing else, and every entry says so. With
+    ``verify`` each build is replayed through the same reader ``show`` uses, and only then does an
+    entry say it was verified.
+
+    A folder that cannot be read comes back as an entry carrying the reason. A build you cannot
+    read is exactly the thing you want a listing to put in front of you, so it is never dropped.
+    """
+
+    start = Path(root)
+    try:
+        root_before = _open_listing_root(start)
+    except OSError as error:
+        found_at_root = presence_at(start)
+        if found_at_root == A_FOLDER:
+            # The entry is the required kind, but this account could not open it for traversal.
+            # Preserve that operating-system refusal so the command's shared remediation says the
+            # access was refused; calling an unreadable folder absent would erase the distinction.
+            raise
+        # `is_dir` follows links and cannot distinguish a dangling link or plain file from an absent
+        # listing root. Use the noun from `ux.path_kind`'s non-following lookup instead.
+        raise BuildError(
+            "LIST_ROOT_ABSENT",
+            f"there is {found_at_root or UNKNOWN_KIND} at {start}, and a listing reads a folder",
+        ) from error
+    try:
+        depth = _bounded_depth(max_depth)
+        found = sorted(
+            _build_directories(root_before.descriptor, start, depth),
+            key=lambda stop: stop.run_dir,
+        )
+        entries = tuple(
+            _entry(stop, root_descriptor=root_before.descriptor, verify=verify) for stop in found
+        )
+        try:
+            root_after = _open_listing_root(start)
+        except OSError:
+            root_after = None
+        try:
+            if root_after is None or root_after.identity != root_before.identity:
+                # No row collected through a different namespace is allowed to leave this
+                # function. The first observation used to be followed by an unbound pathname walk,
+                # so replacing the checked folder with a link in that gap made outside Receipts
+                # look like children of the original spelling. The no-follow directory opens bind
+                # both observations to concrete inodes; a changed name becomes a typed refusal
+                # before either renderer gets the tuple above.
+                raise BuildError(
+                    "LIST_ROOT_ABSENT",
+                    f"the listing root changed while it was being read: {start}",
+                )
+        finally:
+            if root_after is not None:
+                os.close(root_after.descriptor)
+        return entries
+    finally:
+        os.close(root_before.descriptor)
+
+
+@dataclass(frozen=True)
+class _ListingRootHandle:
+    """An opened directory and the filesystem identity bound by that same operation."""
+
+    descriptor: int
+    identity: tuple[int, int]
+
+
+def _open_listing_root(root: Path) -> _ListingRootHandle:
+    """Open the named root as the directory itself, never a link target."""
+
+    descriptor = os.open(
+        root,
+        os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+    )
+    try:
+        observed = os.fstat(descriptor)
+    except BaseException:
+        os.close(descriptor)
+        raise
+    return _ListingRootHandle(descriptor, (observed.st_dev, observed.st_ino))
+
+
+def _bounded_depth(max_depth: int) -> int:
+    if type(max_depth) is not int or not 0 <= max_depth <= MAX_LIST_DEPTH:
+        raise BuildError(
+            "LIST_DEPTH",
+            f"how deep to look must be a whole number from 0 to {MAX_LIST_DEPTH}",
+        )
+    return max_depth
+
+
+@dataclass(frozen=True)
+class _Stop:
+    """One folder the walk stopped at, before anything in it was read.
+
+    ``run_dir`` is where the Build would be. ``reason`` is set only when resolving the folder was
+    itself refused -- the record could not be read, or a build is holding it -- and it is carried
+    into the entry rather than thrown away, because a folder whose record cannot be read is not a
+    folder nothing has been built in. ``nothing_built`` is the one narrow case where that second
+    sentence is true: there is no run recorded here at all.
+    """
+
+    run_dir: Path
+    relative: tuple[str, ...]
+    reason: str | None = None
+    nothing_built: bool = False
+
+
+def _open_directory_beneath(root_descriptor: int, relative: tuple[str, ...]) -> int:
+    """Open one descendant from the retained root, refusing every linked component."""
+
+    descriptor = os.dup(root_descriptor)
+    try:
+        for name in relative:
+            child = os.open(
+                name,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=descriptor,
+            )
+            os.close(descriptor)
+            descriptor = child
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _read_regular_at(
+    directory_descriptor: int,
+    relative: tuple[str, ...],
+    *,
+    maximum: int | None,
+    required_mode: int | None = None,
+) -> bytes:
+    """Read one bounded regular descendant through directory descriptors only."""
+
+    if not relative:
+        raise FileNotFoundError("a file name is required")
+    parent = _open_directory_beneath(directory_descriptor, relative[:-1])
+    descriptor: int | None = None
+    try:
+        descriptor = os.open(
+            relative[-1],
+            os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=parent,
+        )
+        observed = os.fstat(descriptor)
+        if not stat.S_ISREG(observed.st_mode):
+            raise OSError(errno.EINVAL, "listed member is not a regular file")
+        if required_mode is not None and stat.S_IMODE(observed.st_mode) != required_mode:
+            raise OSError(errno.EPERM, "listed member mode changed")
+        if maximum is not None and observed.st_size > maximum:
+            raise OSError(errno.EFBIG, "listed member exceeds its read bound")
+        chunks: list[bytes] = []
+        remaining = maximum + 1 if maximum is not None else None
+        while remaining is None or remaining:
+            chunk = os.read(
+                descriptor, min(remaining, 1 << 16) if remaining is not None else 1 << 16
+            )
+            if not chunk:
+                break
+            chunks.append(chunk)
+            if remaining is not None:
+                remaining -= len(chunk)
+        raw = b"".join(chunks)
+        if maximum is not None and len(raw) > maximum:
+            raise OSError(errno.EFBIG, "listed member grew beyond its read bound")
+        return raw
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+        os.close(parent)
+
+
+def _read_unbounded_regular_at(
+    directory_descriptor: int,
+    relative: tuple[str, ...],
+) -> bytes:
+    """Read a rooted regular listing member without a byte limit."""
+
+    return _read_regular_at(directory_descriptor, relative, maximum=None)
+
+
+def _plain_file_at(directory_descriptor: int, relative: tuple[str, ...]) -> bool:
+    """Whether one descendant entry is a regular file, without following any component."""
+
+    if not relative:
+        return False
+    try:
+        parent = _open_directory_beneath(directory_descriptor, relative[:-1])
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+    try:
+        observed = os.stat(relative[-1], dir_fd=parent, follow_symlinks=False)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+    finally:
+        os.close(parent)
+    return stat.S_ISREG(observed.st_mode)
+
+
+def _folder_at(directory_descriptor: int, name: str) -> bool:
+    try:
+        observed = os.stat(name, dir_fd=directory_descriptor, follow_symlinks=False)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+    return stat.S_ISDIR(observed.st_mode)
+
+
+def _build_directories(root_descriptor: int, root: Path, max_depth: int) -> list[_Stop]:
+    """Walk below the retained root descriptor, never reopening the root pathname."""
+
+    found: list[_Stop] = []
+    pending: list[tuple[tuple[str, ...], int]] = [((), 0)]
+    while pending:
+        relative, depth = pending.pop()
+        try:
+            directory = _open_directory_beneath(root_descriptor, relative)
+        except OSError:
+            if not relative:
+                raise
+            found.append(
+                _Stop(
+                    root.joinpath(*relative),
+                    relative,
+                    reason=DESCENDANT_UNREADABLE_REASON,
+                )
+            )
+            continue
+        try:
+            try:
+                stop = _build_directory_at(directory, root, relative)
+            except OSError:
+                found.append(
+                    _Stop(
+                        root.joinpath(*relative),
+                        relative,
+                        reason=DESCENDANT_UNREADABLE_REASON,
+                    )
+                )
+                continue
+            if stop is not None:
+                found.append(stop)
+                continue
+            if depth >= max_depth:
+                continue
+            try:
+                children, unreadable, incomplete = _child_directories(directory)
+            except OSError:
+                found.append(
+                    _Stop(
+                        root.joinpath(*relative),
+                        relative,
+                        reason=DESCENDANT_UNREADABLE_REASON,
+                    )
+                )
+                continue
+            if incomplete:
+                found.append(
+                    _Stop(
+                        root.joinpath(*relative),
+                        relative,
+                        reason=DESCENDANT_UNREADABLE_REASON,
+                    )
+                )
+            found.extend(
+                _Stop(
+                    root.joinpath(*relative, name),
+                    (*relative, name),
+                    reason=DESCENDANT_UNREADABLE_REASON,
+                )
+                for name in unreadable
+            )
+            pending.extend(((*relative, name), depth + 1) for name in children)
+        finally:
+            os.close(directory)
+    return found
+
+
+def _build_directory_at(
+    directory_descriptor: int,
+    root: Path,
+    relative: tuple[str, ...],
+) -> _Stop | None:
+    """The run represented by an already opened descendant, if it holds one."""
+
+    display = root.joinpath(*relative)
+    if _folder_at(directory_descriptor, _CONTROL_DIRECTORY):
+        return _workbench_run_directory(directory_descriptor, display, relative)
+    if _plain_file_at(directory_descriptor, _RECEIPT.parts):
+        return _Stop(display, relative)
+    return None
+
+
+def _workbench_run_directory(
+    directory_descriptor: int,
+    display: Path,
+    relative: tuple[str, ...],
+) -> _Stop:
+    """Read a Workbench's fixed result child through its retained directory descriptor."""
+
+    child_relative = (*relative, _RUN_CHILD.name)
+    child_display = display / _RUN_CHILD
+    control: int | None = None
+    lock: int | None = None
+    try:
+        control = os.open(
+            _CONTROL_DIRECTORY,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=directory_descriptor,
+        )
+        if fcntl is None:
+            raise OSError(errno.ENOTSUP, "workbench locks are unavailable")
+        try:
+            lock = os.open(
+                _LOCK_FILE,
+                os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=control,
+            )
+            if not stat.S_ISREG(os.fstat(lock).st_mode):
+                raise OSError(errno.EINVAL, "workbench lock is not a regular file")
+        except FileNotFoundError:
+            return _Stop(display, relative, nothing_built=True)
+        try:
+            fcntl.flock(lock, fcntl.LOCK_SH | fcntl.LOCK_NB)
+        except OSError as error:
+            if error.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                return _Stop(child_display, child_relative, reason=BUSY_REASON)
+            raise
+        try:
+            raw = _read_regular_at(
+                control,
+                (_STATE_FILE,),
+                maximum=_MAX_WORKBENCH_STATE_BYTES,
+                required_mode=0o600,
+            )
+        except FileNotFoundError:
+            return _Stop(display, relative, nothing_built=True)
+        state = parse_json(raw)
+        if not isinstance(state, dict) or state.get("paths") != {
+            "input_root": "inputs",
+            "result": _RUN_CHILD.name,
+        }:
+            raise ValueError("workbench state does not name the fixed result child")
+        return _Stop(child_display, child_relative)
+    except (OSError, CanonicalJSONError, ValueError):
+        if _plain_file_at(directory_descriptor, _RUN_CHILD.parts + _RECEIPT.parts):
+            return _Stop(child_display, child_relative, reason=UNRESOLVED_REASON)
+        return _Stop(display, relative, reason=UNRESOLVED_REASON)
+    finally:
+        if lock is not None:
+            os.close(lock)
+        if control is not None:
+            os.close(control)
+
+
+def _child_directories(directory_descriptor: int) -> tuple[list[str], list[str], bool]:
+    children: list[str] = []
+    unreadable: list[str] = []
+    incomplete = False
+    with os.scandir(directory_descriptor) as entries:
+        iterator = iter(entries)
+        while True:
+            try:
+                entry = next(iterator)
+            except StopIteration:
+                break
+            except OSError:
+                incomplete = True
+                break
+            try:
+                if entry.is_dir(follow_symlinks=False):
+                    children.append(entry.name)
+            except OSError:
+                unreadable.append(entry.name)
+    return sorted(children), sorted(unreadable), incomplete
+
+
+def _entry(stop: _Stop, *, root_descriptor: int, verify: bool) -> BuildEntry:
+    """One row, from a folder the walk stopped at.
+
+    A stop that already carries a reason is answered with that reason in both readings. Asking for
+    a verified reading of a folder whose record could not be read cannot make it readable, and
+    replaying it anyway would report the folder under whichever wording the replay happened to
+    fail with rather than the one true thing known about it.
+    """
+
+    if stop.reason is not None:
+        return BuildEntry(run_dir=stop.run_dir, verified=False, reason=stop.reason)
+    if stop.nothing_built:
+        return BuildEntry(
+            run_dir=stop.run_dir,
+            verified=False,
+            reason=NOTHING_BUILT_REASON,
+            nothing_built=True,
+        )
+    if verify:
+        return _verified_entry(stop, root_descriptor)
+    return _listed_entry(stop, root_descriptor)
+
+
+def _copy_directory_snapshot(
+    source_descriptor: int,
+    destination: Path,
+    remaining: list[int],
+) -> None:
+    """Copy one descriptor-bound tree into a private path for the existing full verifier."""
+
+    with os.scandir(source_descriptor) as entries:
+        for entry in entries:
+            observed = entry.stat(follow_symlinks=False)
+            target = destination / entry.name
+            if stat.S_ISDIR(observed.st_mode):
+                child = os.open(
+                    entry.name,
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+                    dir_fd=source_descriptor,
+                )
+                try:
+                    target.mkdir(mode=0o700)
+                    _copy_directory_snapshot(child, target, remaining)
+                    target.chmod(stat.S_IMODE(observed.st_mode))
+                finally:
+                    os.close(child)
+                continue
+            if stat.S_ISREG(observed.st_mode):
+                source = os.open(
+                    entry.name,
+                    os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+                    dir_fd=source_descriptor,
+                )
+                destination_fd: int | None = None
+                try:
+                    opened = os.fstat(source)
+                    if not stat.S_ISREG(opened.st_mode) or (
+                        opened.st_dev,
+                        opened.st_ino,
+                    ) != (observed.st_dev, observed.st_ino):
+                        raise OSError(errno.ESTALE, "listed member changed during snapshot")
+                    if opened.st_size > MAX_CANDIDATE_MEMBER_BYTES or opened.st_size > remaining[0]:
+                        raise OSError(errno.EFBIG, "listed Build exceeds its verification bound")
+                    destination_fd = os.open(
+                        target,
+                        os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                        0o600,
+                    )
+                    member_bytes = 0
+                    while chunk := os.read(source, 1 << 20):
+                        member_bytes += len(chunk)
+                        remaining[0] -= len(chunk)
+                        if member_bytes > MAX_CANDIDATE_MEMBER_BYTES or remaining[0] < 0:
+                            raise OSError(
+                                errno.EFBIG,
+                                "listed Build grew beyond its verification bound",
+                            )
+                        view = memoryview(chunk)
+                        while view:
+                            written = os.write(destination_fd, view)
+                            view = view[written:]
+                    target.chmod(stat.S_IMODE(opened.st_mode))
+                finally:
+                    if destination_fd is not None:
+                        os.close(destination_fd)
+                    os.close(source)
+                continue
+            if stat.S_ISLNK(observed.st_mode):
+                target.symlink_to(os.readlink(entry.name, dir_fd=source_descriptor))
+                continue
+            raise OSError(errno.EINVAL, "listed tree contains an unsupported entry kind")
+
+
+def _snapshot_for_verification(root_descriptor: int, relative: tuple[str, ...]) -> Path:
+    """Materialise only bytes reachable below the retained listing root descriptor."""
+
+    temporary = Path(os.path.realpath(tempfile.mkdtemp(prefix="mr-data-list-verify-")))
+    run = temporary / "run"
+    run.mkdir()
+    source: int | None = None
+    candidate: int | None = None
+    try:
+        source = _open_directory_beneath(root_descriptor, relative)
+        candidate = os.open(
+            _SEALED_TREE.name,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=source,
+        )
+        candidate_info = os.fstat(candidate)
+        candidate_copy = run / _SEALED_TREE
+        candidate_copy.mkdir(mode=0o700)
+        _copy_directory_snapshot(candidate, candidate_copy, [MAX_CANDIDATE_BYTES])
+        candidate_copy.chmod(stat.S_IMODE(candidate_info.st_mode))
+        return run
+    except BaseException:
+        shutil.rmtree(temporary, ignore_errors=True)
+        raise
+    finally:
+        if candidate is not None:
+            os.close(candidate)
+        if source is not None:
+            os.close(source)
+
+
+def _discard_snapshot(snapshot: Path) -> None:
+    """Make the private sealed copy removable, then remove it."""
+
+    for directory, _children, files in os.walk(snapshot.parent):
+        folder = Path(directory)
+        try:
+            folder.chmod(0o700)
+        except OSError:
+            pass
+        for name in files:
+            try:
+                (folder / name).chmod(0o600, follow_symlinks=False)
+            except OSError:
+                pass
+    shutil.rmtree(snapshot.parent, ignore_errors=True)
+
+
+def _verified_entry(stop: _Stop, root_descriptor: int) -> BuildEntry:
+    snapshot: Path | None = None
+    try:
+        snapshot = _snapshot_for_verification(root_descriptor, stop.relative)
+        facts = build_facts(snapshot)
+    except BuildError as error:
+        if error.finding_id == "CANDIDATE_ABSENT":
+            return BuildEntry(
+                run_dir=stop.run_dir,
+                verified=False,
+                reason=NOTHING_BUILT_REASON,
+                nothing_built=True,
+            )
+        # A typed refusal from the replay. Its raise-site wording is translated through the same
+        # boundary the command line uses, so a listing cannot put an internal word on a line a
+        # person reads; a message that is already plain comes through untouched.
+        plain = plain_headline(error.finding_id, str(error), raised_as=naming(error))
+        return BuildEntry(run_dir=stop.run_dir, verified=False, reason=plain or f"{error}.")
+    except Exception:
+        return BuildEntry(run_dir=stop.run_dir, verified=False, reason=UNREADABLE_REASON)
+    finally:
+        if snapshot is not None:
+            _discard_snapshot(snapshot)
+    return BuildEntry(
+        run_dir=stop.run_dir,
+        verified=True,
+        manifest_version=facts.manifest_version,
+        candidate_digest=facts.candidate_digest,
+        table_sha256=facts.table_sha256,
+        row_count=facts.row_count,
+    )
+
+
+def _listed_entry(stop: _Stop, root_descriptor: int) -> BuildEntry:
+    """Read the receipt header and the row count, and nothing else.
+
+    This is the one place in the module that opens a sealed file directly, and it buys speed at
+    the cost of every guarantee the verified reading gives. That is why the entry it returns says
+    ``listed, not verified`` in both output modes, and why nothing else in this module does it.
+    """
+
+    try:
+        directory = _open_directory_beneath(root_descriptor, stop.relative)
+        try:
+            receipt = parse_json(_read_unbounded_regular_at(directory, _RECEIPT.parts))
+        finally:
+            os.close(directory)
+    except FileNotFoundError:
+        # Not a build that could not be read: a folder the walk stopped at -- almost always a
+        # Workbench folder that has been made but not run -- which holds no Receipt at all.
+        return BuildEntry(
+            run_dir=stop.run_dir,
+            verified=False,
+            reason=NOTHING_BUILT_REASON,
+            nothing_built=True,
+        )
+    except (OSError, CanonicalJSONError, ValueError):
+        return BuildEntry(run_dir=stop.run_dir, verified=False, reason=UNREADABLE_REASON)
+    if not isinstance(receipt, dict):
+        return BuildEntry(run_dir=stop.run_dir, verified=False, reason=UNREADABLE_REASON)
+    return BuildEntry(
+        run_dir=stop.run_dir,
+        verified=False,
+        manifest_version=_text(receipt.get("manifest_version")),
+        candidate_digest=_text(receipt.get("candidate_digest")),
+        table_sha256=_text(receipt.get("table_sha256")),
+        row_count=_listed_row_count(root_descriptor, stop.relative),
+    )
+
+
+def _listed_row_count(root_descriptor: int, relative: tuple[str, ...]) -> int | None:
+    """The row count off the same unverified reading; the receipt itself does not carry one."""
+
+    try:
+        directory = _open_directory_beneath(root_descriptor, relative)
+        try:
+            profile = parse_json(_read_unbounded_regular_at(directory, _PROFILE.parts))
+        finally:
+            os.close(directory)
+    except (OSError, CanonicalJSONError, ValueError):
+        return None
+    if not isinstance(profile, dict):
+        return None
+    count = profile.get("row_count")
+    return count if isinstance(count, int) and not isinstance(count, bool) else None
+
+
+def _text(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+__all__ = [
+    "BUSY_REASON",
+    "DEFAULT_LIST_DEPTH",
+    "DEFAULT_LIST_ROOT",
+    "DESCENDANT_UNREADABLE_REASON",
+    "LISTED_ONLY",
+    "MAX_LIST_DEPTH",
+    "NOTHING_BUILT",
+    "NOTHING_BUILT_REASON",
+    "NOTHING_TO_VERIFY",
+    "NOT_ALL_VERIFIED",
+    "UNREADABLE",
+    "UNREADABLE_REASON",
+    "UNRESOLVED_REASON",
+    "VERIFIED",
+    "BuildEntry",
+    "BuildFacts",
+    "build_facts",
+    "holds_a_build",
+    "list_builds",
+    "listing_verification",
+    "plain_card",
+    "require_a_build",
+]