mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/hosted_dataset.py

@@ -0,0 +1,1500 @@
+"""Bring one released hosted Build down and derive its table notebook here.
+
+The hosted half of a deployment ends with Studio releasing an independently checked Build. This
+module is the local half: it reads that release through the pinned generated client, redeems one
+Studio-issued signed download session for the exact sealed evidence, verifies the transferred bytes
+against the digests the release already sealed, rebuilds the Build tree on this machine, verifies
+*that* by ordinary local replay, and only then asks the existing deterministic generator for
+``table.ipynb``.
+
+Three properties are the whole point, and each of them is a refusal rather than a comment.
+
+**A session is a route, not an authority.** The signed session names a size and a digest, and so
+does the sealed artifact record, and so does the released version's own artifact reference. Bytes
+are accepted only where all three agree, so a session that names a digest of its own decides
+nothing. This is the notebook-sidecar rule of ``docs/ARCHITECTURE.md`` applied one layer out: a
+transport cannot authorize what it carries.
+
+**Nothing is exposed before it is verified.** The transfer is bounded and streamed through
+:class:`ResultBytesVerifier`, so a download that will be refused never materializes; the envelope
+is decoded against the released Build fingerprint before a byte reaches the filesystem; the
+rebuilt tree is verified by :func:`pipeline.verify_candidate` before the notebook is derived from
+it; and the notebook is installed by the existing atomic writer, so a half-written one is never
+visible. Rerunning after an interruption converges on the same verified result.
+
+**The notebook is derived here, never transported.** Studio has no notebook to offer and would not
+be believed if it had one -- the viewer re-derives the notebook from its own verified snapshot and
+compares bytes before it will show a Table tab (``viewer.py`` ``_dataset_is_admissible``). This
+module therefore lands exactly what the local generator needs to reproduce it, which is the sealed
+Build tree, and nothing that only a remote actor could vouch for.
+
+Refusals are :class:`HostedDeployError` because this is the deployment lane's last step, not a
+second lane: a person who ran ``mr-data deploy`` and then ``mr-data deploy-dataset`` is inside one
+journey and should not have to learn two error vocabularies to read its failures.
+"""
+
+from __future__ import annotations
+
+import errno
+import importlib
+import os
+import re
+import secrets
+import ssl
+import stat
+import tempfile
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.error import HTTPError
+from urllib.parse import parse_qsl, urlsplit
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, ProxyHandler, Request, build_opener
+from uuid import UUID
+
+from mostlyright.data_harness import canonical, pipeline
+from mostlyright.data_harness.acquisition.result_download import (
+    RESULT_CHUNK_BYTES,
+    ResultBytesVerifier,
+    ResultDownloadError,
+    ValidatedResultDownload,
+)
+from mostlyright.data_harness.hosted_deploy import (
+    REQUEST_TIMEOUT_SECONDS,
+    STUDIO_SCHEMA_VERSION,
+    HostedDeployError,
+    StudioToken,
+    build_editor_client,
+)
+from mostlyright.data_harness.hosted_handoff import (
+    HANDOFF_RECEIPT_SCHEMA,
+    HANDOFF_RELATIVE_PATH,
+    read_handoff_receipt,
+)
+from mostlyright.data_harness.hosted_worker import (
+    CANDIDATE_CONTRACT_VERSION,
+    HOSTED_ARTIFACT_BYTE_LIMITS,
+    MAX_CANDIDATE_ENVELOPE_BYTES,
+    HostedWorkerError,
+    _decode_candidate_envelope,
+    _restore_candidate_members,
+)
+from mostlyright.data_harness.studio_boundary import StudioBoundaryError, studio_wire_dict
+from mostlyright.data_harness.visual_run.contracts import VisualRunError
+from mostlyright.data_harness.visual_run.reducer import reduce_events
+from mostlyright.data_harness.visual_run.sdk import VisualWork
+from mostlyright.data_harness.visual_run.store import VisualRunStore
+
+# The one artifact kind this handoff redeems. The Parquet alone cannot reconstitute a Build the
+# viewer will admit -- admission verifies the whole sealed tree against `candidate/manifest.json`
+# -- and the sealed evidence envelope already carries every member of that tree, including the
+# Parquet, under one digest the release itself names. So the minimum set is one artifact, and
+# taking more would mean trusting more.
+REQUIRED_ARTIFACT_KIND = "candidate_evidence"
+REQUIRED_ARTIFACT_MEDIA_TYPE = "application/json"
+REQUIRED_ARTIFACT_PURPOSE = "public_sealed_artifact_download"
+
+# The committed object prefix of the Studio artifact store. It is named `quarantine/` for
+# historical reasons that mostlyrightmd/mostlyright-studio#44 is fixing; nothing under it is
+# quarantined, and the short-lived uncommitted uploads live under `pending/` instead. A client
+# allowlist has to admit the prefix the sealed bytes are actually served from, so this admits the
+# committed one and only the committed one.
+GCS_COMMITTED_PREFIX = ("quarantine", "v2")
+GCS_TRANSFER_HOST = "storage.googleapis.com"
+
+# A transferred artifact smaller than this never touches the disk; a larger one spills to a
+# temporary file unlinked at creation, so a refused transfer leaves nothing behind on any exit
+# path. The same threshold `ux/hosted_acquisition` stages hosted results at.
+DOWNLOAD_SPOOL_BYTES = 8 * 1024 * 1024
+# A released version lists the artifacts its run sealed. Eight kinds exist; the bound is generous
+# enough to survive a contract that adds some and small enough that a malformed list cannot turn
+# one handoff into an unbounded sequence of reads.
+MAX_ARTIFACT_REFERENCES = 32
+# How many released versions of one Dataset this will read through to find its own. The listing is
+# unpaginated and returns the whole release history, and a Dataset that refreshes daily reaches
+# four thousand after eleven years -- so this is a bound against a malformed answer, not a limit on
+# how often a Dataset may be refreshed. Selecting from the list costs one linear scan; only the
+# selected record is read in full, so the cost here is the response, not the count.
+MAX_RELEASED_VERSIONS = 4096
+MAX_SIGNED_URL_CHARS = 4096
+# A signed transfer carries a handful of required headers at most. Everything else here is
+# bounded explicitly, so the count is too.
+MAX_SESSION_HEADERS = 16
+# The sealed record of an installed tree, read only to recognise a half-finished install.
+MAX_MANIFEST_BYTES = 8 * 1024 * 1024
+# The generated notebook, read back once to narrate it into the open workbench.
+MAX_NOTEBOOK_BYTES = 64 * 1024 * 1024
+_NO_FOLLOW = getattr(os, "O_NOFOLLOW", 0)
+MAX_SESSION_LIFETIME = timedelta(hours=1)
+
+_SHA256 = re.compile(r"^sha256:[0-9a-f]{64}$")
+_BUCKET = re.compile(r"^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$")
+# The object name is an opaque store-side identifier, not a content digest, so its exact alphabet
+# is Studio's business. What this pattern is for is path confinement: one flat segment with no
+# separator, no traversal, and no escape.
+_OBJECT_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._~-]{7,127}$")
+_HEADER_NAME = re.compile(r"^[A-Za-z0-9-]{1,128}$")
+_FORBIDDEN_HEADERS = frozenset({"authorization", "cookie", "host", "proxy-authorization"})
+
+# One sentence for the three transfer bounds it covers, so the status, media-type and length
+# refusals stay indistinguishable to a caller no matter which of them fired.
+_DOWNLOAD_INVALID_DETAIL = "the released Build transfer violated its media type, status, or size"
+
+
+def _refuse(code: str, detail: str) -> HostedDeployError:
+    """Build one typed refusal, for a caller that writes ``raise _refuse(...)``.
+
+    It returns the error rather than raising it, and every call site raises what it returns. That
+    is not a style preference: the completeness gates that require every typed code to carry a
+    plain sentence and a remediation read the name written at each ``raise``, so a helper that
+    raised for its callers would hide every refusal in this module from them.
+    """
+
+    return HostedDeployError(code, detail)
+
+
+@dataclass(frozen=True)
+class SealedArtifact:
+    """One sealed artifact record, already agreed with the release that names it."""
+
+    artifact_id: UUID
+    workspace_id: UUID
+    run_id: UUID
+    kind: str
+    media_type: str
+    content_digest: str
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class ReleasedBuild:
+    """The released version coordinate, reduced to what the local handoff is allowed to use."""
+
+    dataset_id: UUID
+    table_id: UUID
+    table_version_id: UUID
+    workspace_id: UUID
+    run_id: UUID
+    version_number: int
+    candidate_digest: str
+    artifact_references: tuple[tuple[UUID, str], ...]
+
+
+@dataclass(frozen=True)
+class HostedDatasetHandoff:
+    """What one completed handoff installed, and which released Build it came from."""
+
+    run_dir: Path
+    dataset_id: UUID
+    table_id: UUID
+    table_version_id: UUID
+    version_number: int
+    hosted_run_id: UUID
+    candidate_digest: str
+    artifact_id: UUID
+    artifact_content_digest: str
+    artifact_size_bytes: int
+    notebook_path: Path
+    transferred: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": HANDOFF_RECEIPT_SCHEMA,
+            "run_dir": str(self.run_dir),
+            "dataset_id": str(self.dataset_id),
+            "table_id": str(self.table_id),
+            "table_version_id": str(self.table_version_id),
+            "version_number": self.version_number,
+            "hosted_run_id": str(self.hosted_run_id),
+            "candidate_digest": "sha256:" + self.candidate_digest,
+            "artifact_id": str(self.artifact_id),
+            "artifact_content_digest": self.artifact_content_digest,
+            "artifact_size_bytes": self.artifact_size_bytes,
+            "notebook": str(self.notebook_path),
+            "transferred": self.transferred,
+        }
+
+
+class StudioDatasetReader(Protocol):
+    """The three Studio reads this handoff makes, and nothing that can mutate anything."""
+
+    def released_versions(self, table_id: UUID) -> list[Mapping[str, Any]]: ...
+
+    def artifact(self, artifact_id: UUID) -> Mapping[str, Any]: ...
+
+    def download_session(self, artifact_id: UUID) -> Mapping[str, Any]: ...
+
+    def close(self) -> None: ...
+
+
+class GeneratedStudioDatasetReader:
+    """Read-only released-Build access through the pinned generated editor facade."""
+
+    def __init__(self, token: StudioToken) -> None:
+        self._raw_client, self._client = build_editor_client(token)
+        self._operations = {
+            "list_table_versions": importlib.import_module(
+                "mostlyright_studio.api.tables.list_table_versions"
+            ),
+            "get_artifact": importlib.import_module(
+                "mostlyright_studio.api.artifacts.get_artifact"
+            ),
+            "create_artifact_download_session": importlib.import_module(
+                "mostlyright_studio.api.artifacts.create_artifact_download_session"
+            ),
+        }
+
+    def _read(self, code: str, operation: Any, **arguments: Any) -> Any:
+        """Make one read and give every way it can fail the same typed answer.
+
+        A Studio that cannot be reached is the most ordinary failure this command has -- the
+        docstring above advertises a laptop that slept as the normal case -- and the generated
+        client raises its transport errors as its own exception type, which is not an ``OSError``
+        and is in nothing the command boundary catches. Without this the commonest failure of the
+        command reached a person as a traceback with no code, no fix, and, under ``--json``, no
+        object at all. The token exchange before this and the transfer after it both wrap; only
+        the reads did not.
+        """
+
+        try:
+            response = operation(**arguments)
+        except HostedDeployError:
+            raise
+        except (TypeError, AttributeError):
+            # Not a transport failure: the pinned client was regenerated with a different shape,
+            # and calling it "the cloud could not be reached" would send somebody looking at their
+            # network for a contract change. Let it surface as what it is.
+            raise
+        except Exception as error:
+            raise HostedDeployError(code, "the Mostly Right cloud could not be reached") from error
+        return _read_parsed(response, code)
+
+    def released_versions(self, table_id: UUID) -> list[Mapping[str, Any]]:
+        operation = self._operations["list_table_versions"]
+        parsed = self._read(
+            "DEPLOY_DATASET_VERSION_READ_FAILED",
+            operation.sync_detailed,
+            client=self._raw_client,
+            table_id=table_id,
+        )
+        if not isinstance(parsed, list):
+            raise _refuse(
+                "DEPLOY_DATASET_VERSION_READ_FAILED",
+                "the released Build list did not come back as a list",
+            )
+        # Bounded here as well as in the validator every reader passes through: normalizing a
+        # malformed answer of a million entries is work this never has to do.
+        if len(parsed) > MAX_RELEASED_VERSIONS:
+            raise _refuse(
+                "DEPLOY_DATASET_VERSION_INVALID",
+                "the released Build list is longer than this handoff will read",
+            )
+        return [_wire(item, "DEPLOY_DATASET_VERSION_READ_FAILED") for item in parsed]
+
+    def artifact(self, artifact_id: UUID) -> Mapping[str, Any]:
+        operation = self._operations["get_artifact"]
+        parsed = self._read(
+            "DEPLOY_DATASET_ARTIFACT_READ_FAILED",
+            operation.sync_detailed,
+            client=self._raw_client,
+            artifact_id=artifact_id,
+        )
+        return _wire(parsed, "DEPLOY_DATASET_ARTIFACT_READ_FAILED")
+
+    def download_session(self, artifact_id: UUID) -> Mapping[str, Any]:
+        operation = self._operations["create_artifact_download_session"]
+        parsed = self._read(
+            "DEPLOY_DATASET_SESSION_READ_FAILED",
+            operation.sync_detailed,
+            client=self._raw_client,
+            artifact_id=artifact_id,
+            idempotency_key=f"download:{artifact_id}:{secrets.token_hex(16)}",
+        )
+        return _wire(parsed, "DEPLOY_DATASET_SESSION_READ_FAILED")
+
+    def close(self) -> None:
+        client = getattr(self._raw_client, "_client", None)
+        if client is not None:
+            client.close()
+
+
+def _read_parsed(response: Any, code: str) -> Any:
+    status = int(getattr(response, "status_code", 0))
+    parsed = getattr(response, "parsed", None)
+    if status not in {200, 201} or parsed is None:
+        raise _refuse(code, f"the Mostly Right cloud answered with HTTP {status}")
+    return parsed
+
+
+def _wire(model: Any, code: str) -> Mapping[str, Any]:
+    try:
+        return studio_wire_dict(model)
+    except StudioBoundaryError as error:
+        raise HostedDeployError(code, "the answer is not a valid Studio object") from error
+
+
+# ------------------------------------------------------------------------------------------------
+# Pure validation: the release, the sealed record, and the signed session
+# ------------------------------------------------------------------------------------------------
+
+
+def _uuid(value: Any, code: str, label: str) -> UUID:
+    if not isinstance(value, str):
+        raise _refuse(code, f"{label} is missing")
+    try:
+        return UUID(value)
+    except ValueError as error:
+        raise _refuse(code, f"{label} is invalid") from error
+
+
+def _timestamp(value: Any, code: str, label: str) -> datetime:
+    if not isinstance(value, str) or not value.endswith("Z"):
+        raise _refuse(code, f"{label} is invalid")
+    try:
+        parsed = datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
+    except ValueError as error:
+        raise _refuse(code, f"{label} is invalid") from error
+    return parsed.astimezone(UTC)
+
+
+def select_released_build(
+    versions: Sequence[Mapping[str, Any]],
+    *,
+    dataset_id: UUID,
+    table_id: UUID,
+    workspace_id: UUID,
+    hosted_run_id: UUID,
+) -> ReleasedBuild:
+    """Return the one released version this run produced, or refuse.
+
+    Selection is by run, not by recency. "The newest version of this Dataset" is a different
+    question from "what the run I deployed released", and answering the first when asked the second
+    is how a handoff quietly lands somebody else's refresh. A run that has not released anything
+    yet has no version here at all, which is why finishing the hosted work is not by itself enough
+    to unlock any bytes.
+    """
+
+    if len(versions) > MAX_RELEASED_VERSIONS:
+        # The bound belongs here rather than at the transport, because every reader answers this
+        # question and only one of them is the generated client.
+        raise _refuse(
+            "DEPLOY_DATASET_VERSION_INVALID",
+            "the released Build list is longer than this handoff will read",
+        )
+    matches = [
+        version
+        for version in versions
+        if isinstance(version, Mapping) and version.get("run_id") == str(hosted_run_id)
+    ]
+    if not matches:
+        raise _refuse(
+            "DEPLOY_DATASET_NOT_RELEASED",
+            "this run has not released a Build yet, so there is nothing to bring back",
+        )
+    if len(matches) > 1:
+        raise _refuse(
+            "DEPLOY_DATASET_VERSION_INVALID",
+            "this run reports more than one released Build",
+        )
+    return _validate_released_version(
+        matches[0],
+        dataset_id=dataset_id,
+        table_id=table_id,
+        workspace_id=workspace_id,
+        hosted_run_id=hosted_run_id,
+    )
+
+
+def _validate_released_version(
+    version: Mapping[str, Any],
+    *,
+    dataset_id: UUID,
+    table_id: UUID,
+    workspace_id: UUID,
+    hosted_run_id: UUID,
+) -> ReleasedBuild:
+    if not isinstance(version, Mapping):
+        raise _refuse(
+            "DEPLOY_DATASET_VERSION_INVALID", "the released Build record is not an object"
+        )
+    gate = version.get("release_gate")
+    references = version.get("artifact_references")
+    version_number = version.get("version_number")
+    digest = version.get("candidate_digest")
+    if (
+        version.get("schema_version") != STUDIO_SCHEMA_VERSION
+        or version.get("workspace_id") != str(workspace_id)
+        or version.get("dataset_id") != str(dataset_id)
+        or version.get("table_id") != str(table_id)
+        or version.get("run_id") != str(hosted_run_id)
+        or version.get("release_authority") != "studio_transactional_release_controller"
+        or version.get("candidate_contract_version") != CANDIDATE_CONTRACT_VERSION
+        or not isinstance(digest, str)
+        or _SHA256.fullmatch(digest) is None
+        or type(version_number) is not int
+        or version_number < 1
+        or not isinstance(references, list)
+        or not references
+        or len(references) > MAX_ARTIFACT_REFERENCES
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_VERSION_INVALID",
+            "the released Build record is not the exact shape this handoff accepts",
+        )
+    if not isinstance(gate, Mapping) or gate.get("verification_decision") != "passed":
+        raise _refuse(
+            "DEPLOY_DATASET_NOT_RELEASED",
+            "this Build has not passed its independent check, so its rows stay unavailable",
+        )
+    if (
+        gate.get("open_blocker_count") != 0
+        or gate.get("open_critical_count") != 0
+        or gate.get("open_high_count") != 0
+        or gate.get("deterministic_checks_passed") is not True
+        or gate.get("committed_source_states_verified") is not True
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_NOT_RELEASED",
+            "this Build still has open findings, so its rows stay unavailable",
+        )
+    seen: set[UUID] = set()
+    collected: list[tuple[UUID, str]] = []
+    for reference in references:
+        if not isinstance(reference, Mapping):
+            raise _refuse(
+                "DEPLOY_DATASET_VERSION_INVALID", "an artifact reference is not an object"
+            )
+        artifact_id = _uuid(
+            reference.get("artifact_id"), "DEPLOY_DATASET_VERSION_INVALID", "an artifact reference"
+        )
+        content_digest = reference.get("content_digest")
+        if (
+            reference.get("workspace_id") != str(workspace_id)
+            or reference.get("contract_version") != STUDIO_SCHEMA_VERSION
+            or not isinstance(content_digest, str)
+            or _SHA256.fullmatch(content_digest) is None
+            or artifact_id in seen
+        ):
+            raise _refuse(
+                "DEPLOY_DATASET_VERSION_INVALID",
+                "an artifact reference is not the exact shape this handoff accepts",
+            )
+        seen.add(artifact_id)
+        collected.append((artifact_id, content_digest))
+    return ReleasedBuild(
+        dataset_id=dataset_id,
+        table_id=table_id,
+        table_version_id=_uuid(
+            version.get("table_version_id"),
+            "DEPLOY_DATASET_VERSION_INVALID",
+            "the released Build id",
+        ),
+        workspace_id=workspace_id,
+        run_id=hosted_run_id,
+        version_number=version_number,
+        candidate_digest=digest,
+        artifact_references=tuple(collected),
+    )
+
+
+def validate_sealed_artifact(
+    metadata: Mapping[str, Any],
+    *,
+    released: ReleasedBuild,
+    artifact_id: UUID,
+    reference_digest: str,
+) -> SealedArtifact:
+    """Accept one sealed artifact record only where it agrees with the release that named it."""
+
+    if not isinstance(metadata, Mapping):
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID", "the sealed evidence record is not an object"
+        )
+    size = metadata.get("size_bytes")
+    digest = metadata.get("content_digest")
+    kind = metadata.get("kind")
+    if (
+        metadata.get("schema_version") != STUDIO_SCHEMA_VERSION
+        or metadata.get("contract_version") != STUDIO_SCHEMA_VERSION
+        or metadata.get("artifact_id") != str(artifact_id)
+        or metadata.get("workspace_id") != str(released.workspace_id)
+        or metadata.get("run_id") != str(released.run_id)
+        or not isinstance(kind, str)
+        or not isinstance(digest, str)
+        or _SHA256.fullmatch(digest) is None
+        or type(size) is not int
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID",
+            "the sealed evidence record is not the exact shape this handoff accepts",
+        )
+    # The reference the release itself carries is the authority; a record that disagrees with it
+    # describes some other bytes, whatever it says about itself.
+    if digest != reference_digest:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID",
+            "the sealed evidence fingerprint differs from the one the released Build names",
+        )
+    if metadata.get("storage_state") not in {"sealed", "verified"}:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID",
+            "the sealed evidence is not in a settled, readable state",
+        )
+    limit = HOSTED_ARTIFACT_BYTE_LIMITS.get(kind)
+    if limit is None:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID",
+            "the released Build names evidence of a kind this handoff cannot read",
+        )
+    if not 1 <= size <= limit:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_INVALID",
+            "the sealed evidence size is outside its budget for this kind",
+        )
+    return SealedArtifact(
+        artifact_id=artifact_id,
+        workspace_id=released.workspace_id,
+        run_id=released.run_id,
+        kind=kind,
+        media_type=str(metadata.get("media_type", "")),
+        content_digest=digest,
+        size_bytes=size,
+    )
+
+
+def validate_download_session(
+    session: Mapping[str, Any],
+    *,
+    artifact: SealedArtifact,
+    studio_base_url: str,
+    now: datetime,
+) -> tuple[ValidatedResultDownload, dict[str, str]]:
+    """Accept one signed download session as a route to already-known bytes, and nothing more.
+
+    Every fact the transfer will later be judged against -- the size, the fingerprint, the media
+    type -- is taken from the sealed record and merely required to match here. A session is
+    therefore never the reason a byte is believed; it is only the reason a byte is reachable.
+    """
+
+    if not isinstance(session, Mapping):
+        raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "the signed transfer is not an object")
+    issued = _timestamp(
+        session.get("issued_at"), "DEPLOY_DATASET_SESSION_INVALID", "the signed transfer start time"
+    )
+    expires = _timestamp(
+        session.get("expires_at"), "DEPLOY_DATASET_SESSION_INVALID", "the signed transfer expiry"
+    )
+    moment = now.astimezone(UTC)
+    if (
+        session.get("schema_version") != STUDIO_SCHEMA_VERSION
+        or session.get("contract_version") != STUDIO_SCHEMA_VERSION
+        or session.get("artifact_id") != str(artifact.artifact_id)
+        or session.get("workspace_id") != str(artifact.workspace_id)
+        or session.get("run_id") != str(artifact.run_id)
+        or session.get("kind") != artifact.kind
+        or session.get("purpose") != REQUIRED_ARTIFACT_PURPOSE
+        or session.get("media_type") != artifact.media_type
+        or session.get("direction") != "download"
+        or session.get("method") != "GET"
+        or session.get("route_authority") != "public_editor"
+        or session.get("expected_content_digest") != artifact.content_digest
+        or session.get("expected_size_bytes") != artifact.size_bytes
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer does not describe the evidence it was asked for",
+        )
+    if issued >= expires or moment >= expires or expires - issued > MAX_SESSION_LIFETIME:
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer has expired or lasts longer than is allowed",
+        )
+    if issued > moment + timedelta(minutes=1):
+        raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "the signed transfer starts in the future")
+    headers = _session_headers(session.get("required_headers"), media_type=artifact.media_type)
+    url = _validate_transfer_url(session.get("signed_url"), studio_base_url=studio_base_url)
+    return (
+        ValidatedResultDownload(
+            url=url,
+            size=artifact.size_bytes,
+            media_type=artifact.media_type,
+            integrity={"kind": "local_sha256", "value": artifact.content_digest},
+        ),
+        headers,
+    )
+
+
+def _session_headers(required: Any, *, media_type: str) -> dict[str, str]:
+    if not isinstance(required, list) or len(required) > MAX_SESSION_HEADERS:
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer headers are absent or unreasonably many",
+        )
+    headers: dict[str, str] = {}
+    for item in required:
+        if not isinstance(item, Mapping):
+            raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "a signed transfer header is invalid")
+        name = item.get("name")
+        value = item.get("value")
+        if (
+            not isinstance(name, str)
+            or not isinstance(value, str)
+            or _HEADER_NAME.fullmatch(name) is None
+            or name.lower() in _FORBIDDEN_HEADERS
+            or name.lower() in headers
+            or len(value) > 4096
+            or "\r" in value
+            or "\n" in value
+        ):
+            raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "a signed transfer header is unsafe")
+        headers[name.lower()] = value
+    if headers.get("accept", media_type) != media_type:
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID", "the signed transfer asks for a different media type"
+        )
+    headers["accept"] = media_type
+    return headers
+
+
+def _validate_transfer_url(signed_url: Any, *, studio_base_url: str) -> str:
+    """Admit the two places sealed bytes are actually served from, and no third one.
+
+    This is deliberately not the allowlist ``acquisition/result_download`` uses. That one pins the
+    public-crawl result prefix, which sealed Build evidence is never stored under; reusing it would
+    have meant either refusing every real artifact or widening a rule that guards a different
+    boundary. So the authority here is its own: the Studio origin the credential was issued for, or
+    the committed object prefix of the Studio artifact store.
+    """
+
+    if not isinstance(signed_url, str) or not 1 <= len(signed_url) <= MAX_SIGNED_URL_CHARS:
+        raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "the signed transfer address is invalid")
+    parsed = urlsplit(signed_url)
+    base = urlsplit(studio_base_url)
+    try:
+        port = parsed.port
+    except ValueError as error:
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID", "the signed transfer address is invalid"
+        ) from error
+    if (
+        parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+        or "%" in parsed.path
+        or "\\" in parsed.path
+    ):
+        raise _refuse("DEPLOY_DATASET_SESSION_INVALID", "the signed transfer address is invalid")
+    if parsed.hostname == GCS_TRANSFER_HOST:
+        _validate_object_store_url(parsed)
+        return signed_url
+    if (
+        parsed.scheme != base.scheme
+        or parsed.hostname != base.hostname
+        or port != base.port
+        or not parsed.hostname
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer address is somewhere this command will not go",
+        )
+    segments = parsed.path.split("/")
+    if (
+        not parsed.path.startswith("/")
+        or len(segments) > 8
+        or any(segment in {"", ".", ".."} for segment in segments[1:])
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer address is somewhere this command will not go",
+        )
+    return signed_url
+
+
+def _validate_object_store_url(parsed: Any) -> None:
+    segments = parsed.path.split("/")
+    if (
+        parsed.scheme != "https"
+        or parsed.port is not None
+        or len(segments) != 5
+        or _BUCKET.fullmatch(segments[1]) is None
+        or tuple(segments[2:4]) != GCS_COMMITTED_PREFIX
+        or _OBJECT_NAME.fullmatch(segments[4]) is None
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer address is outside the sealed store",
+        )
+    try:
+        query = parse_qsl(parsed.query, keep_blank_values=True, strict_parsing=True)
+    except ValueError as error:
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID", "the signed transfer address is invalid"
+        ) from error
+    names = {key for key, _value in query}
+    required = {
+        "X-Goog-Algorithm",
+        "X-Goog-Credential",
+        "X-Goog-Date",
+        "X-Goog-Expires",
+        "X-Goog-SignedHeaders",
+        "X-Goog-Signature",
+    }
+    values = dict(query)
+    if (
+        len(query) != len(names)
+        or not required <= names
+        or not names <= required | {"generation"}
+        or any(not value for value in values.values())
+        or values["X-Goog-Algorithm"] != "GOOG4-RSA-SHA256"
+        or not values["X-Goog-Expires"].isdigit()
+        or not 1 <= int(values["X-Goog-Expires"]) <= 3600
+        or re.fullmatch(r"[0-9]{8}T[0-9]{6}Z", values["X-Goog-Date"]) is None
+        or re.fullmatch(r"(?:[0-9A-Fa-f]{2}){64,512}", values["X-Goog-Signature"]) is None
+        or re.fullmatch(
+            r"[^/\x00-\x20]{1,320}/[0-9]{8}/auto/storage/goog4_request",
+            values["X-Goog-Credential"],
+        )
+        is None
+        or values["X-Goog-Credential"].split("/", 2)[1] != values["X-Goog-Date"][:8]
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_SESSION_INVALID",
+            "the signed transfer address is not signed the way the store signs",
+        )
+
+
+# ------------------------------------------------------------------------------------------------
+# The transfer
+# ------------------------------------------------------------------------------------------------
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+def download_sealed_artifact(
+    download: ValidatedResultDownload,
+    headers: Mapping[str, str],
+) -> bytes:
+    """Transfer one sealed artifact in bounded units, verifying as it goes.
+
+    The transfer is chunked into a spool while :class:`ResultBytesVerifier` folds each unit into
+    the length and the sealed fingerprint, so the process never has to be able to hold a transfer
+    it is going to refuse, and an accepted one materializes once, at the end, from bytes already
+    verified. Status and media type are read from the head and refused before the body moves, so a
+    wrong answer costs no body bytes at all.
+    """
+
+    opener = build_opener(
+        ProxyHandler({}), HTTPSHandler(context=ssl.create_default_context()), _NoRedirect()
+    )
+    request = Request(download.url, method="GET", headers=dict(headers))
+    try:
+        response = opener.open(request, timeout=REQUEST_TIMEOUT_SECONDS)
+    except HTTPError as error:
+        response = error
+    except Exception as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_DOWNLOAD_FAILED", "the released Build could not be transferred"
+        ) from error
+    # The response is the outermost context deliberately: nothing constructed after the open --
+    # not the verifier, not the spool -- can strand the socket by raising before a `with` that
+    # would have closed it.
+    with response:
+        media_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        status = int(response.status)
+        if status != 200 or media_type != download.media_type:
+            raise _refuse("DEPLOY_DATASET_DOWNLOAD_INVALID", _DOWNLOAD_INVALID_DETAIL)
+        verifier = ResultBytesVerifier(download)
+        with tempfile.SpooledTemporaryFile(max_size=DOWNLOAD_SPOOL_BYTES, mode="w+b") as spool:
+            remaining = download.size + 1
+            while remaining > 0:
+                try:
+                    chunk = response.read(min(RESULT_CHUNK_BYTES, remaining))
+                except Exception as error:
+                    raise HostedDeployError(
+                        "DEPLOY_DATASET_DOWNLOAD_FAILED",
+                        "the released Build could not be transferred",
+                    ) from error
+                if not chunk:
+                    break
+                try:
+                    spool.write(chunk)
+                except OSError as error:
+                    raise HostedDeployError(
+                        "DEPLOY_DATASET_DOWNLOAD_FAILED",
+                        "the released Build could not be staged for checking",
+                    ) from error
+                remaining -= len(chunk)
+                verifier.update(chunk)
+            if verifier.length != download.size:
+                raise _refuse("DEPLOY_DATASET_DOWNLOAD_INVALID", _DOWNLOAD_INVALID_DETAIL)
+            try:
+                verifier.verify()
+            except ResultDownloadError as error:
+                raise HostedDeployError(
+                    "DEPLOY_DATASET_DOWNLOAD_INTEGRITY",
+                    "the transferred bytes do not match the fingerprint the release sealed",
+                ) from error
+            spool.seek(0)
+            return spool.read()
+
+
+# ------------------------------------------------------------------------------------------------
+# Local installation
+# ------------------------------------------------------------------------------------------------
+
+
+def _require_run_directory(run_dir: Path) -> Path:
+    """Settle the destination folder without making it.
+
+    The folder a released Build lands in usually does not exist yet, because the Build that
+    produced it was not made here and nothing has had a reason to make the folder. So an absent
+    name whose parent is a real folder is accepted -- and it stays absent until there is a verified
+    Build to put in it, which is the whole reason this does not make it.
+
+    Making it here instead was a real defect: the ordinary refusal on this path is "the run has not
+    released anything yet", the remediation for it says to run the command again later, and an
+    empty folder left behind by that refusal is one ``mr-data view --run-dir`` will not open. The
+    command would have broken the automatic reveal it exists to provide, for anyone who checked
+    once before opening a window.
+    """
+
+    lexical = Path(os.path.abspath(os.fspath(run_dir)))
+    try:
+        info = os.stat(lexical, follow_symlinks=False)
+    except FileNotFoundError:
+        _require_real_directory(
+            lexical.parent, f"the folder to write into is not inside a real folder: {lexical}"
+        )
+        return lexical
+    except OSError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_TARGET_INVALID",
+            f"the folder to write into could not be read: {lexical}",
+        ) from error
+    if not stat.S_ISDIR(info.st_mode):
+        raise _refuse(
+            "DEPLOY_DATASET_TARGET_INVALID",
+            f"the destination is already something other than a folder: {lexical}",
+        )
+    _require_real_directory(lexical, f"the folder to write into must be one real folder: {lexical}")
+    return lexical
+
+
+def _require_real_directory(path: Path, detail: str) -> None:
+    try:
+        resolved = path.resolve(strict=True)
+        info = os.stat(path, follow_symlinks=False)
+    except OSError as error:
+        raise HostedDeployError("DEPLOY_DATASET_TARGET_INVALID", detail) from error
+    if resolved != path or not stat.S_ISDIR(info.st_mode):
+        raise _refuse("DEPLOY_DATASET_TARGET_INVALID", detail)
+
+
+@contextmanager
+def _staging_directory(run_dir: Path) -> Iterator[Path]:
+    """Build the tree beside its destination, so the destination only ever appears finished.
+
+    Beside rather than inside, because the destination may not exist yet and must not be made
+    before there is something verified to put in it. The parent is where the destination itself
+    will be created, so it is the same filesystem and the move stays one rename.
+    """
+
+    staging = run_dir.parent / f".hosted-build.{secrets.token_hex(8)}"
+    try:
+        staging.mkdir(mode=0o700)
+    except OSError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_INSTALL_FAILED",
+            f"a folder to build the released Build in could not be made beside {run_dir}",
+        ) from error
+    try:
+        yield staging
+    finally:
+        _remove_staging(staging)
+
+
+def _remove_staging(staging: Path) -> None:
+    """Discard an abandoned staging tree, including the read-only one a sealed Build is.
+
+    The tree is made writable from the top down before anything is removed from the bottom up.
+    Both directions are load-bearing: a sealed Build's directories are read-only by the time it is
+    assembled, and removing a file needs write permission on the directory holding it, not on the
+    file. Deleting deepest-first alone therefore stopped at the first sealed directory and left the
+    whole staging tree behind for every later run to find.
+
+    Failure here is not raised. This runs on the way out of a handoff that has already decided its
+    answer, and a leftover folder is not a reason to replace that answer with a different one.
+    """
+
+    if not staging.exists():
+        return
+    entries = sorted(staging.rglob("*"), key=lambda entry: len(entry.parts))
+    for item in entries:
+        if item.is_dir() and not item.is_symlink():
+            try:
+                item.chmod(0o700)
+            except OSError:
+                return
+    for item in reversed(entries):
+        try:
+            if item.is_dir() and not item.is_symlink():
+                item.rmdir()
+            else:
+                item.unlink()
+        except OSError:
+            return
+    try:
+        staging.rmdir()
+    except OSError:
+        return
+
+
+def install_released_build(
+    run_dir: Path, members: Mapping[str, bytes], *, candidate_digest: str
+) -> None:
+    """Install the whole sealed tree, or none of it.
+
+    Every member is written into a staging folder first, verified there, and only then moved into
+    place in one rename, so an interrupted handoff leaves a discarded staging folder rather than a
+    half-populated Build for the next run -- or the viewer -- to find and reason about. The
+    destination folder itself is made in the same breath as the move, so a refusal on the way here
+    leaves no empty folder behind either.
+    """
+
+    with _staging_directory(run_dir) as staging:
+        try:
+            _restore_candidate_members(members, staging)
+        except OSError as error:
+            raise HostedDeployError(
+                "DEPLOY_DATASET_INSTALL_FAILED", "the released Build could not be written here"
+            ) from error
+        # Verified where it is discarded rather than where it is kept. A tree that cannot pass
+        # the checks a Build made on this machine passes never moves into place at all, so the
+        # destination never holds an unverifiable Build for a later run to refuse as somebody
+        # else's -- and the refusal below can say, truthfully, that nothing was written.
+        _verify_installed_build(staging, candidate_digest)
+        made = _make_destination(run_dir)
+        source = staging / "candidate"
+        try:
+            # Moving a folder needs write permission on the folder being moved, because its own
+            # link to its parent changes. The sealed tree is read-only by the time it is built, so
+            # that permission is restored for the move and taken away again immediately. Both
+            # states are unreachable to anything watching this run: before the move the tree is
+            # inside a private staging folder, and after it there is still no notebook beside it,
+            # which is what any reader has to see first. A process that dies inside that window
+            # leaves the right Build under a mode verification will not accept, which is what
+            # `_reseal_interrupted_install` exists to converge on.
+            os.chmod(source, 0o700)
+            os.rename(source, run_dir / "candidate")
+        except OSError as error:
+            # A folder this call made and could not fill is one the viewer will not open, so it
+            # goes back down. And a full disk is not somebody else's Build being in the way: the
+            # two are told apart by what the system said rather than by which line raised.
+            if made:
+                with suppress(OSError):
+                    run_dir.rmdir()
+            if error.errno in {errno.EEXIST, errno.ENOTEMPTY}:
+                raise HostedDeployError(
+                    "DEPLOY_DATASET_TARGET_OCCUPIED",
+                    f"something is already in the way at {run_dir / 'candidate'}",
+                ) from error
+            raise HostedDeployError(
+                "DEPLOY_DATASET_INSTALL_FAILED",
+                f"the released Build could not be put in place at {run_dir}",
+            ) from error
+        try:
+            _seal_installed_build(run_dir)
+            _ensure_table_sidecar_lock(run_dir)
+        except OSError as error:
+            raise HostedDeployError(
+                "DEPLOY_DATASET_INSTALL_FAILED", "the released Build could not be settled here"
+            ) from error
+
+
+def _make_destination(run_dir: Path) -> bool:
+    """Make the destination folder, now that there is a verified Build to put in it.
+
+    Returns whether this call made it, so a move that then fails can take it back down again.
+
+    A folder that appeared between the check at the start of the handoff and this moment is
+    re-checked rather than assumed: the validation up front pins nothing, so a writer in the parent
+    could have planted a link where the folder was going, and the rename that follows would resolve
+    through it.
+    """
+
+    try:
+        run_dir.mkdir(mode=0o700)
+    except FileExistsError:
+        _require_real_directory(
+            run_dir, f"the folder to write into is not one real folder: {run_dir}"
+        )
+        return False
+    except OSError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_TARGET_INVALID",
+            f"the folder to write into could not be made: {run_dir}",
+        ) from error
+    return True
+
+
+def _seal_installed_build(run_dir: Path) -> None:
+    """Give the installed tree its sealed mode and make the move survive a power loss."""
+
+    os.chmod(run_dir / "candidate", 0o555)
+    _fsync_directory(run_dir)
+
+
+def _fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _reseal_interrupted_install(run_dir: Path, candidate_digest: str) -> None:
+    """Finish the sealing step of an install this or an earlier run left half done.
+
+    An install that died between the move and the sealing chmod leaves the exact released Build in
+    place under an owner-writable mode, and verification requires the sealed one -- so the rerun
+    that is supposed to converge would instead read an unverifiable tree and refuse it as somebody
+    else's Build.
+
+    Only that one state is repaired, and it is identified by what the tree says it is rather than
+    by its mode alone: an owner-writable ``candidate`` whose own record names this exact released
+    Build. Nothing is followed on the way -- the folder and its record are opened without following
+    links and the mode is set through the open folder, so a name swapped underneath this cannot
+    redirect it. And repairing it decides nothing: the mode is tightened rather than loosened, and
+    ordinary verification still has to recognise the tree afterwards or the handoff refuses exactly
+    as it did before.
+    """
+
+    directory = -1
+    try:
+        directory = os.open(run_dir / "candidate", os.O_RDONLY | os.O_DIRECTORY | _NO_FOLLOW)
+        info = os.fstat(directory)
+        if stat.S_IMODE(info.st_mode) != 0o700:
+            return
+        if _recorded_candidate_digest(directory) != candidate_digest:
+            return
+        os.fchmod(directory, 0o555)
+    except OSError:
+        return
+    finally:
+        if directory >= 0:
+            os.close(directory)
+    _fsync_directory(run_dir)
+
+
+def _recorded_candidate_digest(directory: int) -> str | None:
+    """Read the fingerprint one unsealed tree records for itself, or nothing."""
+
+    descriptor = os.open("manifest.json", os.O_RDONLY | _NO_FOLLOW, dir_fd=directory)
+    try:
+        info = os.fstat(descriptor)
+        if (
+            not stat.S_ISREG(info.st_mode)
+            or info.st_nlink != 1
+            or info.st_size > MAX_MANIFEST_BYTES
+        ):
+            return None
+        raw = os.read(descriptor, MAX_MANIFEST_BYTES)
+    finally:
+        os.close(descriptor)
+    try:
+        value = canonical.parse_json(raw)
+    except canonical.CanonicalJSONError:
+        return None
+    recorded = value.get("candidate_digest") if isinstance(value, dict) else None
+    return f"sha256:{recorded}" if isinstance(recorded, str) else None
+
+
+def _installed_build_digest(run_dir: Path) -> str | None:
+    """Return the fingerprint of an already-installed Build here, or ``None`` when there is none.
+
+    An unreadable installed tree answers with the empty string rather than ``None``: something is
+    in the way, it is not the released Build, and saying "nothing is here" about it would let the
+    install path try to move a Build on top of it.
+    """
+
+    from mostlyright.data_harness import pipeline
+
+    if not (run_dir / "candidate").exists():
+        return None
+    try:
+        with pipeline.open_verified_snapshot(run_dir) as snapshot:
+            return "sha256:" + snapshot.verified.candidate_digest
+    except Exception:
+        return ""
+
+
+# ------------------------------------------------------------------------------------------------
+# The handoff
+# ------------------------------------------------------------------------------------------------
+
+
+def materialize_hosted_dataset(
+    run_dir: Path,
+    *,
+    dataset_id: UUID,
+    table_id: UUID,
+    hosted_run_id: UUID,
+    token: StudioToken,
+    reader_factory: Callable[[StudioToken], StudioDatasetReader] | None = None,
+    downloader: Callable[[ValidatedResultDownload, Mapping[str, str]], bytes] | None = None,
+    visual_store: VisualRunStore | None = None,
+    now: Callable[[], datetime] = lambda: datetime.now(UTC),
+) -> HostedDatasetHandoff:
+    """Bring one released hosted Build here and derive its table notebook from it.
+
+    The order is the contract. Nothing on this machine is written before the transferred bytes have
+    matched the fingerprint the release sealed and decoded into the exact Build the release names;
+    nothing is derived from the installed tree before ordinary local verification has re-derived
+    that same fingerprint from it; and the notebook is written by the existing atomic installer, so
+    the viewer never observes a partial one. A rerun after any interruption converges: an already
+    installed Build with the released fingerprint is kept and its notebook simply re-derived.
+
+    ``visual_store`` is the open workbench's own run log. Narrating into it is what turns a written
+    file into a revealed Table tab, and it is deliberately the last thing that happens: the
+    viewer will not show the tab on the narration alone, because it re-derives the notebook from
+    its own verified snapshot and compares bytes first, so narrating earlier would only mean
+    announcing something that is not there yet.
+    """
+
+    target = _require_run_directory(run_dir)
+    if token.workspace_id is None:
+        raise _refuse("DEPLOY_TOKEN_EXCHANGE_FAILED", "the sign-in has no workspace")
+    # The two boundaries are resolved here rather than bound as default arguments, so substituting
+    # either one is a matter of naming it on this module, exactly as it is for every other seam in
+    # this tree. A default bound at definition time is one nothing can reach afterwards.
+    reader = (reader_factory or GeneratedStudioDatasetReader)(token)
+    transfer = downloader or download_sealed_artifact
+    try:
+        released = select_released_build(
+            reader.released_versions(table_id),
+            dataset_id=dataset_id,
+            table_id=table_id,
+            workspace_id=token.workspace_id,
+            hosted_run_id=hosted_run_id,
+        )
+        _require_narratable(visual_store, released.candidate_digest)
+        _reseal_interrupted_install(target, released.candidate_digest)
+        installed = _installed_build_digest(target)
+        transferred = installed != released.candidate_digest
+        artifact = _select_sealed_evidence(reader, released)
+        if transferred:
+            if installed is not None:
+                raise _refuse(
+                    "DEPLOY_DATASET_TARGET_OCCUPIED",
+                    f"{target} already holds a different Build; name an unused folder with --into",
+                )
+            session, headers = validate_download_session(
+                reader.download_session(artifact.artifact_id),
+                artifact=artifact,
+                studio_base_url=token.studio_base_url,
+                now=now(),
+            )
+            raw = transfer(session, headers)
+            members = _decode_released_build(raw, released.candidate_digest)
+            install_released_build(target, members, candidate_digest=released.candidate_digest)
+    finally:
+        # Closing a socket is not a verdict. Letting it raise here would replace whatever this
+        # handoff had already decided -- including a refusal a person is waiting to read.
+        try:
+            reader.close()
+        except Exception:
+            pass
+    candidate_digest = _verify_installed_build(target, released.candidate_digest)
+    _ensure_table_sidecar_lock(target)
+    notebook_path = _render_notebook(target, replace_existing=transferred)
+    handoff = HostedDatasetHandoff(
+        run_dir=target,
+        dataset_id=released.dataset_id,
+        table_id=released.table_id,
+        table_version_id=released.table_version_id,
+        version_number=released.version_number,
+        hosted_run_id=released.run_id,
+        candidate_digest=candidate_digest,
+        artifact_id=artifact.artifact_id,
+        artifact_content_digest=artifact.content_digest,
+        artifact_size_bytes=artifact.size_bytes,
+        notebook_path=notebook_path,
+        transferred=transferred,
+    )
+    _write_handoff_receipt(target, handoff)
+    _narrate_hosted_build(visual_store, handoff)
+    return handoff
+
+
+def _require_narratable(visual_store: VisualRunStore | None, candidate_digest: str) -> None:
+    """Refuse before anything is written when this workbench log belongs to another Build."""
+
+    if visual_store is None:
+        return
+    try:
+        state = reduce_events(visual_store.events())
+    except VisualRunError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_NARRATION_UNAVAILABLE",
+            "the open workbench record could not be read",
+        ) from error
+    if (
+        state.candidate_digest is not None
+        and "sha256:" + state.candidate_digest != candidate_digest
+    ):
+        raise _refuse(
+            "DEPLOY_DATASET_NARRATION_CONFLICT",
+            "this workbench is already showing a different Build; start a new one for this",
+        )
+    if state.terminal and state.lifecycle != "completed":
+        raise _refuse(
+            "DEPLOY_DATASET_NARRATION_CONFLICT",
+            "this workbench already ended without a dataset; start a new one for this",
+        )
+
+
+def _narrate_hosted_build(
+    visual_store: VisualRunStore | None, handoff: HostedDatasetHandoff
+) -> None:
+    """Tell the open workbench what landed, using the same records a local Build writes."""
+
+    if visual_store is None:
+        return
+    digest = handoff.candidate_digest
+    try:
+        content = _read_installed_notebook(handoff.notebook_path)
+        work = VisualWork(visual_store, actor="worker")
+        if not visual_store.events():
+            work.start_run(key=f"hosted-build:{digest[:16]}:started")
+        work.build_sealed(digest, key=f"hosted-build:{digest[:16]}:sealed")
+        work.build_verified(digest, key=f"hosted-build:{digest[:16]}:verified")
+        work.notebook_materialized("table", content, key=f"hosted-build:{digest[:16]}:notebook")
+        if reduce_events(visual_store.events()).lifecycle != "completed":
+            work.complete_run(key=f"hosted-build:{digest[:16]}:completed")
+    except (OSError, ValueError) as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_NARRATION_UNAVAILABLE",
+            "the dataset is here, but the open workbench could not be told about it",
+        ) from error
+
+
+def _select_sealed_evidence(reader: StudioDatasetReader, released: ReleasedBuild) -> SealedArtifact:
+    """Read every artifact the release names and keep the one kind this handoff redeems."""
+
+    selected: SealedArtifact | None = None
+    for artifact_id, reference_digest in released.artifact_references:
+        sealed = validate_sealed_artifact(
+            reader.artifact(artifact_id),
+            released=released,
+            artifact_id=artifact_id,
+            reference_digest=reference_digest,
+        )
+        if sealed.kind != REQUIRED_ARTIFACT_KIND:
+            continue
+        if sealed.media_type != REQUIRED_ARTIFACT_MEDIA_TYPE:
+            # The contract for a kind is part of what the kind means. Evidence that arrives under
+            # the wrong one is refused here rather than repaired later, so a Studio slot whose
+            # contract has drifted cannot be rendered as though it had not.
+            raise _refuse(
+                "DEPLOY_DATASET_ARTIFACT_CONTRACT_INVALID",
+                "the sealed evidence does not meet the contract for its kind",
+            )
+        if selected is not None:
+            raise _refuse(
+                "DEPLOY_DATASET_ARTIFACT_INVALID",
+                "the released Build names its sealed evidence more than once",
+            )
+        selected = sealed
+    if selected is None:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_ABSENT",
+            "the released Build does not name the sealed evidence this needs",
+        )
+    return selected
+
+
+def _decode_released_build(raw: bytes, candidate_digest: str) -> Mapping[str, bytes]:
+    if len(raw) > MAX_CANDIDATE_ENVELOPE_BYTES:
+        raise _refuse(
+            "DEPLOY_DATASET_ARTIFACT_CONTRACT_INVALID",
+            "the sealed evidence is larger than the contract for its kind allows",
+        )
+    try:
+        return _decode_candidate_envelope(raw, candidate_digest)
+    except HostedWorkerError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_ARTIFACT_CONTRACT_INVALID",
+            "the sealed evidence does not meet the contract for its kind",
+        ) from error
+
+
+def _verify_installed_build(run_dir: Path, candidate_digest: str) -> str:
+    """Re-derive the fingerprint here, from the installed tree, by ordinary local verification."""
+
+    from mostlyright.data_harness import pipeline
+
+    try:
+        verified = pipeline.verify_candidate(run_dir)
+    except Exception as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_LOCAL_CHECK_FAILED",
+            "the Build written here did not pass the same checks a local Build passes",
+        ) from error
+    if "sha256:" + verified.candidate_digest != candidate_digest:
+        raise _refuse(
+            "DEPLOY_DATASET_LOCAL_CHECK_FAILED",
+            "the Build written here is not the Build the release named",
+        )
+    return verified.candidate_digest
+
+
+def _ensure_table_sidecar_lock(run_dir: Path) -> None:
+    """Install the structural sidecar lock omitted from the sealed candidate envelope."""
+
+    directory = os.open(
+        run_dir,
+        os.O_RDONLY | os.O_DIRECTORY | _NO_FOLLOW | getattr(os, "O_CLOEXEC", 0),
+    )
+    lock = -1
+    try:
+        try:
+            lock = os.open(
+                pipeline.RUN_BUILD_ACTIVITY_LOCK,
+                os.O_RDWR | os.O_CREAT | os.O_EXCL | _NO_FOLLOW | getattr(os, "O_CLOEXEC", 0),
+                0o600,
+                dir_fd=directory,
+            )
+            os.fsync(lock)
+            os.fsync(directory)
+        except FileExistsError:
+            lock = os.open(
+                pipeline.RUN_BUILD_ACTIVITY_LOCK,
+                os.O_RDONLY | _NO_FOLLOW | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=directory,
+            )
+        metadata = os.fstat(lock)
+        named = os.stat(
+            pipeline.RUN_BUILD_ACTIVITY_LOCK,
+            dir_fd=directory,
+            follow_symlinks=False,
+        )
+        if (
+            not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+            or metadata.st_size != 0
+            or stat.S_IMODE(metadata.st_mode) != 0o600
+            or pipeline._entry_identity(metadata) != pipeline._entry_identity(named)
+        ):
+            raise OSError(errno.EPERM, "the Table sidecar lock is not one stable empty file")
+    except OSError as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_NOTEBOOK_FAILED",
+            "the Table notebook lock could not be established here",
+        ) from error
+    finally:
+        if lock >= 0:
+            os.close(lock)
+        os.close(directory)
+
+
+def _render_notebook(run_dir: Path, *, replace_existing: bool) -> Path:
+    """Ask the one generator for the notebook, replacing only what this run just installed.
+
+    A Build that has just landed has no notebook worth keeping, so its own is written. A rerun over
+    an already installed Build fills an absence and no more: the shipped skill tells an agent to
+    append executed chart cells to ``table.ipynb``, and this may be called unattended and
+    repeatedly by whatever is watching the hosted run, which is exactly the shape that would
+    silently discard them. It is the same line ``notebook.py`` draws between the command a person
+    ran and the viewer's own recovery.
+    """
+
+    from mostlyright.data_harness.notebook import (
+        TABLE_NOTEBOOK_NAME,
+        render_table_notebook,
+    )
+
+    try:
+        return render_table_notebook(run_dir, replace_existing=replace_existing)
+    except FileExistsError:
+        return run_dir / TABLE_NOTEBOOK_NAME
+    except Exception as error:
+        raise HostedDeployError(
+            "DEPLOY_DATASET_NOTEBOOK_FAILED", "the table notebook could not be written here"
+        ) from error
+
+
+def _read_installed_notebook(path: Path) -> bytes:
+    """Read the notebook about to be narrated without following a link or taking an unbounded file.
+
+    On a converging rerun this is a file this command did not write, so it is read the way every
+    other file here is read rather than the way a path is usually opened.
+    """
+
+    descriptor = os.open(path, os.O_RDONLY | _NO_FOLLOW)
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+            raise OSError(errno.EPERM, "the table notebook is not one ordinary file")
+        if info.st_size > MAX_NOTEBOOK_BYTES:
+            raise OSError(errno.EFBIG, "the table notebook is larger than this will read")
+        return os.read(descriptor, MAX_NOTEBOOK_BYTES)
+    finally:
+        os.close(descriptor)
+
+
+def _write_handoff_receipt(run_dir: Path, handoff: HostedDatasetHandoff) -> None:
+    """Record which released Build these local bytes came from, atomically and non-secretly.
+
+    This is the coordinate the viewer otherwise has no way to know: it observes content
+    fingerprints and local files, and nothing in it names a hosted run. The receipt states nothing
+    the viewer is allowed to admit anything on -- admission stays exactly what it was -- it only
+    lets what is already admitted be attributed to the run that produced it.
+    """
+
+    destination = run_dir / HANDOFF_RELATIVE_PATH
+    raw = canonical.canonical_json_bytes(handoff.to_dict())
+    temporary = destination.parent / f".handoff.{secrets.token_hex(8)}"
+    try:
+        destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NO_FOLLOW, 0o600)
+        try:
+            view = memoryview(raw)
+            while view:
+                view = view[os.write(descriptor, view) :]
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        os.replace(temporary, destination)
+    except OSError as error:
+        try:
+            temporary.unlink()
+        except OSError:
+            pass
+        raise HostedDeployError(
+            "DEPLOY_DATASET_RECEIPT_FAILED", "the record of this handoff could not be written"
+        ) from error
+
+
+__all__ = [
+    "GCS_COMMITTED_PREFIX",
+    "HANDOFF_RECEIPT_SCHEMA",
+    "HANDOFF_RELATIVE_PATH",
+    "REQUIRED_ARTIFACT_KIND",
+    "GeneratedStudioDatasetReader",
+    "HostedDatasetHandoff",
+    "ReleasedBuild",
+    "SealedArtifact",
+    "StudioDatasetReader",
+    "download_sealed_artifact",
+    "install_released_build",
+    "materialize_hosted_dataset",
+    "read_handoff_receipt",
+    "select_released_build",
+    "validate_download_session",
+    "validate_sealed_artifact",
+]