mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/acquire.py

@@ -0,0 +1,1137 @@
+"""``mr-data acquire``, answered by Studio's clean room and by the Receipt Studio bound.
+
+WHAT WAS MISSING, AND WHAT CLOSED IT. The hosted clean room has existed since ADR 0015 and a full
+install already uses it: with neither attestation, the local ``acquire`` submits to Studio, waits,
+downloads the quarantined bundle, and then binds the Receipt **on this computer** against the
+Toolbox -- which resolves the exact Reader the request pinned and the budgets that Reader's
+certified family narrows to. A thin profile carries no Toolbox, so that last step had no hosted
+answer, and PR #312 recorded the gap with the sentence that named what would close it: *Studio
+returning the bound Receipt itself*. Studio PR #95 does exactly that, at
+``GET /v3/workspaces/{ws}/public-acquisitions/{id}/receipt``.
+
+⚠ THE BINDING IS NOT RE-IMPLEMENTED HERE, AND THAT IS THE POINT. Nothing below re-derives a
+Reader's certified defaults, re-checks a decode-options digest, or re-narrows a budget. Copying
+that closed, Certification-gated table into this repository would be a second copy of a
+security-critical fact with nothing holding the two in step -- precisely the shape the boundary
+carve-out forbids, and precisely the reason this command was pending rather than written.
+
+WHAT THIS LANE DOES CHECK is the half that is about the bytes rather than about the Reader: the
+Receipt is the Receipt for the session that was opened, the bundle hashes to the digest Studio's
+binding declares, and the normalized content hashes to the digest the Receipt declares. Those are
+digests over documents already in hand, not a second opinion about a Toolbox.
+
+⚠ AND IT SAYS WHICH BINDING IT GOT. ``receipt_binding.reader_binding`` is ``none`` when the request
+pinned no Reader -- in which case the Receipt carries no Toolbox-derived fact at all and Studio's
+binding IS the whole binding -- and ``worker_toolbox`` when one was pinned, where the Toolbox that
+resolved it was the one inside the clean room. Both land in the receipt under their own key with
+the sentence that says what the difference is, the same posture ``verify`` set with ``checked_by``:
+state which check was performed rather than letting one word carry two meanings.
+
+A COURIER THAT REACHED THE SOURCE AND REFUSED **completed** the session. It answers here as
+``outcome: "refused"`` carrying its sealed refusal, and this renders it as a refusal -- the local
+lane's own ``status: "refused"`` payload, its headline, its exit code -- rather than as an error
+about one. A publisher saying no is an answer.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import re
+import time
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+from uuid import UUID
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_sha256,
+    parse_foreign_json,
+)
+from mostlyright.data_harness.thin.download import download_signed_artifact
+from mostlyright.data_harness.thin.parity import _no_effect
+from mostlyright.data_harness.thin.runs import StudioApiClient
+from mostlyright.data_harness.thin.session import StudioSession, open_studio_session
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+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,
+    NOT_PLAIN,
+    PlainFileRefusal,
+    read_plain_file,
+)
+
+# --------------------------------------------------------------------------------------------
+# Words and numbers this lane must not invent
+# --------------------------------------------------------------------------------------------
+#
+# Every constant below is a literal the local lane already owns, restated because the module that
+# holds it reaches the engine and cannot be imported on a thin install. A restated literal is a
+# literal that can drift, so `tests/test_thin_parity.py` holds each one equal to its original on a
+# full install, where both sides import.
+
+#: ``cli.ACQUISITION_DOCUMENT_VERSION`` and ``cli.ACQUISITION_RECEIPT_VERSION``.
+ACQUISITION_DOCUMENT_VERSION = "mr-data-acquisition.v1"
+ACQUISITION_RECEIPT_VERSION = "mr-data-acquire-receipt.v1"
+
+#: ``sources.collections.COLLECTION_ADAPTER_ID``.
+COLLECTION_ADAPTER_ID = "public.https.collection"
+
+#: ``cli._HOSTED_LIMIT_CAPS``: the hosted Courier contract's own ceilings
+#: (``public-crawl.schema.json#/$defs/public_https_query/properties/limits``). Refused here, by
+#: name, before this command contacts anything -- Studio would refuse the same document schema-side
+#: as an unexplained 422 that names none of them.
+HOSTED_LIMIT_CAPS: dict[str, int] = {
+    "max_source_bytes": 268_435_456,
+    "max_normalized_bytes": 4_294_967_296,
+    "max_rows": 10_000_000,
+    "max_columns": 1_024,
+}
+
+#: ``cli._MAX_DOCUMENT_BYTES``, which is ``ParseLimits().max_input_bytes``.
+MAX_DOCUMENT_BYTES = 16 * 1024 * 1024
+
+#: ``cli._DENY_DEFAULT_POSTURE``.
+DENY_DEFAULT_POSTURE = (
+    "Nothing is fetchable by default; every acquisition supplies its own exact host allowlist."
+)
+
+#: The two headlines ``cli._acquisition_facts`` and ``cli._acquire_refusal`` open with, for the
+#: single-address case -- the only case a hosted acquisition has.
+ACQUIRED_HEADLINE = "The Courier fetched one address in a clean room and sealed its Receipt."
+REFUSED_HEADLINE = "This acquisition was refused."
+
+#: The two sentences ``ux.hosted_acquisition`` prints about a Courier that reached the source and
+#: said no, and about one that did not get that far.
+COURIER_REFUSAL_DETAIL = (
+    "the hosted public acquisition was safely refused inside the isolated Courier"
+)
+COURIER_FAILURE_DETAIL = "the hosted public acquisition failed inside the isolated Courier"
+
+#: ``cli._acquire``'s two hosted-route labels, and the authority behind the attestation it reports.
+HOSTED_ACQUISITION_ENVIRONMENT = "studio_hosted_clean_room"
+HOSTED_ATTESTATION_AUTHORITY = "studio_trusted_coordinator"
+
+#: The one refusal the hosted route owes a bounded collection, with ``cli``'s own code and words.
+#: PR #312 put this sentence on ``acquire-slices``, which is a different command about a different
+#: problem; Studio's design note (``docs/platform/HOSTED-SLICE-ACQUISITION.md``) found the mix-up
+#: and it is corrected in both places at once.
+COLLECTION_UNSUPPORTED_CODE = "ACQUIRE_HOSTED_COLLECTION_UNSUPPORTED"
+COLLECTION_UNSUPPORTED_DETAIL = (
+    "bounded collections currently require the local attested acquisition route"
+)
+
+#: ``sources.hosted``'s transport envelope, restated as the one shape whose digest the local
+#: hosted route reports as ``clean_room_attestation_digest``. It is a digest over five facts
+#: Studio already stated, not a check: computing it here reproduces the local lane's value exactly,
+#: which is what makes that key mean the same thing in both profiles.
+TRANSPORT_ENVELOPE_SCHEMA = "hosted-public-https-transport-envelope.v1"
+CLEAN_ROOM = {
+    "host_platform": "linux-amd64",
+    "parser_network_syscalls": "denied",
+    "parser_process_creation": "denied",
+    "no_new_privs": True,
+}
+
+#: ``ux.hosted_acquisition.source_authority_digest``'s document.
+SOURCE_AUTHORITY_SCHEMA = "mr-data-hosted-public-source-authority.v1"
+
+#: ``ux.hosted_acquisition._RECEIPT_FIELDS``: the exact key set a Receipt must carry before the
+#: local lane will believe one. Studio's own suite restates this same literal and asserts the
+#: published Receipt equals it; this is the harness half of the same agreement, and a field added
+#: on either side and not the other fails on both.
+RECEIPT_FIELDS = frozenset(
+    {
+        "schema_version",
+        "source_id",
+        "adapter_id",
+        "adapter_version",
+        "request_digest",
+        "source_url",
+        "final_url",
+        "fetched_media_type",
+        "normalized_media_type",
+        "normalized_data_format",
+        "normalized_filename",
+        "acquired_at",
+        "raw_content_sha256",
+        "raw_size_bytes",
+        "normalized_content_sha256",
+        "normalized_size_bytes",
+        "row_count",
+        "column_names",
+        "parsed_schema_digest",
+        "family_id",
+        "family_version",
+        "decode_options_digest",
+        "decode_flags",
+        "resource_caps",
+        "reader_budgets",
+        "transport_evidence_digest",
+        "egress_policy_attestation",
+        "clean_room",
+    }
+)
+
+# --------------------------------------------------------------------------------------------
+# This lane's own vocabulary
+# --------------------------------------------------------------------------------------------
+
+#: The routes.
+CREATE_PUBLIC_ACQUISITION_PATH = "/v3/workspaces/{workspace_id}/public-acquisitions"
+GET_PUBLIC_ACQUISITION_PATH = (
+    "/v3/workspaces/{workspace_id}/public-acquisitions/{crawler_session_id}"
+)
+PUBLIC_ACQUISITION_RECEIPT_PATH = (
+    "/v3/workspaces/{workspace_id}/public-acquisitions/{crawler_session_id}/receipt"
+)
+
+#: ``public-crawl.schema.json#/$defs/public_acquisition_session/properties/status``.
+SESSION_STATUSES = ("enqueue_pending", "enqueued", "result_ready", "failed", "cancelled")
+
+#: What each value of ``receipt_binding.reader_binding`` means, in the words a person needs. Not a
+#: paraphrase of the schema's description: the schema explains the mechanism, and this says what
+#: the reader of a receipt should conclude.
+READER_BINDING_SENTENCE = {
+    "none": (
+        "this request pinned no Reader, so the Receipt carries no fact a Toolbox would have had "
+        "to resolve, and Studio's binding is the whole binding -- it answers exactly what a "
+        "Toolbox on this computer would have answered"
+    ),
+    "worker_toolbox": (
+        "this request pinned a Reader, and the Toolbox that resolved it was the one inside the "
+        "clean room that decoded the bytes; Studio bound the Receipt's budgets to this request's "
+        "own limits and caps without re-deriving that family's certified defaults"
+    ),
+}
+
+#: The one key the local receipt carries that a hosted acquisition genuinely does not have, and
+#: why it is absent rather than empty. ``tests/test_thin_parity.py`` holds the two key sets equal
+#: apart from exactly this, so a field that quietly stopped being reported fails there.
+LOCAL_ONLY_RECEIPT_FIELDS = {
+    "observation_digest": (
+        "an observation is sealed by the local adapter pipeline, which a hosted profile does not "
+        "run; what Studio holds about this acquisition is its session and the Receipt below"
+    )
+}
+
+#: How long to wait for the clean room, and how the wait grows. The same ceiling
+#: ``ux.hosted_acquisition.POLL_TIMEOUT_SECONDS`` gives the local hosted route, so the two profiles
+#: give up on the same acquisition at the same moment.
+POLL_TIMEOUT_SECONDS = 1800.0
+POLL_INITIAL_SECONDS = 0.5
+POLL_MAX_SECONDS = 5.0
+
+#: A hard ceiling on the quarantined bundle this lane will bring back, above the derived bound
+#: below and below anything that would be a memory problem on a laptop. The contract admits a 6 GiB
+#: bundle; a thin client parses the document whole, so it says what it will not do rather than
+#: discovering it as a MemoryError.
+MAX_RESULT_BUNDLE_BYTES = 512 * 1024 * 1024
+
+#: The slack the derived bound allows over the base64url expansion of the normalized content: the
+#: Receipt, the observation and the envelope around them.
+RESULT_BUNDLE_OVERHEAD_BYTES = 1024 * 1024
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_FAILURE_CODE = re.compile(r"^[A-Z][A-Z0-9_]{2,127}$")
+
+
+def _failure_code(value: Any, fallback: str) -> str:
+    """Return a bounded machine code from Studio, never its arbitrary diagnostic text.
+
+    ``failure_code`` is the existing terminal worker-result channel.  A crawler bootstrap failure
+    has no upload capability yet, so it cannot produce the usual signed failure bundle; Studio
+    settles the acquisition with this field instead.  Preserve its exact stable code, but do not
+    let a malformed server response turn an error body, token, or line break into CLI output.
+    """
+
+    return value if isinstance(value, str) and _FAILURE_CODE.fullmatch(value) else fallback
+
+
+class AcquireRefusal(ThinLaneError):
+    """A refusal this command renders as its own receipt rather than as an error.
+
+    Distinct from a plain :class:`ThinLaneError` because the two are different answers. A
+    ``ThinLaneError`` is "this call did not happen"; this is "it happened and the answer was no",
+    which the local lane already prints as a full ``status: "refused"`` document with an operator
+    action beside it. Routing the second through the first would report a publisher's refusal in
+    the words used for a broken client.
+    """
+
+    def __init__(self, code: str, detail: str, action: str, **extra: Any) -> None:
+        super().__init__(code, detail)
+        self.action = action
+        self.extra = extra
+
+    def to_receipt(self) -> dict[str, Any]:
+        return {
+            "headline": REFUSED_HEADLINE,
+            "schema_version": ACQUISITION_RECEIPT_VERSION,
+            "status": "refused",
+            "lane": "hosted",
+            "code": self.code,
+            "refusal": self.detail,
+            "operator_action": self.action,
+            **self.extra,
+        }
+
+
+class StudioAcquisitionClient(StudioApiClient):
+    """Open one hosted acquisition, watch it, and read the Receipt Studio bound for it."""
+
+    def create(self, body: Mapping[str, Any], *, idempotency_key: str) -> dict[str, Any]:
+        return self._call(
+            "POST",
+            CREATE_PUBLIC_ACQUISITION_PATH.format(
+                workspace_id=self._session.workspace_id,
+            ),
+            body=body,
+            extra_headers={"Idempotency-Key": idempotency_key},
+            expected=(202,),
+        )
+
+    def get(self, crawler_session_id: str) -> dict[str, Any]:
+        return self._call(
+            "GET",
+            GET_PUBLIC_ACQUISITION_PATH.format(
+                workspace_id=self._session.workspace_id,
+                crawler_session_id=crawler_session_id,
+            ),
+            expected=(200,),
+        )
+
+    def receipt(self, crawler_session_id: str) -> dict[str, Any]:
+        return self._call(
+            "GET",
+            PUBLIC_ACQUISITION_RECEIPT_PATH.format(
+                workspace_id=self._session.workspace_id,
+                crawler_session_id=crawler_session_id,
+            ),
+            expected=(200,),
+        )
+
+
+# --------------------------------------------------------------------------------------------
+# The operator's document, read without the engine
+# --------------------------------------------------------------------------------------------
+
+
+def read_acquisition_document(path: Path) -> dict[str, Any]:
+    """Read the acquisition document under the same rule every named path is read under.
+
+    ``ux.plain_file`` rather than ``read_bytes``: open once, ask the descriptor what it is, read
+    that descriptor under a bound. A hosted profile does not get a laxer rule about a path somebody
+    typed than the local profile has.
+    """
+
+    try:
+        raw = read_plain_file(path, max_bytes=MAX_DOCUMENT_BYTES)
+    except PlainFileRefusal as refusal:
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            _why(refusal),
+            "point --acquisition at a readable canonical JSON acquisition document",
+        ) from None
+    except OSError as error:
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            f"the acquisition document could not be read: {error}",
+            "point --acquisition at a readable canonical JSON acquisition document",
+        ) from error
+    try:
+        value = parse_foreign_json(raw)
+    except CanonicalJSONError as error:
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            f"the acquisition document could not be read as canonical JSON: {error}",
+            "point --acquisition at a readable canonical JSON acquisition document",
+        ) from error
+    if not isinstance(value, dict):
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            "the acquisition document is not a JSON object",
+            "point --acquisition at a readable canonical JSON acquisition document",
+        )
+    return value
+
+
+def _why(refusal: PlainFileRefusal) -> str:
+    """Why one named path did not yield a document, in the words the local lane already uses.
+
+    ⚠ THE KIND IS NAMED FROM THE DESCRIPTOR, AND THE SENTENCE CARRIES THE PATH IT LOOKED AT.
+    ``ux.path_kind.name_of_kind`` reads the mode the open actually observed, and the same sentence
+    names ``refusal.path``, so what is claimed and what was inspected are visibly the same
+    coordinate -- which is exactly what ``scripts/path_kind_gate.py`` reads these strings for. A
+    sentence that named a kind without the path it looked at would be a claim about some other
+    file.
+    """
+
+    if refusal.reason == MISSING:
+        # ⚠ `presence_at`, not the word "nothing". `MISSING` says the open found no entry, and the
+        # sentence still has to look before it says so: the one thing `peek` learned the hard way
+        # is that "there is nothing there" said about a link sitting right in front of somebody
+        # sends them to check their spelling instead of to repoint it.
+        return (
+            f"there is {presence_at(refusal.path) or UNKNOWN_KIND} at {refusal.path}: this "
+            "command reads a document out of a file"
+        )
+    if refusal.reason == DANGLING:
+        return (
+            f"there is {name_of_kind(refusal.mode) or UNKNOWN_KIND} at {refusal.path}, and it "
+            "leads nowhere: this command reads a document out of a file"
+        )
+    if refusal.reason == NOT_PLAIN:
+        return (
+            f"there is {name_of_kind(refusal.mode) or UNKNOWN_KIND} at {refusal.path}: this "
+            "command reads a document out of a file, not out of a pipe, a socket, or a device"
+        )
+    return f"{refusal.path} holds more than {MAX_DOCUMENT_BYTES} bytes"
+
+
+def hosted_query(document: Mapping[str, Any]) -> dict[str, Any]:
+    """Compose the exact ``public_https_query`` this acquisition asks Studio for.
+
+    Composed here from the operator's own document, field for field, in the shape
+    ``sources.hosted.HostedPublicHttpsAdapter`` composes it on a full install -- and no wider. A
+    hosted profile has no adapter registry to run governance through, so what it can do is refuse
+    every document the hosted route would refuse anyway, name the refusal, and send exactly the
+    query the contract admits.
+    """
+
+    if document.get("schema_version") != ACQUISITION_DOCUMENT_VERSION:
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_VERSION",
+            f"the acquisition document must state schema_version {ACQUISITION_DOCUMENT_VERSION!r}",
+            "correct the document's schema_version and run again",
+        )
+    adapter = _object(document, "adapter")
+    request = _object(document, "request")
+    limits = _limits(document)
+    adapter_id = adapter.get("adapter_id")
+    if adapter_id == COLLECTION_ADAPTER_ID:
+        raise AcquireRefusal(
+            COLLECTION_UNSUPPORTED_CODE,
+            COLLECTION_UNSUPPORTED_DETAIL,
+            "acquire this collection's members one address at a time, or run it on a full "
+            "install with both --clean-room-attestation and --network-policy-attestation",
+        )
+    if adapter.get("source_class") not in {"user_url", "user_api", "external_adapter"}:
+        raise AcquireRefusal(
+            "ACQUIRE_HOSTED_ADAPTER_CLASS",
+            "the hosted public HTTPS clean room fetches a user_url, user_api or external_adapter "
+            "source, and this document names another class",
+            "correct adapter.source_class, or run this on a full install with both attestations",
+        )
+    if request.get("credential_reference_id") is not None:
+        raise AcquireRefusal(
+            "AUTHENTICATED_SOURCE_REQUIRES_TRUSTED_GATEWAY",
+            "hosted public acquisition receives no source credential",
+            "route an authenticated source through a registered typed acquisition boundary",
+        )
+    query = _object(request, "query")
+    url = query.get("url")
+    if not isinstance(url, str) or not url.startswith("https://") or urlsplit(url).port is not None:
+        raise AcquireRefusal(
+            "ACQUIRE_TARGET_UNREADABLE",
+            "the request query states no credential-free https address on the implicit port 443",
+            "state query.url as an https address without a port, user information or a fragment",
+        )
+    data_format = query.get("data_format")
+    filename = query.get("filename")
+    if not isinstance(data_format, str) or not isinstance(filename, str) or not filename:
+        raise AcquireRefusal(
+            "ACQUIRE_OUTPUT_COORDINATES",
+            "the request query states no data_format and filename for what comes back",
+            "state query.data_format and query.filename in the acquisition document",
+        )
+    reader_pin = request.get("reader_pin")
+    resource_caps = request.get("resource_caps")
+    if reader_pin is None and resource_caps is not None:
+        raise AcquireRefusal(
+            "ACQUIRE_RESOURCE_CAPS_WITHOUT_READER",
+            "resource caps narrow a pinned Reader's budgets, and this request pins no Reader",
+            "pin the Reader these caps narrow, or drop request.resource_caps",
+        )
+    return {
+        "url": url,
+        "data_format": data_format,
+        "filename": filename,
+        "reader_pin": None if reader_pin is None else dict(_mapping(reader_pin, "reader_pin")),
+        "resource_caps": (
+            None if resource_caps is None else dict(_mapping(resource_caps, "resource_caps"))
+        ),
+        "limits": limits,
+    }
+
+
+def _object(value: Mapping[str, Any], field: str) -> Mapping[str, Any]:
+    selected = value.get(field)
+    if not isinstance(selected, Mapping):
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            f"the acquisition document states no {field} object",
+            "correct the acquisition document and run again",
+        )
+    return selected
+
+
+def _mapping(value: Any, field: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            f"request.{field} is stated but is not an object",
+            "correct the acquisition document and run again",
+        )
+    return value
+
+
+def _limits(document: Mapping[str, Any]) -> dict[str, int]:
+    """The four bounds, refused against the hosted contract's caps before anything is contacted."""
+
+    stated = _object(document, "limits")
+    limits: dict[str, int] = {}
+    for name in HOSTED_LIMIT_CAPS:
+        value = stated.get(name)
+        if name == "max_normalized_bytes" and value is None:
+            value = stated.get("max_source_bytes")
+        if type(value) is not int or value < 1:
+            raise AcquireRefusal(
+                "ACQUISITION_DOCUMENT_UNREADABLE",
+                f"the acquisition document states no whole-number limits.{name}",
+                "state every limit this acquisition runs under, as a whole number",
+            )
+        limits[name] = value
+    over = {name: limits[name] for name, cap in HOSTED_LIMIT_CAPS.items() if limits[name] > cap}
+    if over:
+        raise AcquireRefusal(
+            "ACQUIRE_HOSTED_LIMITS_OVER_CAP",
+            "this document's limits exceed the hosted Courier contract caps: "
+            + "; ".join(
+                f"{name}={value} exceeds the hosted cap {HOSTED_LIMIT_CAPS[name]}"
+                for name, value in sorted(over.items())
+            ),
+            "lower the named limits to the hosted caps below and run again, or run this on a full "
+            "install with both --clean-room-attestation and --network-policy-attestation",
+            hosted_limit_caps=dict(HOSTED_LIMIT_CAPS),
+        )
+    return limits
+
+
+def allowed_hostnames(values: Sequence[str] | None) -> tuple[str, ...]:
+    """The exact hosts this acquisition may reach. There is no default and no override."""
+
+    if not values:
+        raise AcquireRefusal(
+            "ACQUIRE_EGRESS_ALLOWLIST_REQUIRED",
+            DENY_DEFAULT_POSTURE + " No --allow-host was supplied.",
+            "pass --allow-host <hostname> once for each exact host this acquisition may reach",
+        )
+    return tuple(sorted(dict.fromkeys(values)))
+
+
+def require_allowlisted_target(url: str, hostnames: tuple[str, ...]) -> None:
+    """Refuse an address outside the supplied allowlist before anything is contacted.
+
+    ⚠ NOT THE AUTHORITY, in either profile. Studio's reviewed egress policy is what actually
+    bounds the Courier, and it is applied inside the clean room against the composed address. This
+    is the same early refusal the local lane makes for the same reason: an address the operator
+    never allowlisted should be a named sentence at the terminal, before a token is minted and a
+    session exists on the backend.
+    """
+
+    parsed = urlsplit(url)
+    hostname = (parsed.hostname or "").lower()
+    if not hostname or hostname not in hostnames:
+        raise AcquireRefusal(
+            "ACQUIRE_EGRESS_DENIED",
+            f"the requested host {hostname!r} is not in the allowlist supplied for this "
+            "acquisition",
+            "pass --allow-host for that exact host, or correct the address in the document",
+            host_allowlist=list(hostnames),
+        )
+
+
+def source_authority_digest(source_id: str, query: Mapping[str, Any]) -> str:
+    """The digest that binds this exact query to this exact source, as the local lane computes it.
+
+    Restated rather than imported for the reason every literal at the top of this module is, and
+    held byte-equal to ``ux.hosted_acquisition.source_authority_digest`` by a drift gate: the two
+    profiles must ask Studio for the same acquisition, and a digest that differed by a field would
+    open a second session for the same request and neither would be wrong about it.
+    """
+
+    return canonical_sha256(
+        {
+            "schema_version": SOURCE_AUTHORITY_SCHEMA,
+            "source_id": source_id,
+            "adapter_id": "public.https",
+            "adapter_version": "1.0.0",
+            "query": dict(query),
+        }
+    )
+
+
+def transport_envelope_digest(receipt: Mapping[str, Any]) -> str:
+    """``clean_room_attestation_digest``, reproduced from facts Studio already stated.
+
+    The same five-field envelope ``sources.hosted`` seals on a full install, over the same values.
+    It is a digest and not a check -- nothing here is verified by computing it -- and it is
+    computed rather than omitted precisely so that key means the same thing in both profiles.
+    """
+
+    return canonical_sha256(
+        {
+            "schema_version": TRANSPORT_ENVELOPE_SCHEMA,
+            "hosted_request_digest": receipt.get("request_digest"),
+            "crawler_transport_evidence_digest": receipt.get("transport_evidence_digest"),
+            "egress_policy_attestation": receipt.get("egress_policy_attestation"),
+            "clean_room": dict(CLEAN_ROOM),
+        }
+    )
+
+
+# --------------------------------------------------------------------------------------------
+# The command
+# --------------------------------------------------------------------------------------------
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioAcquisitionClient:
+    return StudioAcquisitionClient(_session(args))
+
+
+#: The local flags a hosted acquisition cannot honour, and the sentence each one gets.
+_ACQUIRE_NO_EFFECT = (
+    (
+        "clean_room_attestation",
+        "--clean-room-attestation",
+        "the clean room this ran in is Studio's, and its policy is attested by Studio rather than "
+        "by whoever typed this command",
+    ),
+    (
+        "network_policy_attestation",
+        "--network-policy-attestation",
+        "the egress policy this ran under is the reviewed hosted one, and the Receipt carries its "
+        "attestation",
+    ),
+)
+
+
+def acquire(
+    args: argparse.Namespace,
+    *,
+    client: StudioAcquisitionClient | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """``mr-data acquire``: fetch one public address in Studio's clean room, bound Receipt and all.
+
+    Same document, same flags, same receipt keys as the local lane's hosted route -- which is the
+    route a full install already takes when it is given neither attestation. What differs is where
+    the last step happens, and the payload names that rather than leaving the word Receipt to carry
+    it.
+    """
+
+    document = read_acquisition_document(Path(args.acquisition).expanduser())
+    query = hosted_query(document)
+    hostnames = allowed_hostnames(getattr(args, "allow_host", None))
+    require_allowlisted_target(query["url"], hostnames)
+    _refuse_cadence(args)
+    snapshots, staging = _acquire_directories(Path(args.output).expanduser())
+    request = _object(document, "request")
+    source_id = request.get("source_id")
+    if not isinstance(source_id, str) or not source_id:
+        raise AcquireRefusal(
+            "ACQUISITION_DOCUMENT_UNREADABLE",
+            "the acquisition document names no source_id",
+            "state request.source_id in the acquisition document",
+        )
+    authority = source_authority_digest(source_id, query)
+    selected = client or _client(args)
+    session = _open_session(
+        selected,
+        source_id=source_id,
+        authority=authority,
+        query=query,
+        attempt_id=str(getattr(args, "attempt_id", "")),
+    )
+    crawler_session_id = _session_id(session)
+    session = _await_result(selected, crawler_session_id, session, sleep=sleep, clock=clock)
+    published = selected.receipt(crawler_session_id)
+    _bind_published_receipt(
+        published,
+        crawler_session_id=crawler_session_id,
+        workspace_id=selected.session.workspace_id,
+        source_id=source_id,
+        authority=authority,
+        request_digest=session.get("request_digest"),
+    )
+    if published.get("outcome") == "refused":
+        raise _courier_refusal(published)
+    receipt = published.get("acquisition_receipt")
+    binding = published.get("receipt_binding")
+    if not isinstance(receipt, Mapping) or not isinstance(binding, Mapping):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio reported an acquisition with no bound Receipt"
+        )
+    if set(receipt) != RECEIPT_FIELDS:
+        raise ThinLaneError(
+            "THIN_RECEIPT_FIELDS",
+            "Studio published a Receipt whose fields are not the fields this contract declares; "
+            "the two repositories are pinned to different versions of it",
+        )
+    content = _fetch_normalized_content(selected, session, receipt, binding, staging)
+    snapshot = _seal(snapshots, content, receipt)
+    return _acquisition_facts(
+        document=document,
+        receipt=receipt,
+        binding=binding,
+        snapshot=snapshot,
+        hostnames=hostnames,
+        crawler_session_id=crawler_session_id,
+        workspace_id=str(selected.session.workspace_id),
+        args=args,
+    )
+
+
+def acquire_exit_code(payload: Mapping[str, Any]) -> int:
+    """``1`` when the answer was no, matching what the local command already exits with."""
+
+    return 1 if payload.get("status") == "refused" else 0
+
+
+def _refuse_cadence(args: argparse.Namespace) -> None:
+    """The local refusal, unchanged: a probe run in Studio's clean room is recorded by Studio.
+
+    Kept identical rather than made to work, because the fact behind it has not changed. An
+    empirical cadence history is a record of probes THIS computer made, and a hosted probe is one
+    Studio made; appending it here would put a local timestamp on somebody else's observation.
+    """
+
+    if getattr(args, "cadence_history", None) is None:
+        if getattr(args, "cadence_authority", None) is not None:
+            raise AcquireRefusal(
+                "CADENCE_HISTORY_REQUIRED",
+                "a cadence authority was supplied with no history to record it in",
+                "pass --cadence-history with the folder this source's probes are recorded in",
+            )
+        return
+    raise AcquireRefusal(
+        "CADENCE_HOSTED_ROUTE_UNSUPPORTED",
+        "a probe run in Studio's hosted clean room is recorded by Studio, not here",
+        "run this probe on a full install with both attestations, or drop --cadence-history",
+    )
+
+
+def _acquire_directories(output: Path) -> tuple[Path, Path]:
+    """The snapshot and staging roots, both inside the operator's output directory."""
+
+    directory = output.absolute()
+    if directory.is_symlink() or not directory.is_dir():
+        raise AcquireRefusal(
+            "ACQUIRE_OUTPUT_DIRECTORY",
+            "--output must name an existing directory that is not a symlink",
+            "create the output directory first; everything this command writes stays inside it",
+        )
+    roots: list[Path] = []
+    for name in ("snapshots", "staging"):
+        child = directory / name
+        child.mkdir(mode=0o700, exist_ok=True)
+        if child.is_symlink() or not child.is_dir():
+            raise AcquireRefusal(
+                "ACQUIRE_OUTPUT_DIRECTORY",
+                f"the output directory's {name!r} entry is not a directory",
+                "remove that entry, or point --output at a clean directory",
+            )
+        roots.append(child)
+    return roots[0], roots[1]
+
+
+def _open_session(
+    client: StudioAcquisitionClient,
+    *,
+    source_id: str,
+    authority: str,
+    query: Mapping[str, Any],
+    attempt_id: str,
+) -> dict[str, Any]:
+    """Ask Studio for one clean-room acquisition of exactly this query.
+
+    The idempotency key is derived from the workspace, the authority digest and the attempt, not
+    minted at random: a retry of one attempt must reach the same session rather than open a second
+    clean room against a stranger's server, and two different attempts must not collide.
+    """
+
+    key = "mr-data-acquire-" + canonical_sha256(
+        {
+            "schema_version": "hosted-public-acquisition-idempotency.v1",
+            "workspace_id": str(client.session.workspace_id),
+            "source_authority_digest": authority,
+            "acquisition_attempt_id": attempt_id,
+        }
+    )
+    return client.create(
+        {
+            "schema_version": "3.0.0",
+            "workspace_id": str(client.session.workspace_id),
+            "source_id": source_id,
+            "source_authority_digest": authority,
+            "query": dict(query),
+        },
+        idempotency_key=key,
+    )
+
+
+def _session_id(session: Mapping[str, Any]) -> str:
+    value = session.get("crawler_session_id")
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio opened an acquisition without an identifier"
+        ) from error
+
+
+def _await_result(
+    client: StudioAcquisitionClient,
+    crawler_session_id: str,
+    session: Mapping[str, Any],
+    *,
+    sleep: Callable[[float], None],
+    clock: Callable[[], float],
+) -> dict[str, Any]:
+    """Wait for the clean room, refusing a session Studio moved under us.
+
+    The immutable coordinates are compared on every poll. A session whose request digest or
+    requester changed between two readings is not a slow session, it is a different one, and
+    following it would be downloading bytes fetched for somebody else's request.
+    """
+
+    observed = dict(session)
+    deadline = clock() + POLL_TIMEOUT_SECONDS
+    delay = POLL_INITIAL_SECONDS
+    while observed.get("status") not in {"result_ready", "failed", "cancelled"}:
+        if clock() >= deadline:
+            raise AcquireRefusal(
+                "HOSTED_ACQUISITION_TIMEOUT",
+                "the hosted public acquisition did not finish",
+                "run this again; the session is Studio's and the attempt identifier reaches it",
+            )
+        sleep(delay)
+        delay = min(delay * 2, POLL_MAX_SECONDS)
+        polled = client.get(crawler_session_id)
+        for field in (
+            "schema_version",
+            "crawler_session_id",
+            "workspace_id",
+            "requester_principal_id",
+            "source_id",
+            "source_authority_digest",
+            "adapter_id",
+            "adapter_version",
+            "request_id",
+            "request_digest",
+            "egress_policy_attestation",
+            "created_at",
+            "expires_at",
+        ):
+            if polled.get(field) != observed.get(field):
+                raise ThinLaneError(
+                    "THIN_SESSION_BINDING",
+                    "Studio changed an immutable hosted acquisition coordinate",
+                )
+        observed = polled
+    if observed.get("status") == "failed":
+        raise AcquireRefusal(
+            _failure_code(observed.get("failure_code"), "HOSTED_ACQUISITION_FAILED"),
+            COURIER_FAILURE_DETAIL,
+            "read the failure code above; it names what the isolated Courier stopped on",
+        )
+    if observed.get("status") == "cancelled":
+        raise AcquireRefusal(
+            "HOSTED_ACQUISITION_CANCELLED",
+            "the hosted public acquisition was cancelled",
+            "the clean-room work was stopped; start a new acquisition only if the source is "
+            "still needed",
+        )
+    return observed
+
+
+def _bind_published_receipt(
+    published: Mapping[str, Any],
+    *,
+    crawler_session_id: str,
+    workspace_id: UUID,
+    source_id: str,
+    authority: str,
+    request_digest: Any,
+) -> None:
+    """Refuse a Receipt that is not this session's, before anything is read out of it.
+
+    Five equalities, and none of them is about a Reader. This is the whole of what a client can
+    settle for itself when the binding was performed elsewhere: that the document in hand is the
+    document for the acquisition it asked for.
+    """
+
+    if (
+        published.get("schema_version") != "mostlyright-public-acquisition-receipt.v1"
+        or published.get("crawler_session_id") != crawler_session_id
+        or published.get("workspace_id") != str(workspace_id)
+        or published.get("source_id") != source_id
+        or published.get("source_authority_digest") != authority
+        or published.get("request_digest") != request_digest
+        or published.get("outcome") not in {"acquired", "refused"}
+    ):
+        raise ThinLaneError(
+            "THIN_RECEIPT_BINDING",
+            "Studio published a Receipt that is not this acquisition session's",
+        )
+
+
+def _courier_refusal(published: Mapping[str, Any]) -> AcquireRefusal:
+    """The Courier reached the source and the source said no. That is an answer."""
+
+    failure = published.get("crawler_failure")
+    failure = failure if isinstance(failure, Mapping) else {}
+    return AcquireRefusal(
+        _failure_code(failure.get("failure_code"), "HOSTED_ACQUISITION_REFUSED"),
+        COURIER_REFUSAL_DETAIL,
+        "the code above is the source's own refusal, sealed by the Courier; nothing about this "
+        "machine changes it",
+        retryable=failure.get("retryable"),
+        crawler_session_id=published.get("crawler_session_id"),
+        source_id=published.get("source_id"),
+        request_digest=published.get("request_digest"),
+        network_fetch_performed=True,
+    )
+
+
+def _fetch_normalized_content(
+    client: StudioAcquisitionClient,
+    session: Mapping[str, Any],
+    receipt: Mapping[str, Any],
+    binding: Mapping[str, Any],
+    staging: Path,
+) -> bytes:
+    """Bring the quarantined bundle back, and hash it twice before believing a byte of it.
+
+    Once against ``receipt_binding.result_digest``, which is what Studio authenticated, and once
+    against the Receipt's own ``normalized_content_sha256`` after the chunks are decoded. Both,
+    rather than either: the first says the bundle is the bundle, the second says the bytes about to
+    be written are the bytes the Receipt describes.
+    """
+
+    download = session.get("result_download")
+    if not isinstance(download, Mapping):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio reported a ready acquisition with no download"
+        )
+    declared = download.get("bundle_size_bytes")
+    normalized_size = receipt.get("normalized_size_bytes")
+    if type(declared) is not int or type(normalized_size) is not int:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "the quarantined bundle declares no usable size"
+        )
+    bound = min(
+        MAX_RESULT_BUNDLE_BYTES,
+        -(-normalized_size // 3) * 4 + RESULT_BUNDLE_OVERHEAD_BYTES,
+    )
+    if declared > bound:
+        raise AcquireRefusal(
+            "ACQUIRE_RESULT_BUNDLE_TOO_LARGE",
+            f"the quarantined result bundle declares {declared} bytes, above the {bound} this "
+            "profile reads whole",
+            "acquire this source on a full install, which streams the bundle rather than reading "
+            "it whole",
+        )
+    result_digest = binding.get("result_digest")
+    if not isinstance(result_digest, str) or _DIGEST.fullmatch(result_digest) is None:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio's binding carries no result digest to check against"
+        )
+    destination = staging / f"{session['crawler_session_id']}.hosted-crawler-result.json"
+    artifact = download_signed_artifact(
+        {
+            "signed_url": download.get("signed_url", ""),
+            "expected_content_digest": f"sha256:{result_digest}",
+            "expected_size_bytes": declared,
+            "media_type": download.get("media_type"),
+            "required_headers": download.get("required_headers"),
+        },
+        destination,
+        transport=client.transport,
+    )
+    try:
+        raw = artifact.path.read_bytes()
+        content = _normalized_content(raw, receipt)
+    finally:
+        # The quarantined bundle is not an output of this command; the snapshot is. Leaving it
+        # behind would put an unlabelled copy of somebody's source bytes in a folder nobody was
+        # told about.
+        artifact.path.unlink(missing_ok=True)
+    return content
+
+
+def _normalized_content(raw: bytes, receipt: Mapping[str, Any]) -> bytes:
+    """Decode the bundle's chunks and refuse them unless they are the bytes the Receipt names."""
+
+    try:
+        bundle = parse_foreign_json(raw)
+    except CanonicalJSONError as error:
+        raise ThinLaneError(
+            "THIN_RESULT_INVALID", "the quarantined result bundle is not a readable document"
+        ) from error
+    chunks = bundle.get("normalized_content_base64url_chunks") if isinstance(bundle, dict) else None
+    if not isinstance(chunks, list) or not chunks:
+        raise ThinLaneError(
+            "THIN_RESULT_INVALID", "the quarantined result bundle carries no normalized content"
+        )
+    joined = "".join(chunk for chunk in chunks if isinstance(chunk, str))
+    try:
+        content = base64.urlsafe_b64decode(joined + "=" * (-len(joined) % 4))
+    except (ValueError, TypeError) as error:
+        raise ThinLaneError(
+            "THIN_RESULT_INVALID", "the quarantined result bundle's content is not base64url"
+        ) from error
+    observed = hashlib.sha256(content).hexdigest()
+    if observed != receipt.get("normalized_content_sha256") or len(content) != receipt.get(
+        "normalized_size_bytes"
+    ):
+        raise ThinLaneError(
+            "THIN_RESULT_DIGEST_MISMATCH",
+            "the bytes in the quarantined bundle are not the bytes the bound Receipt describes",
+        )
+    return content
+
+
+def _seal(snapshots: Path, content: bytes, receipt: Mapping[str, Any]) -> Path:
+    """Write the normalized bytes under their own digest, never over something already there.
+
+    The same content-addressed name ``acquisition.http.seal_content_addressed_snapshot`` writes on
+    a full install, so a snapshot folder filled by either profile reads the same way. An existing
+    file with this name already holds these exact bytes -- the name IS the digest -- so it is left
+    alone rather than rewritten.
+    """
+
+    suffix = receipt.get("normalized_data_format")
+    if not isinstance(suffix, str) or not suffix.isalnum():
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "the bound Receipt names no output format for these bytes"
+        )
+    destination = snapshots / f"{hashlib.sha256(content).hexdigest()}.{suffix}"
+    if destination.exists():
+        return destination
+    staged = destination.with_name(destination.name + ".partial")
+    staged.write_bytes(content)
+    staged.replace(destination)
+    return destination
+
+
+def _acquisition_facts(
+    *,
+    document: Mapping[str, Any],
+    receipt: Mapping[str, Any],
+    binding: Mapping[str, Any],
+    snapshot: Path,
+    hostnames: tuple[str, ...],
+    crawler_session_id: str,
+    workspace_id: str,
+    args: argparse.Namespace,
+) -> dict[str, Any]:
+    """The receipt, under the keys the local lane already uses for the same facts.
+
+    ``tests/test_thin_parity.py`` holds this key set equal to ``cli._acquisition_facts``'s, apart
+    from :data:`LOCAL_ONLY_RECEIPT_FIELDS`, so a script that reads ``content_sha256`` reads it in
+    both profiles and a key that quietly stopped being reported fails there rather than in
+    somebody's pipeline.
+    """
+
+    reader_binding = binding.get("reader_binding")
+    adapter = _object(document, "adapter")
+    return {
+        "headline": ACQUIRED_HEADLINE,
+        "schema_version": ACQUISITION_RECEIPT_VERSION,
+        "status": "source_acquired",
+        "lane": "hosted",
+        "source_id": receipt.get("source_id"),
+        "adapter_id": receipt.get("adapter_id"),
+        "adapter_version": receipt.get("adapter_version"),
+        "source_class": adapter.get("source_class"),
+        "media_type": receipt.get("normalized_media_type"),
+        "data_format": receipt.get("normalized_data_format"),
+        "size_bytes": receipt.get("normalized_size_bytes"),
+        "content_sha256": receipt.get("normalized_content_sha256"),
+        "snapshot_path": str(snapshot),
+        "receipt_digest": canonical_sha256(dict(receipt)),
+        "host_allowlist": list(hostnames),
+        "acquisition_environment": HOSTED_ACQUISITION_ENVIRONMENT,
+        "clean_room_attestation_digest": transport_envelope_digest(receipt),
+        "external_network_policy_attestation": receipt.get("egress_policy_attestation"),
+        "attestation_authority": HOSTED_ATTESTATION_AUTHORITY,
+        "reader_decode_identity_present": receipt.get("family_id") is not None,
+        "network_fetch_performed": True,
+        "source_uri": receipt.get("source_url"),
+        "final_uri": receipt.get("final_url"),
+        # The honest half. Everything above is a fact about the acquisition; these three are facts
+        # about who established them, which is the one thing that differs between the profiles.
+        "bound_by": binding.get("bound_by"),
+        "reader_binding": reader_binding,
+        "binding_note": READER_BINDING_SENTENCE.get(
+            str(reader_binding),
+            "Studio named a binding this client has no sentence for; read receipt_binding below",
+        ),
+        "crawler_session_id": crawler_session_id,
+        "workspace_id": workspace_id,
+        "receipt": dict(receipt),
+        "receipt_binding": dict(binding),
+        "not_reported_here": dict(LOCAL_ONLY_RECEIPT_FIELDS),
+        "flags_without_effect": _no_effect(args, _ACQUIRE_NO_EFFECT),
+    }
+
+
+__all__ = [
+    "ACQUIRED_HEADLINE",
+    "ACQUISITION_DOCUMENT_VERSION",
+    "ACQUISITION_RECEIPT_VERSION",
+    "CLEAN_ROOM",
+    "COLLECTION_ADAPTER_ID",
+    "COLLECTION_UNSUPPORTED_CODE",
+    "COLLECTION_UNSUPPORTED_DETAIL",
+    "COURIER_FAILURE_DETAIL",
+    "COURIER_REFUSAL_DETAIL",
+    "CREATE_PUBLIC_ACQUISITION_PATH",
+    "DENY_DEFAULT_POSTURE",
+    "GET_PUBLIC_ACQUISITION_PATH",
+    "HOSTED_ACQUISITION_ENVIRONMENT",
+    "HOSTED_ATTESTATION_AUTHORITY",
+    "HOSTED_LIMIT_CAPS",
+    "LOCAL_ONLY_RECEIPT_FIELDS",
+    "MAX_DOCUMENT_BYTES",
+    "MAX_RESULT_BUNDLE_BYTES",
+    "POLL_TIMEOUT_SECONDS",
+    "PUBLIC_ACQUISITION_RECEIPT_PATH",
+    "READER_BINDING_SENTENCE",
+    "RECEIPT_FIELDS",
+    "REFUSED_HEADLINE",
+    "SESSION_STATUSES",
+    "SOURCE_AUTHORITY_SCHEMA",
+    "TRANSPORT_ENVELOPE_SCHEMA",
+    "AcquireRefusal",
+    "StudioAcquisitionClient",
+    "acquire",
+    "acquire_exit_code",
+    "allowed_hostnames",
+    "hosted_query",
+    "read_acquisition_document",
+    "require_allowlisted_target",
+    "source_authority_digest",
+    "transport_envelope_digest",
+]