mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/peek.py

@@ -0,0 +1,1000 @@
+"""Look at a file, or a public https address, before writing a Recipe against it.
+
+`peek` is the first thing a person tries and the first thing a driving agent runs. It answers one
+question -- what is in there -- and it answers it without building anything, approving anything, or
+writing a single byte to disk.
+
+Ordinary tabular bytes go through :func:`parse_tabular_bytes_for_display`. Reader-pinned bytes go
+through the exact Toolbox coordinate's warm-up and decode inside the same clean room as a Build;
+for a URL, retrieval and decode are one operation so container bytes never return to this process.
+That is deliberate and load-bearing: the size budgets, archive and executable refusal, strict
+UTF-8 rule, and row and cell limits come along for free, with no second unconfined parser. There is
+no ``open()``, no ``csv`` import, and no ``json`` import in this module, and
+`tests/test_ux_peek.py` reads this file's own source to keep it that way. Local bytes are fetched
+through :mod:`ux.plain_file`, the one open-then-fstat rule every command that takes a path from a
+person shares, so peek has no reading rule of its own either.
+
+The one difference is the display rendering. A Build's Reader refuses a value the canonical rule
+cannot hold exactly -- a date, a time, a duration, a decimal, a not-a-number -- because what a
+Build reads gets sealed. A peek seals nothing and writes nothing, so it renders those values into
+their exact text instead of refusing them, and reports the column as the kind of column it really
+is. That is why peek opens a Build's own ``table.parquet``, and every timestamped source the
+product exists to work with, rather than turning them away.
+
+What peek reports is deliberately small: the columns, the type observed in each, how many values
+are missing, how many are distinct, the lowest and highest, and the first few rows. Nothing here
+infers a type, coerces a value, or refuses a messy cell. Peek exists to look at data nobody has
+cleaned yet, so a peek that refuses messy data would not be a peek.
+
+Column types are reported in the product's own vocabulary -- ``string``, ``int64``, ``float64``,
+``boolean``, ``date``, ``timestamp_utc`` -- which is the set a Recipe accepts and the set
+``mr-data show`` and ``mr-data inventory`` print. That is not an inference: it is the observed kind
+under the name the rest of the product gives it, so a type read out of a peek is a type ``author``
+takes. A column that holds no single kind, or a kind none of the six covers, is never dressed up as
+one of them; see :func:`plain_column_type`.
+
+``timestamp_utc`` is the narrowest of the six and is not a synonym for "a timestamp": it is bound
+to ``timestamp[us, tz=UTC]``, and a Recipe refuses the type unless the timezone it declares is UTC.
+So a column whose timestamps carry no zone, or carry one that is not UTC, is reported as the kind
+it is rather than as that one -- the sample rows printed two lines below say the same thing, and
+the two may not disagree.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import tempfile
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from mostlyright.data_harness.acquisition.http import (
+    PinnedHttpsRetriever,
+    PinnedTransport,
+    RetrievalLimits,
+    StdlibPinnedTransport,
+    reader_retrieval_limits,
+)
+from mostlyright.data_harness.acquisition.parsing import (
+    _FORMAT_MEDIA_TYPES,
+    _FORMAT_SUFFIXES,
+    ParsedTable,
+    ParseLimits,
+    column_types,
+    parse_tabular_bytes_for_display,
+)
+from mostlyright.data_harness.acquisition.sandbox import CrawlerSandbox, SandboxResult
+from mostlyright.data_harness.acquisition.url_policy import (
+    AcquisitionSecurityError,
+    EgressPolicy,
+    Resolver,
+    SystemResolver,
+    _normalize_hostname,
+)
+from mostlyright.data_harness.canonical import sha256_bytes
+from mostlyright.data_harness.readers.contracts import ReaderError, ReaderPin, identifier, semver
+from mostlyright.data_harness.readers.registry import TOOLBOX
+from mostlyright.data_harness.readers.samples import DecodedFacts, ReaderSample, warm_up
+from mostlyright.data_harness.ux.path_kind import UNKNOWN_KIND, name_of_kind, presence_at
+from mostlyright.data_harness.ux.plain_file import (
+    DANGLING,
+    MISSING,
+    PlainFileRefusal,
+    open_plain_file,
+    read_bounded,
+)
+
+# How many rows come back by default, and the ceiling on asking for more. A peek is a look, not an
+# export: anything larger is a Build.
+DEFAULT_SAMPLE_ROWS = 5
+MAX_SAMPLE_ROWS = 100
+
+# Derived from the Reader's own allowlist rather than re-typed here, so the list of formats peek
+# offers cannot drift from the list of formats the harness can actually open.
+PEEK_FORMATS: tuple[str, ...] = tuple(sorted(_FORMAT_SUFFIXES))
+_SUFFIX_FORMATS: dict[str, str] = {
+    suffix: data_format
+    for data_format, suffixes in _FORMAT_SUFFIXES.items()
+    for suffix in sorted(suffixes)
+}
+_MEDIA_FORMATS: dict[str, str] = {
+    media_type: data_format
+    for data_format, media_types in _FORMAT_MEDIA_TYPES.items()
+    for media_type in sorted(media_types)
+}
+_READABLE = ", ".join(PEEK_FORMATS)
+_JSON_READER_COORDINATE = ("json.tabular", "1.0.0")
+_INHERITED_MEMORY_CGROUP_ROOT_FD = 3
+_EXTERNAL_NETWORK_POLICY_ATTESTATION_ENV = "MOSTLYRIGHT_EXTERNAL_NETWORK_POLICY_ATTESTATION"
+
+
+def _reader_sandbox(staging_root: Path) -> CrawlerSandbox:
+    memory_fd = None
+    if os.sys.platform == "linux":
+        try:
+            os.fstat(_INHERITED_MEMORY_CGROUP_ROOT_FD)
+            inherited = os.get_inheritable(_INHERITED_MEMORY_CGROUP_ROOT_FD)
+        except OSError:
+            pass
+        else:
+            if inherited:
+                memory_fd = _INHERITED_MEMORY_CGROUP_ROOT_FD
+    return CrawlerSandbox(
+        staging_root=staging_root,
+        external_network_policy_attestation=os.environ.get(
+            _EXTERNAL_NETWORK_POLICY_ATTESTATION_ENV
+        ),
+        memory_cgroup_root_fd=memory_fd,
+    )
+
+
+def _reader_pin(
+    coordinate: tuple[str, str] | None,
+    options: Mapping[str, Any],
+) -> tuple[Any, dict[str, Any], str]:
+    family = TOOLBOX.resolve(*(coordinate or _JSON_READER_COORDINATE))
+    admitted = dict(family.validate_options(options))
+    resolved = ReaderPin(family.family_id, family.family_version, admitted)
+    return (
+        family,
+        {
+            "family_id": family.family_id,
+            "family_version": family.family_version,
+            "decode_options": admitted,
+        },
+        resolved.options_digest,
+    )
+
+
+def _normalise_reader_request(
+    coordinate: tuple[str, str] | None,
+    options: Mapping[str, Any] | None,
+    data_format: str | None,
+) -> tuple[tuple[str, str] | None, Mapping[str, Any] | None]:
+    """Choose Reader mode once; an exact coordinate can never fall through to direct parsing."""
+
+    reader_requested = coordinate is not None or options is not None
+    if not reader_requested:
+        return None, None
+    if data_format is not None:
+        raise ReaderError(
+            "READER_OPTIONS",
+            "peek.format",
+            "data_format is for direct tabular preview and cannot be combined with a Reader",
+        )
+    if options is not None and not isinstance(options, Mapping):
+        raise ReaderError("READER_OPTIONS", "peek.reader_options", "must be an object")
+    if coordinate is None:
+        resolved_coordinate = _JSON_READER_COORDINATE
+    else:
+        if not isinstance(coordinate, tuple) or len(coordinate) != 2:
+            raise ReaderError(
+                "READER_CONTRACT",
+                "peek.reader",
+                "must be an exact (family, version) Reader coordinate",
+            )
+        resolved_coordinate = (
+            identifier(coordinate[0], "peek.reader.family"),
+            semver(coordinate[1], "peek.reader.version"),
+        )
+    return resolved_coordinate, options or {}
+
+
+def _require_reader_result(
+    result: SandboxResult,
+    *,
+    operation: str,
+    family: Any,
+    pin: Mapping[str, Any],
+    options_digest: str,
+    retrieval: bool,
+) -> None:
+    """Bind a sandbox answer to the exact decode the coordinator requested."""
+
+    expected_identity = (
+        family.family_id,
+        family.family_version,
+        options_digest,
+    )
+    returned_identity = (
+        result.decode_family_id,
+        result.decode_family_version,
+        result.decode_options_digest,
+    )
+    if (
+        result.operation != operation
+        or returned_identity != expected_identity
+        or result.decode_flags is None
+        or result.content is None
+        or result.parsed is None
+        or pin.get("family_id") != family.family_id
+        or pin.get("family_version") != family.family_version
+    ):
+        raise AcquisitionSecurityError(
+            "SANDBOX_RESULT",
+            "Reader preview result does not bind the exact requested Reader decode",
+        )
+    if retrieval and (
+        result.fetched_content_sha256 is None
+        or not result.final_url
+        or result.transport_evidence_digest is None
+    ):
+        raise AcquisitionSecurityError(
+            "SANDBOX_RESULT",
+            "Reader URL preview result omits required retrieval evidence",
+        )
+
+
+def _warm_up_reader(sandbox: CrawlerSandbox, family: Any) -> None:
+    """Prove the exact Reader coordinate on its packaged sample through this clean room."""
+
+    def decode(sample: ReaderSample) -> DecodedFacts:
+        sample_pin = ReaderPin(
+            sample.family_id,
+            sample.family_version,
+            dict(sample.decode_options),
+        )
+        result = sandbox.decode_and_parse(
+            request_id=f"peek.warmup.{sample.family_id}.{sample.family_version}".lower(),
+            content=sample.content,
+            reader_pin={
+                "family_id": sample.family_id,
+                "family_version": sample.family_version,
+                "decode_options": dict(sample.decode_options),
+            },
+            output_format=family.output_format,
+            limits=ParseLimits(),
+        )
+        _require_reader_result(
+            result,
+            operation="decode_and_parse",
+            family=family,
+            pin={
+                "family_id": sample.family_id,
+                "family_version": sample.family_version,
+                "decode_options": dict(sample.decode_options),
+            },
+            options_digest=sample_pin.options_digest,
+            retrieval=False,
+        )
+        assert result.content is not None
+        assert result.parsed is not None
+        assert result.decode_flags is not None
+        return DecodedFacts(
+            sha256_bytes(result.content),
+            len(result.parsed.rows),
+            tuple(result.parsed.columns),
+            tuple(result.decode_flags),
+        )
+
+    try:
+        warm_up(family.family_id, family.family_version, decode=decode)
+    except ReaderError as error:
+        # A preview must distinguish "this certified Reader is unavailable on this host" from
+        # "the Reader or source is invalid".  Warm-up intentionally wraps runtime failures for
+        # Build execution, but peek is the capability-inspection surface: preserve the exact
+        # typed platform refusal there so discovery does not misclassify the source as unfit.
+        cause = error.__cause__
+        if isinstance(cause, AcquisitionSecurityError) and cause.code in {
+            "SANDBOX_MEMORY_BOUNDARY",
+            "SANDBOX_OS_BOUNDARY",
+        }:
+            raise cause from error
+        raise
+
+
+def _peek_reader_bytes(
+    content: bytes,
+    *,
+    family: Any,
+    pin: Mapping[str, Any],
+    options_digest: str,
+    limits: ParseLimits,
+    sandbox: CrawlerSandbox,
+) -> ParsedTable:
+    _warm_up_reader(sandbox, family)
+    result = sandbox.decode_and_parse(
+        request_id=f"peek.{family.family_id}.{family.family_version}",
+        content=content,
+        reader_pin=pin,
+        output_format=family.output_format,
+        limits=limits,
+    )
+    _require_reader_result(
+        result,
+        operation="decode_and_parse",
+        family=family,
+        pin=pin,
+        options_digest=options_digest,
+        retrieval=False,
+    )
+    assert result.parsed is not None
+    return result.parsed
+
+
+# ------------------------------------------------------------------------------------------------
+# What a column's type is called
+# ------------------------------------------------------------------------------------------------
+#
+# The Reader reports what it saw in Python's own words -- `str`, `int`, `float`, `int|str`. Those
+# are not words this product uses anywhere else: `mr-data show` prints `string` and `float64`,
+# `mr-data inventory` publishes the same six, and a Recipe accepts only those six. peek is the
+# look-before-you-author step, so an agent that carries a peek answer straight into `author` was
+# being handed a value the Recipe contract rejects, with a refusal that names neither the offending
+# value nor a legal one.
+#
+# So the observed kind is rendered into the product's own column-type vocabulary here. Nothing is
+# inferred or coerced: this is the same fact under the name the rest of the product gives it. A
+# column that holds no single kind, or a kind no Recipe column type covers, is never dressed up as
+# one -- it gets a named marker instead, and the markers are written out below rather than being
+# whatever text happened to come back.
+OBSERVED_LOGICAL_TYPES: dict[str, str] = {
+    "str": "string",
+    "int": "int64",
+    "float": "float64",
+    "bool": "boolean",
+    "date": "date",
+    "datetime": "timestamp_utc",
+}
+
+# `timestamp_utc` is not this product's word for "a timestamp". It is bound to
+# `timestamp[us, tz=UTC]` (`preparation/contracts.PHYSICAL_TYPES`), a Recipe refuses the type
+# unless its declared timezone is UTC (`recipe.py`), and the contract reader accepts only UTC
+# instants. A column of naive timestamps, or of timestamps at some other offset, is none of those
+# -- so reporting `timestamp_utc` for every datetime column asserted UTC about values the sample
+# rows two lines above show are not, and handed an agent a type `author` then refuses.
+#
+# The Reader names the kind after the Python type it rendered, and every ``datetime.datetime``
+# renders under one name, so the zone is read back off the rendered text here. These two markers
+# are observed kinds like any other: no Recipe column type covers them, so
+# :func:`plain_column_type` reports them as exactly that, and a mixed column lists them beside the
+# kinds it holds.
+TIMESTAMP_NO_ZONE = "timestamp with no time zone"
+TIMESTAMP_OTHER_ZONE = "timestamp at an offset other than UTC"
+
+_OBSERVED_DATETIME = "datetime"
+
+# The three answers that are not a column type, spelled out. `null` inside a column that also holds
+# one kind is not one of them: how many values are missing is already its own reported number, so a
+# column of whole numbers with gaps in it is a whole-number column.
+NO_ROWS = "no rows to read"
+ALL_MISSING = "missing in every row"
+MIXED_PREFIX = "mixed: "
+NOT_A_COLUMN_TYPE_PREFIX = "no Recipe column type for this: "
+
+# The literal the Reader uses for a column it saw no rows of, and for an absent value.
+_OBSERVED_EMPTY = "empty"
+_OBSERVED_NULL = "null"
+
+
+def plain_column_type(observed: str) -> str:
+    """The Reader's observed kind, in the vocabulary the rest of the product uses.
+
+    ``observed`` is what :func:`acquisition.parsing.column_types` returns: one Python type name, or
+    several joined by ``|`` for a column holding more than one kind, or ``empty``.
+    """
+
+    if observed == _OBSERVED_EMPTY:
+        return NO_ROWS
+    kinds = [kind for kind in observed.split("|") if kind != _OBSERVED_NULL]
+    if not kinds:
+        return ALL_MISSING
+    named = sorted(
+        OBSERVED_LOGICAL_TYPES[kind] if kind in OBSERVED_LOGICAL_TYPES else kind for kind in kinds
+    )
+    if len(named) > 1:
+        return MIXED_PREFIX + " and ".join(named)
+    if kinds[0] not in OBSERVED_LOGICAL_TYPES:
+        return NOT_A_COLUMN_TYPE_PREFIX + named[0]
+    return named[0]
+
+
+@dataclass(frozen=True)
+class PeekColumn:
+    """One column as it is, before anyone has cleaned it."""
+
+    name: str
+    type: str
+    null_count: int
+    distinct_count: int
+    minimum: str | None
+    maximum: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "type": self.type,
+            "null_count": self.null_count,
+            "distinct_count": self.distinct_count,
+            "minimum": self.minimum,
+            "maximum": self.maximum,
+        }
+
+
+@dataclass(frozen=True)
+class PeekResult:
+    """What one look found: where it looked, what the columns are, and the first rows."""
+
+    source: str
+    origin: str
+    data_format: str
+    input_sha256: str
+    schema_digest: str
+    row_count: int
+    columns: tuple[PeekColumn, ...]
+    sample: tuple[tuple[Any, ...], ...]
+    media_type: str | None = None
+    final_url: str | None = None
+    content_sha256: str | None = None
+    fetched_from: str | None = None
+    note: str | None = None
+    reader_coordinate: str | None = None
+    reader_options_digest: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """The one payload both renderings are built from.
+
+        No key here is taken from the data. A column is called ``column 1`` and carries its real
+        name as a value, and a sample row is the row's values in column order. That is deliberate:
+        the plain rendering gives a payload key its plain label, so a column named ``max_temp_c``
+        used as a key would be shown to a person as ``Max temp c`` -- a name the file does not
+        have. Facts about the data go in values, where nothing rewrites them.
+        """
+
+        payload: dict[str, Any] = {
+            "status": "peeked",
+            "source": self.source,
+            "origin": self.origin,
+            "data_format": self.data_format,
+            "input_sha256": self.input_sha256,
+            "schema_digest": self.schema_digest,
+            "row_count": self.row_count,
+            "columns": [column.name for column in self.columns],
+            "schema": self._schema_payload(),
+            "sample": self._sample_payload(),
+        }
+        if self.origin == "url":
+            payload["url"] = self.final_url
+            payload["fetched_from"] = self.fetched_from
+            payload["content_sha256"] = self.content_sha256
+            if self.media_type is not None:
+                payload["media_type"] = self.media_type
+            payload["saved_to_disk"] = False
+        if self.note is not None:
+            payload["note"] = self.note
+        if self.reader_coordinate is not None:
+            payload["reader_coordinate"] = self.reader_coordinate
+            payload["reader_options_digest"] = self.reader_options_digest
+            payload["reader_execution_status"] = "available"
+        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}": column.to_dict()
+            for index, column in enumerate(self.columns, start=1)
+        }
+
+    def _sample_payload(self) -> dict[str, list[Any]]:
+        """Each row as its values in column order, the way a table has always been written."""
+
+        width = len(str(max(len(self.sample), 1)))
+        return {
+            f"row {index:0{width}d}": [_json_safe(value) for value in row]
+            for index, row in enumerate(self.sample, start=1)
+        }
+
+
+def peek_bytes(
+    content: bytes,
+    *,
+    filename: str,
+    data_format: str | None = None,
+    sample_rows: int = DEFAULT_SAMPLE_ROWS,
+    limits: ParseLimits | None = None,
+    source: str | None = None,
+    reader_coordinate: tuple[str, str] | None = None,
+    reader_options: Mapping[str, Any] | None = None,
+    reader_sandbox: CrawlerSandbox | None = None,
+) -> PeekResult:
+    """Look at exact bytes. The only byte reader in this module, by design."""
+
+    reader_coordinate, reader_options = _normalise_reader_request(
+        reader_coordinate, reader_options, data_format
+    )
+    rows_wanted = _bounded_sample_rows(sample_rows)
+    original_sha256 = sha256_bytes(content)
+    resolved_reader_coordinate = None
+    reader_options_digest = None
+    if reader_options is not None:
+        family, pin, reader_options_digest = _reader_pin(reader_coordinate, reader_options)
+        resolved_reader_coordinate = f"{family.family_id}@{family.family_version}"
+        if reader_sandbox is not None:
+            table = _peek_reader_bytes(
+                content,
+                family=family,
+                pin=pin,
+                options_digest=reader_options_digest,
+                limits=limits or ParseLimits(),
+                sandbox=reader_sandbox,
+            )
+        else:
+            with tempfile.TemporaryDirectory(prefix="mr-peek-reader-") as temporary:
+                table = _peek_reader_bytes(
+                    content,
+                    family=family,
+                    pin=pin,
+                    options_digest=reader_options_digest,
+                    limits=limits or ParseLimits(),
+                    sandbox=_reader_sandbox(Path(temporary).resolve()),
+                )
+    else:
+        resolved_format, media_type = _format_for(filename, data_format)
+        table = parse_tabular_bytes_for_display(
+            content,
+            data_format=resolved_format,
+            media_type=media_type,
+            filename=filename,
+            limits=limits or ParseLimits(),
+        )
+    return PeekResult(
+        source=source if source is not None else filename,
+        origin="file",
+        data_format=table.data_format,
+        input_sha256=original_sha256,
+        schema_digest=table.schema_digest,
+        row_count=len(table.rows),
+        columns=_summarise(table),
+        sample=table.rows[:rows_wanted],
+        reader_coordinate=resolved_reader_coordinate if reader_options is not None else None,
+        reader_options_digest=reader_options_digest,
+    )
+
+
+def peek_path(
+    path: Path | str,
+    *,
+    data_format: str | None = None,
+    sample_rows: int = DEFAULT_SAMPLE_ROWS,
+    limits: ParseLimits | None = None,
+    reader_coordinate: tuple[str, str] | None = None,
+    reader_options: Mapping[str, Any] | None = None,
+    reader_sandbox: CrawlerSandbox | None = None,
+) -> PeekResult:
+    """Look at one file on this machine.
+
+    The size is checked before the bytes are loaded, so a file too large to open is refused rather
+    than read into memory first -- and it is checked on the open descriptor, through
+    :mod:`ux.plain_file`, which is the rule the rest of this tree opens anything with. Asking the
+    path instead got two answers wrong at once. ``st_size`` is 0 for a pipe and a character device,
+    so the cap governed nothing there, and ``Path.is_file`` is false for both, so a peek at either
+    one was refused with the sentence written for a folder -- a statement about what is at the path
+    that is simply not true, and advice ("check the spelling") aimed at a caller who typed the path
+    they meant. The bound also has to govern the read that follows it, so a file that grows between
+    the two is caught by the read rather than trusted from a moment earlier.
+    """
+
+    reader_coordinate, reader_options = _normalise_reader_request(
+        reader_coordinate, reader_options, data_format
+    )
+    target = Path(path)
+    rows_wanted = _bounded_sample_rows(sample_rows)
+    budgets = limits or ParseLimits()
+    try:
+        descriptor, size = open_plain_file(target)
+    except PlainFileRefusal as refusal:
+        # Two codes rather than two wordings of one, because the two findings contradict each
+        # other: `PEEK_TARGET` says nothing is there and tells the caller to check the spelling,
+        # which is advice about a mistake somebody pointing at a real pipe did not make.
+        # `OUTPUT_PARENT_ABSENT` and `OUTPUT_PARENT_INVALID` are two codes for the same reason.
+        # Raised here rather than returned from a helper: the sweep that proves every typed code
+        # names its fix reads `raise` statements out of the live source.
+        if refusal.reason == DANGLING:
+            # A dangling link is present even though opening its target raises
+            # `FileNotFoundError`, so it must not be translated as an absent input. The noun comes
+            # from the `st_mode` retained from the non-following lookup, keeping the sentence and
+            # finding bound to one observation.
+            raise AcquisitionSecurityError(
+                "PEEK_TARGET_DANGLING",
+                f"there is {name_of_kind(refusal.mode) or UNKNOWN_KIND} at {refusal.path}, "
+                "and it leads nowhere",
+            ) from None
+        if refusal.reason == MISSING:
+            raise AcquisitionSecurityError(
+                "PEEK_TARGET",
+                f"there is {presence_at(target) or UNKNOWN_KIND} at {target} to look at",
+            ) from None
+        raise AcquisitionSecurityError(
+            "PEEK_TARGET_NOT_A_FILE",
+            f"{target} is not a file: a peek reads a file, not a folder, a pipe, or a device",
+        ) from None
+    try:
+        # Resolve the format before the read as well, so an unreadable file is named as unreadable
+        # rather than loaded and then refused. Opening the descriptor has loaded nothing yet.
+        if reader_options is None:
+            _format_for(target.name, data_format)
+        if size > budgets.max_input_bytes:
+            raise AcquisitionSecurityError(
+                "PEEK_SIZE",
+                f"{target} holds {size} bytes, above the {budgets.max_input_bytes} byte "
+                "limit on anything this harness opens",
+            )
+        content = read_bounded(descriptor, max_bytes=budgets.max_input_bytes)
+    finally:
+        os.close(descriptor)
+    if len(content) > budgets.max_input_bytes:
+        raise AcquisitionSecurityError(
+            "PEEK_SIZE",
+            f"{target} holds more than {budgets.max_input_bytes} bytes, above the limit on "
+            "anything this harness opens",
+        )
+    return peek_bytes(
+        content,
+        filename=target.name,
+        data_format=data_format,
+        sample_rows=rows_wanted,
+        limits=budgets,
+        source=str(target),
+        reader_coordinate=reader_coordinate,
+        reader_options=reader_options,
+        reader_sandbox=reader_sandbox,
+    )
+
+
+def peek_url(
+    url: str,
+    *,
+    allow_redirect_hosts: tuple[str, ...] = (),
+    data_format: str | None = None,
+    sample_rows: int = DEFAULT_SAMPLE_ROWS,
+    limits: ParseLimits | None = None,
+    transport: PinnedTransport | None = None,
+    resolver: Resolver | None = None,
+    reader_coordinate: tuple[str, str] | None = None,
+    reader_options: Mapping[str, Any] | None = None,
+    reader_sandbox: CrawlerSandbox | None = None,
+) -> PeekResult:
+    """Fetch one public https address and look at what came back, saving nothing.
+
+    The fetch goes through the harness's one Courier: the same address validation, the same
+    pinned-peer connection, the same redirect and byte budgets a Recipe's own fetches use. Nothing
+    here widens that; the only thing peek supplies is which single host is allowed.
+
+    ``transport`` and ``resolver`` exist so a test can hand in a recorded exchange instead of
+    reaching the network. Neither is reachable from the command line.
+    """
+
+    reader_coordinate, reader_options = _normalise_reader_request(
+        reader_coordinate, reader_options, data_format
+    )
+    rows_wanted = _bounded_sample_rows(sample_rows)
+    hostname = _hostname_of(url)
+    # The allowlist of one is derived from an explicit argument -- the address the person or their
+    # agent typed -- and never from a config file and never from the content of a source. That is
+    # what keeps the fail-closed egress model intact: peek narrows it to a single host rather than
+    # widening it, and `--allow-redirect-host` names any further host explicitly. Every entry
+    # is written in the egress rule's own spelling, the named host and the redirect hosts alike:
+    # an entry spelled any other way is either refused as non-canonical or silently never matched.
+    allowed_hostnames = (
+        hostname,
+        *(_normalize_hostname(host) for host in allow_redirect_hosts),
+    )
+    if reader_options is not None:
+        family, pin, reader_options_digest = _reader_pin(reader_coordinate, reader_options)
+        budgets = limits or ParseLimits()
+
+        def retrieve(sandbox: CrawlerSandbox) -> PeekResult:
+            _warm_up_reader(sandbox, family)
+            result = sandbox.retrieve_decode_and_parse(
+                request_id=f"peek.url.{family.family_id}.{family.family_version}",
+                url=url,
+                allowed_hostnames=allowed_hostnames,
+                reader_pin=pin,
+                output_format=family.output_format,
+                parse_limits=budgets,
+                retrieval_limits=reader_retrieval_limits(
+                    RetrievalLimits(),
+                    family_id=family.family_id,
+                    family_version=family.family_version,
+                ),
+            )
+            _require_reader_result(
+                result,
+                operation="retrieve_decode_and_parse",
+                family=family,
+                pin=pin,
+                options_digest=reader_options_digest,
+                retrieval=True,
+            )
+            assert result.parsed is not None
+            assert result.fetched_content_sha256 is not None
+            return PeekResult(
+                source=url,
+                origin="url",
+                data_format=result.parsed.data_format,
+                input_sha256=result.fetched_content_sha256,
+                schema_digest=result.parsed.schema_digest,
+                row_count=len(result.parsed.rows),
+                columns=_summarise(result.parsed),
+                sample=result.parsed.rows[:rows_wanted],
+                # The combined clean-room result exposes the normalized CSV media type, not the
+                # original response header. Do not fabricate source metadata from decode settings.
+                media_type=None,
+                final_url=result.final_url,
+                content_sha256=result.fetched_content_sha256,
+                fetched_from=hostname,
+                note=(
+                    f"The fetched media type was enforced against {family.family_id}@"
+                    f"{family.family_version} inside the "
+                    "clean room; the original response header is not returned by that operation."
+                ),
+                reader_coordinate=f"{family.family_id}@{family.family_version}",
+                reader_options_digest=reader_options_digest,
+            )
+
+        if reader_sandbox is not None:
+            return retrieve(reader_sandbox)
+        with tempfile.TemporaryDirectory(prefix="mr-peek-reader-") as temporary:
+            return retrieve(_reader_sandbox(Path(temporary).resolve()))
+
+    policy = EgressPolicy(allowed_hostnames=allowed_hostnames)
+    retriever = PinnedHttpsRetriever(
+        resolver=resolver if resolver is not None else SystemResolver(),
+        egress_policy=policy,
+        transport=transport if transport is not None else StdlibPinnedTransport(),
+        limits=RetrievalLimits(),
+    )
+    retrieved = retriever.retrieve(url)
+    resolved_format, filename, note = _format_for_response(
+        final_url=retrieved.final_url,
+        media_type=retrieved.media_type,
+        declared=data_format,
+    )
+    result = peek_bytes(
+        retrieved.content,
+        filename=filename,
+        data_format=resolved_format,
+        sample_rows=rows_wanted,
+        limits=limits,
+        reader_coordinate=reader_coordinate,
+        reader_options=reader_options,
+    )
+    return replace(
+        result,
+        source=url,
+        origin="url",
+        media_type=retrieved.media_type,
+        final_url=retrieved.final_url,
+        content_sha256=retrieved.content_sha256,
+        fetched_from=hostname,
+        note=note,
+    )
+
+
+def _hostname_of(url: str) -> str:
+    """The hostname to build the allowlist from. Validating the address is not this job.
+
+    ``validate_public_https_url`` is the validator, and it runs on every hop inside the Courier.
+    Reading the host out here is only how the allowlist gets its single entry, so anything odd
+    about the address is still refused there rather than quietly accepted here.
+
+    The spelling is the egress rule's own: ``_normalize_hostname`` is what ``EgressPolicy`` measures
+    an entry against and what the validator normalizes every hop to, so this allowlist of one is
+    written in the same spelling it will later be compared in. Lower-casing the host here instead
+    was a second rule that agreed with that one on ordinary addresses and disagreed on two:
+    an internationalized address (whose entry was refused as non-canonical before a byte was
+    fetched) and a trailing-dot name (whose entry was stored unnormalized and never matched), both
+    turned away with a message about an allowlist a `peek` invocation does not have.
+    """
+
+    try:
+        hostname = urlsplit(url).hostname
+    except ValueError:
+        hostname = None
+    if not hostname:
+        raise AcquisitionSecurityError(
+            "PEEK_TARGET",
+            f"{url} is not an address with a host in it",
+        )
+    return _normalize_hostname(hostname)
+
+
+def _format_for_response(
+    *,
+    final_url: str,
+    media_type: str,
+    declared: str | None,
+) -> tuple[str, str, str | None]:
+    """Decide what was served, and name a file the Reader's own suffix check can look at.
+
+    Order: what the caller said, then what the server said it was serving, then the name at the
+    end of the address. The media type only picks which Reader opens the bytes; that Reader then
+    re-checks the magic bytes, the encoding, and the budgets, so a content type that lies gets a
+    refusal rather than a wrong reading.
+    """
+
+    basename = _basename_of(final_url)
+    suffix_format = _SUFFIX_FORMATS.get(_suffix_of(basename))
+    data_format = declared or _MEDIA_FORMATS.get(media_type) or suffix_format
+    if data_format is None:
+        raise AcquisitionSecurityError("PEEK_FORMAT", _unreadable(final_url))
+    if data_format not in PEEK_FORMATS:
+        raise AcquisitionSecurityError("PEEK_FORMAT", _unreadable(data_format))
+    if suffix_format is not None:
+        # The address names a file, so the Reader checks that name against the bytes as usual.
+        return data_format, basename, None
+    stand_in = f"download{_suffix_for(data_format)}"
+    reason = (
+        f"the server did not name a file, so this was read as {data_format} "
+        f"because that is what the media type ({media_type}) says it is"
+    )
+    return data_format, stand_in, reason
+
+
+def _basename_of(url: str) -> str:
+    return urlsplit(url).path.rsplit("/", 1)[-1]
+
+
+def _suffix_for(data_format: str) -> str:
+    """The suffix the Reader accepts for this format, taken from the Reader's own table."""
+
+    return min(_FORMAT_SUFFIXES[data_format])
+
+
+def _summarise(table: ParsedTable) -> tuple[PeekColumn, ...]:
+    """One :class:`PeekColumn` per column, over rows the Reader has already bounded."""
+
+    types = column_types(table)
+    columns: list[PeekColumn] = []
+    for index, name in enumerate(table.columns):
+        values = [row[index] for row in table.rows]
+        present = [value for value in values if value is not None]
+        minimum, maximum = _extremes(present)
+        columns.append(
+            PeekColumn(
+                name=name,
+                type=plain_column_type(_zoned(types[index], present)),
+                null_count=len(values) - len(present),
+                distinct_count=_distinct(present),
+                minimum=minimum,
+                maximum=maximum,
+            )
+        )
+    return tuple(columns)
+
+
+def _zoned(observed: str, values: list[Any]) -> str:
+    """``observed`` with its ``datetime`` kind replaced by what the values say about the zone.
+
+    Nothing is inferred and nothing is refused: the rendered text of a ``datetime.datetime`` is its
+    own ``isoformat``, and reading it back with ``datetime.fromisoformat`` -- the inverse of the
+    call that wrote it -- answers whether the value carried a zone and whether that zone was UTC.
+    A column whose datetimes do not all agree on UTC is reported as the kind it is, which is one no
+    Recipe column type covers. Text that will not read back is treated the same way: this says what
+    the column is, and ``timestamp_utc`` is a claim, not a default.
+    """
+
+    if _OBSERVED_DATETIME not in observed.split("|"):
+        return observed
+    for value in values:
+        if type(value).__name__ != _OBSERVED_DATETIME:
+            continue
+        offset = _utc_offset(str(value))
+        if offset is None:
+            return observed.replace(_OBSERVED_DATETIME, TIMESTAMP_NO_ZONE)
+        if offset != timedelta(0):
+            return observed.replace(_OBSERVED_DATETIME, TIMESTAMP_OTHER_ZONE)
+    return observed
+
+
+def _utc_offset(text: str) -> timedelta | None:
+    """The offset from UTC the rendered timestamp carries, or ``None`` when it carries none."""
+
+    try:
+        return datetime.fromisoformat(text).utcoffset()
+    except ValueError:
+        return None
+
+
+def _extremes(values: list[Any]) -> tuple[str | None, str | None]:
+    """The lowest and highest value, or nothing at all when they cannot be ordered.
+
+    A column holding more than one kind of value has no order, and saying so is more honest than
+    inventing one. It is never a refusal: unclean data is exactly what peek is for.
+    """
+
+    if not values:
+        return None, None
+    try:
+        ordered = sorted(values)
+    except TypeError:
+        return None, None
+    return str(ordered[0]), str(ordered[-1])
+
+
+def _distinct(values: list[Any]) -> int:
+    """How many different values a column holds, counting only the ones that are there."""
+
+    try:
+        return len(set(values))
+    except TypeError:
+        return len({repr(value) for value in values})
+
+
+def _bounded_sample_rows(sample_rows: int) -> int:
+    if type(sample_rows) is not int or not 0 <= sample_rows <= MAX_SAMPLE_ROWS:
+        raise AcquisitionSecurityError(
+            "PEEK_SAMPLE",
+            f"the number of rows to show must be a whole number from 0 to {MAX_SAMPLE_ROWS}",
+        )
+    return sample_rows
+
+
+def _format_for(filename: str, declared: str | None) -> tuple[str, str]:
+    """Pick the format and the media type that agree with the Reader's own allowlists."""
+
+    if declared is not None:
+        if declared not in PEEK_FORMATS:
+            raise AcquisitionSecurityError("PEEK_FORMAT", _unreadable(declared))
+        return declared, _media_type_for(declared)
+    data_format = _SUFFIX_FORMATS.get(_suffix_of(filename))
+    if data_format is None:
+        raise AcquisitionSecurityError("PEEK_FORMAT", _unreadable(filename))
+    return data_format, _media_type_for(data_format)
+
+
+def _media_type_for(data_format: str) -> str:
+    """The media type the Reader expects for this format, taken from the Reader's own table."""
+
+    return min(_FORMAT_MEDIA_TYPES[data_format])
+
+
+def _suffix_of(filename: str) -> str:
+    dot = filename.rfind(".")
+    return filename[dot:].lower() if dot > 0 else ""
+
+
+def _unreadable(subject: str) -> str:
+    return (
+        f"{subject} is not one of the formats this build can read ({_READABLE}); "
+        "the set of readable formats grows as Readers are certified"
+    )
+
+
+def _json_safe(value: Any) -> Any:
+    """Keep a cell as it is when it is already a plain value; otherwise show it as written.
+
+    A rendered value arrives here as a ``str`` subclass carrying the name of the kind it came from.
+    That name is a fact about the column and it is already reported there; on the value itself it
+    would only be a type nobody asked about, so the text is handed on as plain text.
+    """
+
+    if isinstance(value, str):
+        return str(value)
+    if value is None or isinstance(value, bool | int):
+        return value
+    if isinstance(value, float):
+        return value if math.isfinite(value) else str(value)
+    return str(value)
+
+
+__all__ = [
+    "ALL_MISSING",
+    "DEFAULT_SAMPLE_ROWS",
+    "MAX_SAMPLE_ROWS",
+    "MIXED_PREFIX",
+    "NOT_A_COLUMN_TYPE_PREFIX",
+    "NO_ROWS",
+    "OBSERVED_LOGICAL_TYPES",
+    "PEEK_FORMATS",
+    "PeekColumn",
+    "PeekResult",
+    "peek_bytes",
+    "peek_path",
+    "peek_url",
+    "plain_column_type",
+]