mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/collections.py

@@ -0,0 +1,815 @@
+"""Deterministic public-HTTPS collections with one certified Reader pin.
+
+One collection is one logical Recipe source.  The query either names an exact ordered member
+list or a fixed inclusive page-number range.  Every member crosses the existing combined
+retrieve/decode/parse Clean-room operation; fetched bytes never enter this coordinator process.
+Only the normalized tables return, and they are concatenated without guessing, coercion,
+deduplication, or reordering.
+
+This is intentionally not a general crawler.  It performs credential-free GETs, follows only the
+redirects admitted by ``PinnedHttpsRetriever``, and has no cursor, link-following, stop-on-empty,
+header, method, or callback surface.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qsl, urlsplit, urlunsplit
+
+from mostlyright.data_harness.acquisition.http import (
+    RetrievalLimits,
+    reader_retrieval_limits,
+    seal_content_addressed_snapshot,
+)
+from mostlyright.data_harness.acquisition.sandbox import CrawlerSandbox, sandbox_policy_digest
+from mostlyright.data_harness.canonical import sha256_bytes
+from mostlyright.data_harness.readers.contracts import ReaderBudgets, ReaderError
+from mostlyright.data_harness.readers.registry import TOOLBOX
+from mostlyright.data_harness.readers.tabular import encode_canonical_csv
+from mostlyright.data_harness.sources._adapter_steps import (
+    DecodeRecord,
+    _authorize_candidate,
+    _parse_limits,
+    _require_decode_matches_pin,
+)
+from mostlyright.data_harness.sources.adapters import (
+    AdapterGovernance,
+    _reader_budget_caps,
+    _warm_up_family,
+    https_reader_policy_digest,
+)
+from mostlyright.data_harness.sources.contracts import (
+    AcquisitionReceiptV3,
+    AcquisitionRequest,
+    AdapterDescriptor,
+    CollectionMemberEvidence,
+    SnapshotReference,
+    SourceContractError,
+    SourceObservation,
+    collection_fetched_content_sha256,
+    collection_member_manifest_digest,
+    collection_transport_evidence_digest,
+    decode_options_digest,
+)
+from mostlyright.data_harness.sources.governance import (
+    classify_before_persistence,
+    require_admissible,
+)
+from mostlyright.data_harness.sources.registry import AcquisitionContext, AcquisitionOutput
+
+COLLECTION_ADAPTER_ID = "public.https.collection"
+COLLECTION_ADAPTER_VERSION = "1.0.0"
+MAX_COLLECTION_MEMBERS = 16
+MAX_COLLECTION_MEMBER_ID_LENGTH = 128
+MAX_URL_LENGTH = 2_048
+
+_MEMBER_ID = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+_PAGE_PARAMETER = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
+_MAX_PAGE_NUMBER = 9_007_199_254_740_991
+
+
+@dataclass(frozen=True)
+class CollectionMember:
+    """One exact member address after closed query expansion."""
+
+    member_id: str
+    url: str
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.member_id, str)
+            or len(self.member_id) > MAX_COLLECTION_MEMBER_ID_LENGTH
+            or _MEMBER_ID.fullmatch(self.member_id) is None
+        ):
+            raise SourceContractError(
+                "COLLECTION_MEMBER_ID",
+                "request.query.collection.members.member_id",
+                "must be a canonical lowercase identifier no longer than "
+                f"{MAX_COLLECTION_MEMBER_ID_LENGTH} characters",
+            )
+        _safe_public_https_url(self.url, "request.query.collection.members.url")
+
+
+def collection_members(query: Mapping[str, Any]) -> tuple[CollectionMember, ...]:
+    """Parse the collection adapter's exact query and return its semantic member order."""
+
+    data = _exact_object(query, {"collection", "data_format"}, "request.query")
+    if data["data_format"] != "csv":
+        raise SourceContractError(
+            "COLLECTION_FORMAT",
+            "request.query.data_format",
+            "collection output must be canonical CSV",
+        )
+    collection = _object(data["collection"], "request.query.collection")
+    kind = collection.get("kind")
+    if kind == "explicit":
+        return _explicit_members(collection)
+    if kind == "page_number":
+        return _page_members(collection)
+    raise SourceContractError(
+        "COLLECTION_KIND",
+        "request.query.collection.kind",
+        "must be explicit or page_number",
+    )
+
+
+def _explicit_members(value: Mapping[str, Any]) -> tuple[CollectionMember, ...]:
+    data = _exact_object(value, {"kind", "members"}, "request.query.collection")
+    raw_members = data["members"]
+    if not isinstance(raw_members, list) or not 1 <= len(raw_members) <= MAX_COLLECTION_MEMBERS:
+        raise SourceContractError(
+            "COLLECTION_MEMBER_LIMIT",
+            "request.query.collection.members",
+            f"must contain between 1 and {MAX_COLLECTION_MEMBERS} members",
+        )
+    members: list[CollectionMember] = []
+    for index, raw in enumerate(raw_members):
+        item = _exact_object(
+            raw,
+            {"member_id", "url"},
+            f"request.query.collection.members[{index}]",
+        )
+        members.append(CollectionMember(member_id=item["member_id"], url=item["url"]))
+    _require_unique_members(tuple(members))
+    return tuple(members)
+
+
+def _page_members(value: Mapping[str, Any]) -> tuple[CollectionMember, ...]:
+    data = _exact_object(
+        value,
+        {"kind", "base_url", "page_parameter", "first_page", "last_page"},
+        "request.query.collection",
+    )
+    base_url = _safe_public_https_url(
+        data["base_url"],
+        "request.query.collection.base_url",
+    )
+    parameter = data["page_parameter"]
+    if not isinstance(parameter, str) or _PAGE_PARAMETER.fullmatch(parameter) is None:
+        raise SourceContractError(
+            "COLLECTION_PAGE_PARAMETER",
+            "request.query.collection.page_parameter",
+            "must be a bounded URL-query parameter name",
+        )
+    first = _page_number(data["first_page"], "request.query.collection.first_page")
+    last = _page_number(data["last_page"], "request.query.collection.last_page")
+    if last < first:
+        raise SourceContractError(
+            "COLLECTION_PAGE_RANGE",
+            "request.query.collection.last_page",
+            "must not precede first_page",
+        )
+    count = last - first + 1
+    if count > MAX_COLLECTION_MEMBERS:
+        raise SourceContractError(
+            "COLLECTION_MEMBER_LIMIT",
+            "request.query.collection",
+            f"page range must contain at most {MAX_COLLECTION_MEMBERS} pages",
+        )
+    parsed = urlsplit(base_url)
+    try:
+        existing_names = [name for name, _ in parse_qsl(parsed.query, keep_blank_values=True)]
+    except ValueError as error:
+        raise SourceContractError(
+            "COLLECTION_URL",
+            "request.query.collection.base_url",
+            "contains a malformed query string",
+        ) from error
+    if parameter in existing_names:
+        raise SourceContractError(
+            "COLLECTION_PAGE_PARAMETER",
+            "request.query.collection.page_parameter",
+            "must not already occur in base_url",
+        )
+    members = tuple(
+        CollectionMember(
+            member_id=f"page-{page}",
+            url=_append_page_parameter(parsed, parameter=parameter, page=page),
+        )
+        for page in range(first, last + 1)
+    )
+    _require_unique_members(members)
+    return members
+
+
+def _append_page_parameter(parsed: Any, *, parameter: str, page: int) -> str:
+    suffix = f"{parameter}={page}"
+    query = f"{parsed.query}&{suffix}" if parsed.query else suffix
+    url = urlunsplit((parsed.scheme, parsed.netloc, parsed.path, query, ""))
+    return _safe_public_https_url(url, "request.query.collection.base_url")
+
+
+def _require_unique_members(members: tuple[CollectionMember, ...]) -> None:
+    ids = [item.member_id for item in members]
+    urls = [item.url for item in members]
+    if len(set(ids)) != len(ids):
+        raise SourceContractError(
+            "COLLECTION_MEMBER_DUPLICATE",
+            "request.query.collection.members",
+            "member identifiers must be unique",
+        )
+    if len(set(urls)) != len(urls):
+        raise SourceContractError(
+            "COLLECTION_MEMBER_DUPLICATE",
+            "request.query.collection.members",
+            "member URLs must be unique",
+        )
+
+
+def _page_number(value: Any, path: str) -> int:
+    if type(value) is not int or not 0 <= value <= _MAX_PAGE_NUMBER:
+        raise SourceContractError(
+            "COLLECTION_PAGE_RANGE",
+            path,
+            f"must be an integer in [0, {_MAX_PAGE_NUMBER}]",
+        )
+    return value
+
+
+def _safe_public_https_url(value: Any, path: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= MAX_URL_LENGTH
+        or not value.isascii()
+        or any(char in value for char in "\r\n\t")
+    ):
+        raise SourceContractError(
+            "COLLECTION_URL",
+            path,
+            "must be bounded ASCII HTTPS text without control characters",
+        )
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port
+    except ValueError as error:
+        raise SourceContractError("COLLECTION_URL", path, "is malformed") from error
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+        or port not in {None, 443}
+    ):
+        raise SourceContractError(
+            "COLLECTION_URL",
+            path,
+            "must be public HTTPS on port 443 without user information or a fragment",
+        )
+    return value
+
+
+def _object(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise SourceContractError("COLLECTION_QUERY", path, "must be an object")
+    return value
+
+
+def _exact_object(value: Any, keys: set[str], path: str) -> Mapping[str, Any]:
+    data = _object(value, path)
+    if set(data) != keys:
+        raise SourceContractError(
+            "COLLECTION_QUERY",
+            path,
+            f"fields must be exactly {sorted(keys)}",
+        )
+    return data
+
+
+def _descriptor() -> AdapterDescriptor:
+    return AdapterDescriptor(
+        adapter_id=COLLECTION_ADAPTER_ID,
+        adapter_version=COLLECTION_ADAPTER_VERSION,
+        source_class="external_adapter",
+        data_formats=("csv",),
+        capabilities=("snapshot", "refresh", "backfill"),
+    )
+
+
+def _collection_retrieval_limits() -> RetrievalLimits:
+    # A collection member with no redirect consumes one request. The transport ceiling is 16,
+    # matching this adapter's member ceiling, and is one aggregate budget across the collection,
+    # not a fresh allowance for every member.
+    return RetrievalLimits(max_requests=MAX_COLLECTION_MEMBERS)
+
+
+@dataclass(frozen=True)
+class PublicHttpsCollectionAdapter:
+    """Acquire a bounded collection and seal one canonical CSV snapshot."""
+
+    sandbox: CrawlerSandbox
+    allowed_hostnames: tuple[str, ...]
+    governance: AdapterGovernance
+    retrieval_limits: RetrievalLimits = field(default_factory=_collection_retrieval_limits)
+    descriptor: AdapterDescriptor = field(default_factory=_descriptor)
+    monotonic: Callable[[], float] = field(default=time.monotonic, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        expected = _descriptor()
+        if self.descriptor != expected:
+            raise SourceContractError(
+                "COLLECTION_ADAPTER_DESCRIPTOR",
+                "adapter.descriptor",
+                f"must be exactly {COLLECTION_ADAPTER_ID}@{COLLECTION_ADAPTER_VERSION}",
+            )
+        if not self.allowed_hostnames:
+            raise SourceContractError(
+                "EGRESS_ALLOWLIST",
+                "adapter.allowed_hostnames",
+                "collection adapter requires an exact non-empty host allowlist",
+            )
+        if not callable(self.monotonic):
+            raise SourceContractError(
+                "COLLECTION_CLOCK",
+                "adapter.monotonic",
+                "must be a callable monotonic clock",
+            )
+
+    def acquire(
+        self,
+        request: AcquisitionRequest,
+        context: AcquisitionContext,
+    ) -> AcquisitionOutput:
+        if (request.adapter_id, request.adapter_version) != (
+            self.descriptor.adapter_id,
+            self.descriptor.adapter_version,
+        ):
+            raise SourceContractError(
+                "ADAPTER_BINDING",
+                "request",
+                "request does not bind the exact collection adapter identity",
+            )
+        if request.credential_reference_id is not None:
+            raise SourceContractError(
+                "AUTHENTICATED_SOURCE_REQUIRES_TRUSTED_GATEWAY",
+                "request.credential_reference_id",
+                "public collection acquisition receives no credential",
+            )
+        if request.reader_pin is None:
+            raise SourceContractError(
+                "READER_PIN_REQUIRED",
+                "request.reader_pin",
+                "collection members require one exact common Reader pin",
+            )
+        members = collection_members(request.query)
+        _authorize_candidate(request, self.governance)
+        if context.crawler_sandbox_attestation_digest != https_reader_policy_digest():
+            raise SourceContractError(
+                "SANDBOX_ATTESTATION_MISMATCH",
+                "context.crawler_sandbox_attestation_digest",
+                "context does not pin the HTTPS retrieval-plus-decode policies",
+            )
+        expected_retrieval = sandbox_policy_digest("retrieve_decode_and_parse")
+        expected_decode = sandbox_policy_digest("decode_and_parse")
+        _warm_up_family(
+            self.sandbox,
+            pin=request.reader_pin,
+            context=context,
+            sealed_format="csv",
+            expected_policy_digest=expected_decode,
+        )
+        return self._acquire_members(
+            request,
+            context,
+            members=members,
+            expected_retrieval=expected_retrieval,
+        )
+
+    def _acquire_members(
+        self,
+        request: AcquisitionRequest,
+        context: AcquisitionContext,
+        *,
+        members: tuple[CollectionMember, ...],
+        expected_retrieval: str,
+    ) -> AcquisitionOutput:
+        assert request.reader_pin is not None
+        pin = request.reader_pin
+        fetched_bytes = 0
+        normalized_bytes = 0
+        request_count = 0
+        row_count = 0
+        declared_cells = 0
+        columns: tuple[str, ...] | None = None
+        schema_digest: str | None = None
+        member_rows: list[tuple[tuple[Any, ...], ...]] = []
+        evidence: list[CollectionMemberEvidence] = []
+        started = _monotonic_value(self.monotonic, "adapter.monotonic")
+        deadline = started + self.retrieval_limits.total_timeout_seconds
+        max_declared_cells = _effective_max_declared_cells(context, request)
+
+        for sequence, member in enumerate(members):
+            remaining_requests = self.retrieval_limits.max_requests - request_count
+            if remaining_requests <= 0:
+                raise SourceContractError(
+                    "COLLECTION_REQUEST_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative HTTP request budget",
+                )
+            remaining_seconds = deadline - _monotonic_value(
+                self.monotonic,
+                "adapter.monotonic",
+            )
+            if remaining_seconds <= 0:
+                raise SourceContractError(
+                    "COLLECTION_TIMEOUT",
+                    "request.query.collection",
+                    "collection exceeded its cumulative retrieval deadline",
+                )
+            remaining = context.max_source_bytes - fetched_bytes
+            if remaining <= 0:
+                raise SourceContractError(
+                    "COLLECTION_BYTE_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative fetched-byte budget",
+                )
+            limits = reader_retrieval_limits(
+                self.retrieval_limits,
+                family_id=str(pin["family_id"]),
+                family_version=str(pin["family_version"]),
+            )
+            limits = replace(
+                limits,
+                max_response_bytes=min(limits.max_response_bytes, remaining),
+                max_aggregate_response_bytes=min(
+                    limits.max_aggregate_response_bytes,
+                    remaining,
+                ),
+                max_requests=remaining_requests,
+                # RetrievalLimits requires room for the admitted redirect chain. A nearly
+                # exhausted collection can still make its one terminal request, but it may not
+                # spend requests it no longer owns on redirects.
+                max_redirects=min(limits.max_redirects, remaining_requests - 1),
+                total_timeout_seconds=min(limits.total_timeout_seconds, remaining_seconds),
+            )
+            reader_budgets = _reader_budget_caps(context, request)
+            # A zero-row member is valid even after earlier members have spent the whole cell
+            # allowance. Reader budgets are positive integers, so retain a one-cell confined
+            # decode allowance and enforce the exact aggregate immediately on its parsed result.
+            # This never authorizes aggregate output beyond ``max_declared_cells``.
+            reader_budgets["max_declared_cells"] = min(
+                int(reader_budgets.get("max_declared_cells", max_declared_cells)),
+                max(max_declared_cells - declared_cells, 1),
+            )
+            result = self.sandbox.retrieve_decode_and_parse(
+                # The outer request id may already occupy its complete 128-byte contract.
+                # Derive a short, collision-resistant child id instead of appending unbounded
+                # member text to it. Sequence is semantic and the request digest binds the
+                # complete ordered member plan.
+                request_id=f"collection.{request.digest[:24]}.{sequence}",
+                url=member.url,
+                allowed_hostnames=self.allowed_hostnames,
+                reader_pin=pin,
+                output_format="csv",
+                parse_limits=_parse_limits(context),
+                retrieval_limits=limits,
+                reader_budgets=reader_budgets,
+            )
+            if result.policy_digest != expected_retrieval:
+                raise SourceContractError(
+                    "SANDBOX_ATTESTATION_MISMATCH",
+                    "sandbox.policy_digest",
+                    "collection member does not bind the retrieval-plus-decode policy",
+                )
+            required = (
+                result.content,
+                result.parsed,
+                result.final_url,
+                result.transport_evidence_digest,
+                result.fetched_content_sha256,
+                result.fetched_content_size_bytes,
+                result.fetched_total_response_body_size_bytes,
+                result.fetched_request_count,
+                result.decode_family_id,
+                result.decode_family_version,
+                result.decode_options_digest,
+                result.decode_flags,
+                result.decode_declared_cell_count,
+            )
+            if any(item is None for item in required):
+                raise SourceContractError(
+                    "SANDBOX_RESULT",
+                    "sandbox",
+                    "collection member acquisition result is incomplete",
+                )
+            assert result.content is not None
+            assert result.parsed is not None
+            assert result.final_url is not None
+            assert result.transport_evidence_digest is not None
+            assert result.fetched_content_sha256 is not None
+            assert result.fetched_content_size_bytes is not None
+            assert result.fetched_total_response_body_size_bytes is not None
+            assert result.fetched_request_count is not None
+            assert result.decode_family_id is not None
+            assert result.decode_family_version is not None
+            assert result.decode_options_digest is not None
+            assert result.decode_flags is not None
+            assert result.decode_declared_cell_count is not None
+            if result.parsed.input_sha256 != sha256_bytes(result.content):
+                raise SourceContractError(
+                    "SANDBOX_RESULT",
+                    "sandbox.parsed.input_sha256",
+                    "parsed table does not bind the normalized member bytes",
+                )
+            _require_decode_matches_pin(
+                request,
+                _decode_record(
+                    fetched_sha256=result.fetched_content_sha256,
+                    family_id=result.decode_family_id,
+                    family_version=result.decode_family_version,
+                    options_digest=result.decode_options_digest,
+                    flags=result.decode_flags,
+                ),
+            )
+            if (
+                type(result.fetched_total_response_body_size_bytes) is not int
+                or type(result.fetched_content_size_bytes) is not int
+                or not 1
+                <= result.fetched_content_size_bytes
+                <= result.fetched_total_response_body_size_bytes
+            ):
+                raise SourceContractError(
+                    "COLLECTION_BYTE_LIMIT",
+                    "sandbox.fetched_total_response_body_size_bytes",
+                    "member byte accounting does not contain its terminal fetched object",
+                )
+            # Charge every retained response body, not only the terminal object recorded as this
+            # member's fetched identity. Redirect bodies consume the same collection-wide source
+            # budget and cannot buy a fresh allowance by preceding a smaller final response.
+            fetched_bytes += result.fetched_total_response_body_size_bytes
+            if (
+                type(result.fetched_request_count) is not int
+                or not 1 <= result.fetched_request_count <= remaining_requests
+            ):
+                raise SourceContractError(
+                    "COLLECTION_REQUEST_LIMIT",
+                    "sandbox.fetched_request_count",
+                    "member request accounting is outside the remaining collection budget",
+                )
+            request_count += result.fetched_request_count
+            if _monotonic_value(self.monotonic, "adapter.monotonic") > deadline:
+                raise SourceContractError(
+                    "COLLECTION_TIMEOUT",
+                    "request.query.collection",
+                    "collection exceeded its cumulative retrieval deadline",
+                )
+            normalized_bytes += len(result.content)
+            if fetched_bytes > context.max_source_bytes:
+                raise SourceContractError(
+                    "COLLECTION_BYTE_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative fetched-byte budget",
+                )
+            if normalized_bytes > context.max_source_bytes:
+                raise SourceContractError(
+                    "COLLECTION_BYTE_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative normalized-byte budget",
+                )
+            if len(result.parsed.columns) > context.max_columns:
+                raise SourceContractError(
+                    "COLLECTION_COLUMN_LIMIT",
+                    "request.query.collection",
+                    "member schema exceeds the column budget",
+                )
+            if columns is None:
+                columns = result.parsed.columns
+                schema_digest = result.parsed.schema_digest
+            elif result.parsed.columns != columns or result.parsed.schema_digest != schema_digest:
+                raise SourceContractError(
+                    "COLLECTION_SCHEMA_MISMATCH",
+                    f"request.query.collection.members[{sequence}]",
+                    "member schema differs from the first member; no coercion is implicit",
+                )
+            row_count += len(result.parsed.rows)
+            if row_count > context.max_rows:
+                raise SourceContractError(
+                    "COLLECTION_ROW_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative row budget",
+                )
+            normalized_cell_count = len(result.parsed.rows) * len(result.parsed.columns)
+            if (
+                type(result.decode_declared_cell_count) is not int
+                or result.decode_declared_cell_count != normalized_cell_count
+            ):
+                raise SourceContractError(
+                    "COLLECTION_CELL_EVIDENCE",
+                    "sandbox.decode_declared_cell_count",
+                    "collection v1 requires Reader cell accounting that is exactly rederived "
+                    "from the normalized member geometry",
+                )
+            declared_cells += result.decode_declared_cell_count
+            if declared_cells > max_declared_cells:
+                raise SourceContractError(
+                    "COLLECTION_CELL_LIMIT",
+                    "request.query.collection",
+                    "members exceed the cumulative effective Reader cell budget",
+                )
+            member_rows.append(result.parsed.rows)
+            evidence.append(
+                CollectionMemberEvidence(
+                    member_id=member.member_id,
+                    sequence=sequence,
+                    source_uri=member.url,
+                    final_uri=result.final_url,
+                    fetched_content_sha256=result.fetched_content_sha256,
+                    fetched_size_bytes=result.fetched_content_size_bytes,
+                    normalized_content_sha256=sha256_bytes(result.content),
+                    normalized_size_bytes=len(result.content),
+                    request_count=result.fetched_request_count,
+                    row_count=len(result.parsed.rows),
+                    column_count=len(result.parsed.columns),
+                    declared_cell_count=result.decode_declared_cell_count,
+                    parsed_schema_digest=result.parsed.schema_digest,
+                    transport_evidence_digest=result.transport_evidence_digest,
+                    decode_flags=result.decode_flags,
+                )
+            )
+
+        assert columns is not None and schema_digest is not None
+        try:
+            content = encode_canonical_csv(
+                columns,
+                _ordered_rows(member_rows),
+                budgets=ReaderBudgets().narrowed_by(
+                    {
+                        "max_output_bytes": (
+                            context.max_source_bytes
+                            if context.max_normalized_bytes is None
+                            else context.max_normalized_bytes
+                        ),
+                        "max_rows": context.max_rows,
+                        "max_columns": context.max_columns,
+                        "max_declared_cells": max_declared_cells,
+                    }
+                ),
+            )
+        except ReaderError as error:
+            raise SourceContractError(
+                "COLLECTION_OUTPUT",
+                "request.query.collection",
+                "canonical aggregate output was refused by the Reader budget",
+            ) from error
+        classification = classify_before_persistence(
+            content,
+            declared_classification=self.governance.declared_classification,
+            lawful_basis_declared=self.governance.lawful_basis_declared,
+        )
+        require_admissible(classification)
+        snapshot_path = seal_content_addressed_snapshot(
+            context.snapshot_root,
+            content=content,
+            suffix="csv",
+        )
+        return _collection_output(
+            request=request,
+            descriptor=self.descriptor,
+            governance=self.governance,
+            snapshot_path=snapshot_path,
+            content=content,
+            classification=classification.classification,
+            members=tuple(evidence),
+            parsed_schema_digest=schema_digest,
+        )
+
+
+def _decode_record(
+    *,
+    fetched_sha256: str,
+    family_id: str,
+    family_version: str,
+    options_digest: str,
+    flags: tuple[str, ...],
+) -> DecodeRecord:
+    return DecodeRecord(
+        fetched_content_sha256=fetched_sha256,
+        family_id=family_id,
+        family_version=family_version,
+        decode_options_digest=options_digest,
+        flags=flags,
+    )
+
+
+def _effective_max_declared_cells(
+    context: AcquisitionContext,
+    request: AcquisitionRequest,
+) -> int:
+    """Return the one aggregate cell ceiling shared by every member and final encoding.
+
+    The selected family's certified defaults remain the outer Reader authority. Trusted context
+    row/column ceilings and an optional Recipe cap can only narrow it. Resolving the exact Toolbox
+    coordinate here also means the aggregate coordinator cannot accidentally enforce a generic
+    Reader ceiling wider than the family that actually decodes the members.
+    """
+
+    assert request.reader_pin is not None
+    family = TOOLBOX.resolve(
+        str(request.reader_pin["family_id"]),
+        str(request.reader_pin["family_version"]),
+    )
+    budgets = family.default_budgets.narrowed_by(_reader_budget_caps(context, request))
+    return min(
+        budgets.max_declared_cells,
+        budgets.max_rows * budgets.max_columns,
+    )
+
+
+def _monotonic_value(clock: Callable[[], float], path: str) -> float:
+    value = clock()
+    if type(value) not in {int, float} or not 0 <= value < float("inf"):
+        raise SourceContractError(
+            "COLLECTION_CLOCK",
+            path,
+            "must return a finite non-negative monotonic value",
+        )
+    return float(value)
+
+
+def _ordered_rows(
+    members: Iterable[tuple[tuple[Any, ...], ...]],
+) -> Iterable[tuple[Any, ...]]:
+    for rows in members:
+        yield from rows
+
+
+def _collection_output(
+    *,
+    request: AcquisitionRequest,
+    descriptor: AdapterDescriptor,
+    governance: AdapterGovernance,
+    snapshot_path: Path,
+    content: bytes,
+    classification: str,
+    members: tuple[CollectionMemberEvidence, ...],
+    parsed_schema_digest: str,
+) -> AcquisitionOutput:
+    assert request.reader_pin is not None
+    observation = SourceObservation(
+        source_id=request.source_id,
+        observed_at=governance.observation.observed_at,
+        event_time_field=governance.observation.event_time_field,
+        available_at_field=governance.observation.available_at_field,
+        historical_start=governance.observation.historical_start,
+        historical_end=governance.observation.historical_end,
+        live_status=governance.observation.live_status,
+        publication_delay_seconds=governance.observation.publication_delay_seconds,
+        update_frequency_seconds=governance.observation.update_frequency_seconds,
+        response_status=governance.observation.response_status,
+        evidence=governance.observation.evidence,
+    )
+    flags = tuple(sorted({flag for member in members for flag in member.decode_flags}))
+    digest = sha256_bytes(content)
+    receipt = AcquisitionReceiptV3(
+        receipt_id=f"receipt.{request.digest[:24]}",
+        request_digest=request.digest,
+        source_id=request.source_id,
+        adapter=descriptor,
+        query_digest=request.query_digest,
+        snapshot=SnapshotReference(
+            content_sha256=digest,
+            size_bytes=len(content),
+            media_type="text/csv",
+            data_format="csv",
+            storage_name=snapshot_path.name,
+        ),
+        fetched_content_sha256=collection_fetched_content_sha256(members),
+        family_id=str(request.reader_pin["family_id"]),
+        family_version=str(request.reader_pin["family_version"]),
+        decode_options_digest=decode_options_digest(request.reader_pin["decode_options"]),
+        decode_flags=flags,
+        event_time_field=governance.observation.event_time_field,
+        observed_at=governance.observation.observed_at,
+        available_at=governance.observation.available_at,
+        ingested_at=request.requested_at,
+        classification=classification,
+        rights_digest=governance.rights.digest,
+        retention_digest=governance.retention.digest,
+        observation_digest=observation.digest,
+        transport_evidence_digest=collection_transport_evidence_digest(members),
+        members=members,
+        member_manifest_digest=collection_member_manifest_digest(members),
+        parsed_schema_digest=parsed_schema_digest,
+    )
+    return AcquisitionOutput(
+        receipt=receipt,
+        observation=observation,
+        parsed_schema_digest=parsed_schema_digest,
+        snapshot_path=snapshot_path,
+    )
+
+
+__all__ = [
+    "COLLECTION_ADAPTER_ID",
+    "COLLECTION_ADAPTER_VERSION",
+    "MAX_COLLECTION_MEMBERS",
+    "MAX_COLLECTION_MEMBER_ID_LENGTH",
+    "CollectionMember",
+    "PublicHttpsCollectionAdapter",
+    "collection_members",
+]