mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/acquisition/parsing.py

@@ -0,0 +1,809 @@
+"""Closed, bounded parsers for untrusted tabular source bytes."""
+
+from __future__ import annotations
+
+import csv
+import datetime
+import decimal
+import hashlib
+import io
+import json
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from mostlyright.data_harness.acquisition.url_policy import AcquisitionSecurityError
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    sha256_bytes,
+)
+from mostlyright.data_harness.formats import (
+    ARCHIVE_OR_EXECUTABLE_MAGICS,
+    DIRECT_FETCH_MEDIA_TYPES,
+    FORMAT_MEDIA_TYPES,
+    FORMAT_SUFFIXES,
+)
+
+# Read from the single closed table in ``mostlyright.data_harness.formats``; this module
+# keeps the private names it has always used so its call sites are unchanged.
+_FORMAT_MEDIA_TYPES = FORMAT_MEDIA_TYPES
+# The parse admits what the fetch admitted: a direct fetch may carry the weak label, so
+# refusing it here would refuse at the parse exactly what was just let through the door.
+_ADMITTED_MEDIA_TYPES = DIRECT_FETCH_MEDIA_TYPES
+_FORMAT_SUFFIXES = FORMAT_SUFFIXES
+# The archive prefixes are read from the leaf too, for the reason recorded beside them there:
+# the container Readers refuse a nested archive on the same list, ``readers/`` may not import
+# this module, and two copies of what an archive looks like would drift.
+_ARCHIVE_OR_EXECUTABLE_MAGICS = ARCHIVE_OR_EXECUTABLE_MAGICS
+_FORBIDDEN_REFERENCE_KEYS = frozenset(
+    {"$ref", "$schema", "external_reference", "external_references"}
+)
+_SAFE_COLUMN = re.compile(r"^[^\x00-\x1f\x7f]{1,256}$")
+
+
+# PyArrow is imported on first Parquet use, never at module import. It is the single most
+# expensive import in the sandbox worker's dependency graph -- around 50 ms of the ~110 ms this
+# module used to add to a child interpreter's startup, and every millisecond of it is paid by
+# every sandbox child, including the ones that only probe isolation or parse a CSV. Deferring it
+# costs one dictionary lookup per Parquet parse and gives the operations that never touch Parquet
+# a child that starts in roughly half the time. The module object is cached rather than re-bound
+# into module globals so there is exactly one place that decides whether the import has happened.
+_PYARROW: tuple[Any, Any] | None = None
+
+
+def _pyarrow() -> tuple[Any, Any]:
+    """Return ``(pyarrow, pyarrow.parquet)``, importing them on first use."""
+
+    global _PYARROW
+    if _PYARROW is None:
+        import pyarrow
+        import pyarrow.parquet
+
+        _PYARROW = (pyarrow, pyarrow.parquet)
+    return _PYARROW
+
+
+def prime_parquet_support() -> None:
+    """Pay the deferred PyArrow import now, before any request is bound.
+
+    The lazy import above moves the cost off every child that does not parse Parquet; this
+    moves it off the request latency of the children that do. A warm sandbox child calls this
+    while it is still idle and unbound, so the first Parquet parse it is later asked for pays
+    an already-imported module rather than a cold one. Nothing else about the child changes:
+    priming reads no request, opens no socket, and touches no per-request state.
+    """
+
+    _pyarrow()
+
+
+@dataclass(frozen=True)
+class ParseLimits:
+    """Coordinator-owned parser budgets."""
+
+    max_input_bytes: int = 16 * 1024 * 1024
+    max_uncompressed_bytes: int = 128 * 1024 * 1024
+    max_expansion_ratio: int = 100
+    max_rows: int = 1_000_000
+    max_columns: int = 1_024
+    max_field_bytes: int = 1 * 1024 * 1024
+    max_json_depth: int = 32
+    max_total_cells: int = 10_000_000
+
+    def __post_init__(self) -> None:
+        bounded = (
+            ("max_input_bytes", self.max_input_bytes, 1, 1 << 34),
+            ("max_uncompressed_bytes", self.max_uncompressed_bytes, 1, 1 << 36),
+            ("max_expansion_ratio", self.max_expansion_ratio, 1, 10_000),
+            ("max_rows", self.max_rows, 1, 10_000_000),
+            ("max_columns", self.max_columns, 1, 10_000),
+            ("max_field_bytes", self.max_field_bytes, 1, 1 << 30),
+            ("max_json_depth", self.max_json_depth, 1, 128),
+            ("max_total_cells", self.max_total_cells, 1, 1_000_000_000),
+        )
+        for name, value, minimum, maximum in bounded:
+            if type(value) is not int or not minimum <= value <= maximum:
+                raise AcquisitionSecurityError(
+                    "PARSE_LIMIT",
+                    f"{name} must be an integer in [{minimum}, {maximum}]",
+                )
+        if self.max_uncompressed_bytes < self.max_input_bytes:
+            raise AcquisitionSecurityError(
+                "PARSE_LIMIT",
+                "max_uncompressed_bytes must not be smaller than max_input_bytes",
+            )
+
+
+@dataclass(frozen=True)
+class ParsedTable:
+    """Immutable, source-independent parsed tabular result."""
+
+    data_format: str
+    input_sha256: str
+    columns: tuple[str, ...]
+    rows: tuple[tuple[Any, ...], ...]
+    schema_digest: str
+
+    def __post_init__(self) -> None:
+        if self.data_format not in _FORMAT_MEDIA_TYPES:
+            raise AcquisitionSecurityError("PARSE_FORMAT", "parsed format is not allowlisted")
+        if not self.columns or len(set(self.columns)) != len(self.columns):
+            raise AcquisitionSecurityError(
+                "PARSE_COLUMNS",
+                "parsed columns must be non-empty and unique",
+            )
+        if any(len(row) != len(self.columns) for row in self.rows):
+            raise AcquisitionSecurityError(
+                "PARSE_ROW_WIDTH",
+                "parsed row width differs from the schema",
+            )
+        expected = canonical_sha256(
+            {
+                "data_format": self.data_format,
+                "columns": list(self.columns),
+                "types": [_column_type(self.rows, index) for index in range(len(self.columns))],
+            }
+        )
+        if expected != self.schema_digest:
+            raise AcquisitionSecurityError(
+                "PARSE_SCHEMA_DIGEST",
+                "parsed schema digest does not match the exact result",
+            )
+
+    def dictionaries(self) -> tuple[dict[str, Any], ...]:
+        return tuple(dict(zip(self.columns, row, strict=True)) for row in self.rows)
+
+
+def parse_tabular_bytes(
+    content: bytes,
+    *,
+    data_format: str,
+    media_type: str,
+    filename: str,
+    limits: ParseLimits,
+) -> ParsedTable:
+    """Parse one allowlisted format after exact media/suffix and budget validation.
+
+    Every value that comes back is one the canonical rule can hold exactly. A temporal, decimal, or
+    non-finite value is refused with ``PARSE_VALUE`` rather than turned into text, because what
+    this function returns can be sealed and a value nobody can round-trip must not be.
+    """
+
+    return _parse_tabular(
+        content,
+        data_format=data_format,
+        media_type=media_type,
+        filename=filename,
+        limits=limits,
+        display=False,
+    )
+
+
+def parse_tabular_bytes_for_display(
+    content: bytes,
+    *,
+    data_format: str,
+    media_type: str,
+    filename: str,
+    limits: ParseLimits,
+) -> ParsedTable:
+    """The same parse, for bytes that are being looked at rather than built from.
+
+    Identical in every guard: the same media, suffix, magic-byte, encoding, row, column, cell,
+    field, and decompression budgets, in the same order, from the same code. One thing differs.
+    Where :func:`parse_tabular_bytes` refuses a value the canonical rule has no place for -- a
+    date, a time, a duration, a decimal, a not-a-number -- this one renders it into its exact text
+    and carries on, so a column of dates can be *shown* rather than refused.
+
+    That is safe here and only here, because nothing this function returns is ever sealed. It has
+    exactly one caller, ``ux.peek``, which writes no bytes at all; ``tests/h3/test_parsing.py``
+    pins that there is no second one. Exactness is kept by
+    the rendering rather than by the refusal: the text is the value's own ``isoformat`` or ``str``,
+    never a rounding, and the type of column a person is told about is unchanged -- a rendered
+    ``date`` is still reported as a ``date``, because the text carries the name of the kind it came
+    from.
+    """
+
+    return _parse_tabular(
+        content,
+        data_format=data_format,
+        media_type=media_type,
+        filename=filename,
+        limits=limits,
+        display=True,
+    )
+
+
+def row_digest_for(parsed: ParsedTable) -> str:
+    """Return the canonical row digest of one drained parsed table.
+
+    The one formula, in one place.  ``parse_csv_evidence`` accumulates the identical encoding a
+    row at a time for tables too large to hold, and the two are pinned equal by test; a second
+    spelling of it anywhere would be a second digest that could disagree with sealed evidence.
+    """
+
+    return sha256_bytes(
+        canonical_json_bytes(
+            {
+                "columns": list(parsed.columns),
+                "rows": [list(row) for row in parsed.rows],
+            }
+        )
+    )
+
+
+@dataclass(frozen=True)
+class ParsedTabularEvidence:
+    """The facts a receipt states about a parsed table, without the table.
+
+    ``parse_csv_evidence`` computes exactly what ``parse_tabular_bytes`` would have put in
+    a receipt -- the columns, the row count, the schema digest, and the canonical row
+    digest -- while holding one row at a time.  A year-scale verification pass therefore
+    costs the size of a row, not the size of the table; the values are pinned equal to the
+    drained parse by test, because a digest that moved would move every sealed receipt.
+    """
+
+    data_format: str
+    input_sha256: str
+    columns: tuple[str, ...]
+    row_count: int
+    schema_digest: str
+    row_digest: str
+
+
+def parse_csv_evidence(
+    content: bytes,
+    *,
+    media_type: str,
+    filename: str,
+    limits: ParseLimits,
+) -> ParsedTabularEvidence:
+    """Stream one CSV verification pass: the admissions of the drained parse, row by row.
+
+    The refusals are ``_parse_csv``'s own, at the same rows, in the same order.  The one
+    check the drained path could only make after the loop -- the total-cell budget that
+    ``_validate_table`` applies to the whole table -- keeps that position: the flag is
+    raised at the end of the input, so a malformed row later in the file still wins.
+
+    The row digest is fed to the hash incrementally as the canonical encoding of
+    ``{"columns": [...], "rows": [[...], ...]}``.  The framing bytes are literal because
+    the canonical encoder is compositional -- sorted keys, no spaces, context-free element
+    encoding -- and the equality with the one-shot encoding is pinned by test rather than
+    assumed.
+    """
+
+    _admit_tabular_input(content, data_format="csv", media_type=media_type, filename=filename)
+    if not content or len(content) > limits.max_input_bytes:
+        raise AcquisitionSecurityError(
+            "PARSE_INPUT_LIMIT",
+            "source bytes are empty or exceed the parser input budget",
+        )
+    if any(content.startswith(magic) for magic in _ARCHIVE_OR_EXECUTABLE_MAGICS):
+        raise AcquisitionSecurityError(
+            "PARSE_FORBIDDEN_CONTAINER",
+            "archives, executables, documents, and nested containers are forbidden",
+        )
+    text = _strict_utf8(content)
+    if "\x00" in text:
+        raise AcquisitionSecurityError("PARSE_ENCODING", "CSV contains a NUL byte")
+    reader = csv.reader(
+        io.StringIO(text, newline=""),
+        delimiter=",",
+        quotechar='"',
+        doublequote=True,
+        strict=True,
+    )
+    try:
+        header = next(reader)
+    except (StopIteration, csv.Error):
+        raise AcquisitionSecurityError("PARSE_CSV", "CSV has no valid header") from None
+    columns = _columns(header, limits)
+    width = len(columns)
+
+    row_hash = hashlib.sha256()
+    row_hash.update(b'{"columns":' + canonical_json_bytes(list(columns)) + b',"rows":[')
+    observed_types: list[set[str]] = [set() for _ in range(width)]
+    row_count = 0
+    over_cell_budget = False
+    canonical_error: CanonicalJSONError | None = None
+    try:
+        for raw in reader:
+            if row_count >= limits.max_rows:
+                raise AcquisitionSecurityError("PARSE_ROW_LIMIT", "CSV exceeds the row budget")
+            if len(raw) != width:
+                raise AcquisitionSecurityError(
+                    "PARSE_ROW_WIDTH",
+                    "CSV row width differs from its header",
+                )
+            row = tuple(raw)
+            _validate_row(row, limits)
+            if (row_count + 1) * width > limits.max_total_cells:
+                over_cell_budget = True
+            # A cell the canonical encoder refuses -- reachable only if the process-wide
+            # ``csv.field_size_limit`` is raised above the canonical string bound -- keeps
+            # the position the one-shot digest gave it: after every parse refusal and the
+            # cell budget, never mid-loop.  The hash is dead on that path, so it stops
+            # accumulating with the first error.
+            if canonical_error is None:
+                try:
+                    encoded_row = canonical_json_bytes(list(row))
+                except CanonicalJSONError as error:
+                    canonical_error = error
+                else:
+                    if row_count:
+                        row_hash.update(b",")
+                    row_hash.update(encoded_row)
+            for index, value in enumerate(row):
+                observed_types[index].add("null" if value is None else type(value).__name__)
+            row_count += 1
+    except csv.Error:
+        raise AcquisitionSecurityError("PARSE_CSV", "CSV syntax is malformed") from None
+    if over_cell_budget:
+        raise AcquisitionSecurityError("PARSE_CELL_LIMIT", "table exceeds the cell budget")
+    if canonical_error is not None:
+        raise canonical_error
+    row_hash.update(b"]}")
+
+    schema_digest = canonical_sha256(
+        {
+            "data_format": "csv",
+            "columns": list(columns),
+            "types": [
+                "|".join(sorted(observed)) if observed else "empty" for observed in observed_types
+            ],
+        }
+    )
+    return ParsedTabularEvidence(
+        data_format="csv",
+        input_sha256=sha256_bytes(content),
+        columns=columns,
+        row_count=row_count,
+        schema_digest=schema_digest,
+        row_digest=row_hash.hexdigest(),
+    )
+
+
+def _admit_tabular_input(
+    content: bytes,
+    *,
+    data_format: str,
+    media_type: str,
+    filename: str,
+) -> None:
+    """The input admissions every tabular parse makes, in the order it makes them."""
+
+    if not isinstance(content, bytes):
+        raise AcquisitionSecurityError("PARSE_INPUT", "parser input must be exact bytes")
+    if data_format not in _FORMAT_MEDIA_TYPES:
+        raise AcquisitionSecurityError("PARSE_FORMAT", "data format is not allowlisted")
+    normalized_media = media_type.split(";", 1)[0].strip().lower()
+    if normalized_media not in _ADMITTED_MEDIA_TYPES[data_format]:
+        raise AcquisitionSecurityError(
+            "PARSE_MEDIA_MISMATCH",
+            "declared media type does not match the selected parser",
+        )
+    suffix = _suffix(filename)
+    if suffix not in _FORMAT_SUFFIXES[data_format]:
+        raise AcquisitionSecurityError(
+            "PARSE_SUFFIX_MISMATCH",
+            "filename suffix does not match the selected parser",
+        )
+
+
+def _parse_tabular(
+    content: bytes,
+    *,
+    data_format: str,
+    media_type: str,
+    filename: str,
+    limits: ParseLimits,
+    display: bool,
+) -> ParsedTable:
+    _admit_tabular_input(content, data_format=data_format, media_type=media_type, filename=filename)
+    if not content or len(content) > limits.max_input_bytes:
+        raise AcquisitionSecurityError(
+            "PARSE_INPUT_LIMIT",
+            "source bytes are empty or exceed the parser input budget",
+        )
+    if any(content.startswith(magic) for magic in _ARCHIVE_OR_EXECUTABLE_MAGICS):
+        raise AcquisitionSecurityError(
+            "PARSE_FORBIDDEN_CONTAINER",
+            "archives, executables, documents, and nested containers are forbidden",
+        )
+
+    # Exhaustive over the format table, with no catch-all decoder.  The admission checks
+    # above read ``mostlyright.data_harness.formats``, so widening that table admits a name
+    # here too; if the last branch were ``else: _parse_parquet(...)`` the new name's bytes
+    # would be handed to the Parquet reader, and the ``ParsedTable`` and its
+    # ``schema_digest`` -- which folds ``data_format`` in -- would then attest a decoder
+    # that never ran.  A format the table admits and no branch claims is refused here
+    # instead, naming itself, so adding a Reader family to ``formats.py`` is a loud failure
+    # until a decoder is taught to honour it rather than a silent misparse.
+    if data_format == "csv":
+        columns, rows = _parse_csv(content, limits)
+    elif data_format in {"json", "ndjson"}:
+        columns, rows = _parse_json(content, data_format, limits)
+    elif data_format == "parquet":
+        columns, rows = _parse_parquet(content, limits, display=display)
+    else:
+        raise AcquisitionSecurityError(
+            "PARSE_FORMAT_UNHANDLED",
+            f"data format {data_format!r} is in the format table but no decoder claims it",
+        )
+    _validate_table(columns, rows, limits)
+    schema_digest = canonical_sha256(
+        {
+            "data_format": data_format,
+            "columns": list(columns),
+            "types": [_column_type(rows, index) for index in range(len(columns))],
+        }
+    )
+    return ParsedTable(
+        data_format=data_format,
+        input_sha256=sha256_bytes(content),
+        columns=columns,
+        rows=rows,
+        schema_digest=schema_digest,
+    )
+
+
+def column_types(table: ParsedTable) -> tuple[str, ...]:
+    """Return the observed type of each column, in column order.
+
+    This is the exact list the schema digest already commits to, so it exposes a sealed fact
+    rather than inferring a new one.
+    """
+
+    return tuple(_column_type(table.rows, index) for index in range(len(table.columns)))
+
+
+def _parse_csv(
+    content: bytes,
+    limits: ParseLimits,
+) -> tuple[tuple[str, ...], tuple[tuple[Any, ...], ...]]:
+    text = _strict_utf8(content)
+    if "\x00" in text:
+        raise AcquisitionSecurityError("PARSE_ENCODING", "CSV contains a NUL byte")
+    reader = csv.reader(
+        io.StringIO(text, newline=""),
+        delimiter=",",
+        quotechar='"',
+        doublequote=True,
+        strict=True,
+    )
+    try:
+        header = next(reader)
+    except (StopIteration, csv.Error):
+        raise AcquisitionSecurityError("PARSE_CSV", "CSV has no valid header") from None
+    columns = _columns(header, limits)
+    rows: list[tuple[Any, ...]] = []
+    try:
+        for raw in reader:
+            if len(rows) >= limits.max_rows:
+                raise AcquisitionSecurityError("PARSE_ROW_LIMIT", "CSV exceeds the row budget")
+            if len(raw) != len(columns):
+                raise AcquisitionSecurityError(
+                    "PARSE_ROW_WIDTH",
+                    "CSV row width differs from its header",
+                )
+            row = tuple(raw)
+            _validate_row(row, limits)
+            rows.append(row)
+    except csv.Error:
+        raise AcquisitionSecurityError("PARSE_CSV", "CSV syntax is malformed") from None
+    return columns, tuple(rows)
+
+
+def _parse_json(
+    content: bytes,
+    data_format: str,
+    limits: ParseLimits,
+) -> tuple[tuple[str, ...], tuple[tuple[Any, ...], ...]]:
+    text = _strict_utf8(content)
+    decoder = json.JSONDecoder(
+        object_pairs_hook=_unique_object,
+        parse_constant=lambda value: _invalid_json_number(value),
+    )
+    try:
+        if data_format == "json":
+            value = decoder.decode(text)
+            if isinstance(value, dict) and {"nbformat", "cells"} <= set(value):
+                raise AcquisitionSecurityError(
+                    "PARSE_NOTEBOOK",
+                    "notebook documents are not tabular JSON sources",
+                )
+            records = value
+        else:
+            records = []
+            for line_number, line in enumerate(text.splitlines(), start=1):
+                if not line.strip():
+                    continue
+                if len(records) >= limits.max_rows:
+                    raise AcquisitionSecurityError(
+                        "PARSE_ROW_LIMIT",
+                        "NDJSON exceeds the row budget",
+                    )
+                try:
+                    records.append(decoder.decode(line))
+                except json.JSONDecodeError:
+                    raise AcquisitionSecurityError(
+                        "PARSE_JSON",
+                        f"NDJSON line {line_number} is malformed",
+                    ) from None
+    except json.JSONDecodeError:
+        raise AcquisitionSecurityError("PARSE_JSON", "JSON syntax is malformed") from None
+    if not isinstance(records, list) or not records:
+        raise AcquisitionSecurityError(
+            "PARSE_JSON_SHAPE",
+            "JSON tabular input must be a non-empty array of objects",
+        )
+    if len(records) > limits.max_rows:
+        raise AcquisitionSecurityError("PARSE_ROW_LIMIT", "JSON exceeds the row budget")
+    if not all(isinstance(item, dict) for item in records):
+        raise AcquisitionSecurityError(
+            "PARSE_JSON_SHAPE",
+            "every JSON row must be an object",
+        )
+    first = records[0]
+    assert isinstance(first, dict)
+    columns = _columns(list(first), limits)
+    expected = set(columns)
+    rows: list[tuple[Any, ...]] = []
+    for index, item in enumerate(records):
+        assert isinstance(item, dict)
+        _validate_json_value(item, depth=1, limits=limits)
+        if set(item) != expected:
+            raise AcquisitionSecurityError(
+                "PARSE_ROW_SCHEMA",
+                f"JSON row {index + 1} does not match the first-row schema",
+            )
+        row = tuple(item[column] for column in columns)
+        _validate_row(row, limits)
+        rows.append(row)
+    return columns, tuple(rows)
+
+
+def _parse_parquet(
+    content: bytes,
+    limits: ParseLimits,
+    *,
+    display: bool = False,
+) -> tuple[tuple[str, ...], tuple[tuple[Any, ...], ...]]:
+    if not (content.startswith(b"PAR1") and content.endswith(b"PAR1")):
+        raise AcquisitionSecurityError("PARSE_PARQUET", "Parquet magic bytes are invalid")
+    pa, pq = _pyarrow()
+    try:
+        parquet = pq.ParquetFile(pa.BufferReader(content))
+        metadata = parquet.metadata
+        schema = parquet.schema_arrow
+    except (pa.ArrowException, OSError, ValueError):
+        raise AcquisitionSecurityError("PARSE_PARQUET", "Parquet metadata is malformed") from None
+    if metadata.num_rows > limits.max_rows:
+        raise AcquisitionSecurityError("PARSE_ROW_LIMIT", "Parquet exceeds the row budget")
+    if metadata.num_columns > limits.max_columns:
+        raise AcquisitionSecurityError("PARSE_COLUMN_LIMIT", "Parquet exceeds the column budget")
+    if metadata.num_rows * max(metadata.num_columns, 1) > limits.max_total_cells:
+        raise AcquisitionSecurityError("PARSE_CELL_LIMIT", "Parquet exceeds the cell budget")
+    uncompressed = sum(
+        metadata.row_group(group).total_byte_size for group in range(metadata.num_row_groups)
+    )
+    if uncompressed > limits.max_uncompressed_bytes:
+        raise AcquisitionSecurityError(
+            "PARSE_DECOMPRESSION_LIMIT",
+            "Parquet decoded bytes exceed the configured budget",
+        )
+    if uncompressed > max(len(content), 1) * limits.max_expansion_ratio:
+        raise AcquisitionSecurityError(
+            "PARSE_EXPANSION_RATIO",
+            "Parquet expansion ratio exceeds the configured budget",
+        )
+    for field in schema:
+        if isinstance(field.type, pa.ExtensionType):
+            raise AcquisitionSecurityError(
+                "PARSE_EXTENSION_TYPE",
+                "Parquet extension types are not allowlisted",
+            )
+    columns = _columns(schema.names, limits)
+    try:
+        table = parquet.read()
+        records = table.to_pylist()
+    except (pa.ArrowException, OSError, ValueError):
+        raise AcquisitionSecurityError("PARSE_PARQUET", "Parquet row decoding failed") from None
+    rows = tuple(tuple(item[column] for column in columns) for item in records)
+    if display:
+        # Before the budget check, never instead of it: a rendered value is measured in bytes
+        # exactly like any other string, so the field budget still applies to every cell.
+        rows = tuple(
+            tuple(_displayed(value, depth=0, limits=limits) for value in row) for row in rows
+        )
+    for row in rows:
+        _validate_row(row, limits)
+    return columns, rows
+
+
+# ------------------------------------------------------------------------------------------------
+# Rendering for display, which is the one thing a look may do that a build may not
+# ------------------------------------------------------------------------------------------------
+
+
+class _ExactText(str):
+    """The exact text of a value the canonical rule has no place for.
+
+    A ``str`` subclass rather than a plain ``str`` so the kind of value it came from survives the
+    rendering. Each subclass is named after that kind and :func:`_column_type` reads a value's type
+    name, so a rendered ``datetime.date`` is still reported as a ``date`` column: a person and an
+    agent are told what the file holds, not what the display did to it.
+    """
+
+    __slots__ = ()
+
+
+# The kinds that are rendered, and the text each is rendered into. Keyed by exact type rather than
+# by `isinstance`, because `datetime` is a subclass of `date` and the two are different kinds of
+# column. `isoformat` and `str` are the value's own exact spellings -- neither rounds, truncates,
+# or reformats -- so the text is the value and not a summary of it.
+_DISPLAY_TEXT: dict[type, Any] = {
+    datetime.date: datetime.date.isoformat,
+    datetime.datetime: datetime.datetime.isoformat,
+    datetime.time: datetime.time.isoformat,
+    datetime.timedelta: str,
+    decimal.Decimal: str,
+}
+
+# One named subclass per kind, built once.
+_DISPLAY_CLASSES: dict[type, type[_ExactText]] = {
+    kind: type(kind.__name__, (_ExactText,), {"__slots__": ()}) for kind in _DISPLAY_TEXT
+}
+
+# A not-a-number or an infinity is a `float` like any other, and the column it sits in is a float
+# column, so its rendering keeps that name. `repr` is the exact spelling Python reads back.
+_DISPLAY_FLOAT: type[_ExactText] = type("float", (_ExactText,), {"__slots__": ()})
+
+
+def _displayed(value: Any, *, depth: int, limits: ParseLimits) -> Any:
+    """``value`` unchanged when the canonical rule holds it, and its exact text when it does not.
+
+    Anything still unrenderable is left exactly as it is, so :func:`_validate_row` refuses it with
+    ``PARSE_VALUE`` as before: this widens what can be looked at, it does not remove the floor.
+    """
+
+    if depth > limits.max_json_depth:
+        raise AcquisitionSecurityError("PARSE_DEPTH_LIMIT", "value exceeds the nesting budget")
+    if isinstance(value, list | tuple):
+        return [_displayed(item, depth=depth + 1, limits=limits) for item in value]
+    if isinstance(value, dict):
+        return {
+            key: _displayed(item, depth=depth + 1, limits=limits) for key, item in value.items()
+        }
+    if type(value) is float and not math.isfinite(value):
+        return _DISPLAY_FLOAT(repr(value))
+    render = _DISPLAY_TEXT.get(type(value))
+    if render is None:
+        return value
+    return _DISPLAY_CLASSES[type(value)](render(value))
+
+
+def _columns(values: list[Any], limits: ParseLimits) -> tuple[str, ...]:
+    if not values or len(values) > limits.max_columns:
+        raise AcquisitionSecurityError(
+            "PARSE_COLUMN_LIMIT",
+            "table must have a non-empty bounded column set",
+        )
+    if not all(isinstance(value, str) and _SAFE_COLUMN.fullmatch(value) for value in values):
+        raise AcquisitionSecurityError(
+            "PARSE_COLUMN_NAME",
+            "column names must be bounded non-control strings",
+        )
+    columns = tuple(values)
+    if len(set(columns)) != len(columns):
+        raise AcquisitionSecurityError("PARSE_COLUMN_DUPLICATE", "column names must be unique")
+    return columns
+
+
+def _validate_table(
+    columns: tuple[str, ...],
+    rows: tuple[tuple[Any, ...], ...],
+    limits: ParseLimits,
+) -> None:
+    if len(rows) > limits.max_rows:
+        raise AcquisitionSecurityError("PARSE_ROW_LIMIT", "table exceeds the row budget")
+    if len(rows) * len(columns) > limits.max_total_cells:
+        raise AcquisitionSecurityError("PARSE_CELL_LIMIT", "table exceeds the cell budget")
+    for row in rows:
+        if len(row) != len(columns):
+            raise AcquisitionSecurityError(
+                "PARSE_ROW_WIDTH",
+                "parsed row width differs from its schema",
+            )
+
+
+def _validate_row(row: tuple[Any, ...], limits: ParseLimits) -> None:
+    for value in row:
+        if isinstance(value, str):
+            size = len(value.encode("utf-8"))
+        elif isinstance(value, bytes):
+            size = len(value)
+        else:
+            try:
+                size = len(
+                    json.dumps(
+                        value,
+                        ensure_ascii=False,
+                        separators=(",", ":"),
+                        allow_nan=False,
+                    ).encode("utf-8")
+                )
+            except (TypeError, ValueError):
+                raise AcquisitionSecurityError(
+                    "PARSE_VALUE",
+                    "parsed field contains a non-canonical value",
+                ) from None
+        if size > limits.max_field_bytes:
+            raise AcquisitionSecurityError(
+                "PARSE_FIELD_LIMIT",
+                "parsed field exceeds the byte budget",
+            )
+
+
+def _validate_json_value(value: Any, *, depth: int, limits: ParseLimits) -> None:
+    if depth > limits.max_json_depth:
+        raise AcquisitionSecurityError("PARSE_DEPTH_LIMIT", "JSON exceeds the nesting budget")
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in _FORBIDDEN_REFERENCE_KEYS:
+                raise AcquisitionSecurityError(
+                    "PARSE_EXTERNAL_REFERENCE",
+                    "parser-driven external references are forbidden",
+                )
+            _validate_json_value(item, depth=depth + 1, limits=limits)
+    elif isinstance(value, list):
+        for item in value:
+            _validate_json_value(item, depth=depth + 1, limits=limits)
+    elif isinstance(value, float) and not math.isfinite(value):
+        raise AcquisitionSecurityError("PARSE_NUMBER", "non-finite JSON numbers are forbidden")
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise AcquisitionSecurityError("PARSE_JSON_DUPLICATE", "JSON keys must be unique")
+        result[key] = value
+    return result
+
+
+def _invalid_json_number(value: str) -> Any:
+    raise AcquisitionSecurityError("PARSE_NUMBER", f"JSON number {value!r} is forbidden")
+
+
+def _strict_utf8(content: bytes) -> str:
+    try:
+        return content.decode("utf-8", errors="strict")
+    except UnicodeDecodeError:
+        raise AcquisitionSecurityError(
+            "PARSE_ENCODING",
+            "source text must be strict UTF-8",
+        ) from None
+
+
+def _suffix(filename: str) -> str:
+    if (
+        not isinstance(filename, str)
+        or not filename
+        or "/" in filename
+        or "\\" in filename
+        or filename.startswith(".")
+    ):
+        raise AcquisitionSecurityError(
+            "PARSE_FILENAME",
+            "source filename must be one non-hidden path component",
+        )
+    dot = filename.rfind(".")
+    return filename[dot:].lower() if dot >= 0 else ""
+
+
+def _column_type(rows: tuple[tuple[Any, ...], ...], index: int) -> str:
+    observed = sorted({"null" if row[index] is None else type(row[index]).__name__ for row in rows})
+    return "|".join(observed) if observed else "empty"