mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/hosted_deploy.py

@@ -0,0 +1,3037 @@
+"""Crash-safe deployment of one exact reviewed Build through Cloud and Studio."""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import importlib
+import ipaddress
+import os
+import re
+import ssl
+import stat
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, ProxyHandler, Request, build_opener
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+from croniter import CroniterBadCronError, CroniterBadDateError, croniter
+
+from mostlyright.data_harness import canonical, deployment_evidence, pipeline
+from mostlyright.data_harness.deploy import DeploymentRequest
+from mostlyright.data_harness.hosted_crawler_protocol import (
+    OPENLIGADB_EGRESS_POLICY_ATTESTATION,
+    PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+)
+from mostlyright.data_harness.studio_boundary import StudioBoundaryError, client_contract_identity
+from mostlyright.data_harness.ux.credentials import ResolvedCloudCredentials
+
+CLOUD_TOKEN_PATH = "/api/cli/studio-token"
+CLOUD_DATASET_BINDINGS_PATH = "/api/cli/table-bindings"
+CLOUD_TABLE_BINDING_SCHEMA_VERSION = "mostlyright-cloud-table-binding.v1"
+CLOUD_TABLE_BINDING_CONTRACT_SHA256 = (
+    "f408d3ce54994624778e74186077557228bfd89f95ab882a152efa1b5af111fd"
+)
+DEPLOYMENT_STATE_SCHEMA = "mostlyright-hosted-deployment-state.v3"
+DEPLOYMENT_RECEIPT_SCHEMA = "mostlyright-hosted-deployment-receipt.v3"
+STUDIO_SCHEMA_VERSION = "3.0.0"
+REQUEST_TIMEOUT_SECONDS = 30.0
+#: How many EXTRA attempts one transient Cloud 503 earns before this deployment
+#: refuses.
+#:
+#: ⚠ WHY THIS EXISTS AT ALL. Studio runs behind Cloud and scales to zero; a cold
+#: start takes ~20s to become servable. Cloud provisions this workspace's Studio
+#: tenancy on EVERY token exchange, so the request that WAKES Studio is the same
+#: request that has to wait for it. Before 2026-08-20 that request simply
+#: answered 503 and this function raised DEPLOY_STUDIO_UNAVAILABLE immediately --
+#: which meant `mr-data` could never deploy after any idle period, because every
+#: attempt woke Studio, gave up on it, and left it to scale back to zero. Eight
+#: such failures were recorded against production on 2026-08-20 alone.
+#:
+#: Two attempts is deliberate rather than generous: Cloud's own provisioning
+#: budget already clears the observed cold start, so a retry here is the second
+#: line, covering the case where Studio was not merely cold but genuinely
+#: restarting.
+TOKEN_EXCHANGE_RETRY_ATTEMPTS = 2
+#: Ceiling on any single retry wait, however large a `retry-after` Cloud sends.
+#: A deployment must stay a bounded, interruptible foreground operation.
+TOKEN_EXCHANGE_MAX_RETRY_SECONDS = 30.0
+MAX_TOKEN_RESPONSE_BYTES = 32 * 1024
+MAX_BINDING_RESPONSE_BYTES = 32 * 1024
+MAX_STATE_BYTES = 8 * 1024 * 1024
+STATE_RELATIVE_PATH = Path("evidence") / "deployment" / "state.json"
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_PREFIXED_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_IMMUTABLE_IMAGE = re.compile(r"^[a-z0-9][a-z0-9._/-]{0,254}@sha256:[0-9a-f]{64}$")
+_OBJECT_GENERATION = re.compile(r"^[1-9][0-9]{0,31}$")
+_CLI_KEY = re.compile(r"^mr_cli_[A-Za-z0-9_-]{64}$")
+
+
+class HostedDeployError(RuntimeError):
+    """A typed, credential-safe deployment refusal."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{code}: {detail}")
+
+
+@dataclass(frozen=True)
+class StudioToken:
+    studio_base_url: str
+    workspace_id: UUID
+    token: str
+    expires_at: datetime
+
+    def __repr__(self) -> str:
+        return (
+            "StudioToken("
+            f"studio_base_url={self.studio_base_url!r}, workspace_id={self.workspace_id!r}, "
+            f"token='<redacted>', expires_at={self.expires_at!r})"
+        )
+
+
+@dataclass(frozen=True)
+class StudioResponse:
+    status_code: int
+    body: Mapping[str, Any]
+    etag: str | None = None
+
+
+class TokenExchangeTransport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes, Mapping[str, str]]: ...
+
+
+class StudioDeploymentClient(Protocol):
+    def call(
+        self,
+        operation: str,
+        body: Mapping[str, Any] | None,
+        *,
+        idempotency_key: str | None = None,
+        resource_id: UUID | None = None,
+        if_match: str | None = None,
+    ) -> StudioResponse: ...
+
+    def preflight(self, body: Mapping[str, Any]) -> StudioResponse: ...
+
+    def read(self, operation: str, *, resource_id: UUID | None = None) -> StudioResponse: ...
+
+    def upload(self, session: Mapping[str, Any], content: bytes) -> str: ...
+
+    def close(self) -> None: ...
+
+
+class DeploymentStateStore(Protocol):
+    @property
+    def path(self) -> Path: ...
+
+    def exists(self) -> bool: ...
+
+    def load(self) -> dict[str, Any]: ...
+
+    def save(self, state: Mapping[str, Any]) -> None: ...
+
+    def close(self) -> None: ...
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        request: Request,
+        file_pointer: Any,
+        code: int,
+        message: str,
+        headers: Any,
+        new_url: str,
+    ) -> None:
+        return None
+
+
+class UrlLibTokenExchangeTransport:
+    """Bounded Cloud token exchange with ambient proxies and redirects disabled."""
+
+    def __init__(self) -> None:
+        self._opener = build_opener(
+            ProxyHandler({}), HTTPSHandler(context=ssl.create_default_context()), _NoRedirect()
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes, Mapping[str, str]]:
+        request = Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            response = self._opener.open(request, timeout=REQUEST_TIMEOUT_SECONDS)
+        except HTTPError as error:
+            response = error
+        with response:
+            raw = response.read(maximum + 1)
+            status = int(response.status)
+            response_headers = {key.lower(): value for key, value in response.headers.items()}
+        if len(raw) > maximum:
+            raise HostedDeployError(
+                "DEPLOY_TOKEN_EXCHANGE_FAILED", "the Cloud token response exceeds its byte limit"
+            )
+        return status, raw, response_headers
+
+
+def _transient_retry_seconds(response_headers: Mapping[str, str]) -> float | None:
+    """Seconds Cloud asked this deployment to wait, or ``None`` if it asked at all.
+
+    ⚠ THE ABSENCE OF THE HEADER IS THE SIGNAL, not a missing detail to paper
+    over. Cloud answers a 503 in exactly two shapes, and they mean opposite
+    things:
+
+    * ``serviceUnavailable()`` -- "our failure, not yours; please retry" --
+      stamps ``retry-after``. This is the cold-start case, and it is worth
+      retrying.
+    * ``studioUnconfigured()`` -- Studio is not configured on that deployment
+      at all -- stamps NO ``retry-after``. Retrying it would burn a bounded
+      deployment budget on a condition no amount of waiting can change.
+
+    Both bodies are deliberately generic (Cloud does not leak which of its
+    environment variables is at fault), so this header is the ONLY thing that
+    distinguishes them from out here. Returning ``None`` for a malformed or
+    out-of-range value fails toward the safe reading -- refuse now rather than
+    sleep on a number we do not trust.
+    """
+
+    raw = response_headers.get("retry-after", "")
+    if not raw.isdecimal():
+        return None
+    seconds = int(raw)
+    if not 1 <= seconds <= 3600:
+        return None
+    return float(min(seconds, TOKEN_EXCHANGE_MAX_RETRY_SECONDS))
+
+
+def exchange_studio_token(
+    credentials: ResolvedCloudCredentials,
+    *,
+    transport: TokenExchangeTransport | None = None,
+    now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    sleep: Callable[[float], None] = time.sleep,
+) -> StudioToken:
+    """Exchange the selected Cloud credential for a short-lived human Studio token."""
+
+    _require_cli_credential(credentials)
+    cloud_url = _service_url(credentials.cloud_url, "Cloud URL", allow_loopback_http=False)
+    selected = transport or UrlLibTokenExchangeTransport()
+    attempts_remaining = TOKEN_EXCHANGE_RETRY_ATTEMPTS
+    while True:
+        try:
+            status, raw, response_headers = selected.request(
+                "POST",
+                f"{cloud_url}{CLOUD_TOKEN_PATH}",
+                {"Accept": "application/json", "x-api-key": credentials.raw_key},
+                b"",
+                MAX_TOKEN_RESPONSE_BYTES,
+            )
+        except HostedDeployError:
+            raise
+        except Exception as error:
+            raise HostedDeployError(
+                "DEPLOY_TOKEN_EXCHANGE_FAILED", "the Cloud token exchange could not be reached"
+            ) from error
+        if status != 503 or attempts_remaining == 0:
+            break
+        delay = _transient_retry_seconds(response_headers)
+        if delay is None:
+            break
+        attempts_remaining -= 1
+        sleep(delay)
+    try:
+        parsed = canonical.parse_json(raw)
+    except canonical.CanonicalJSONError:
+        parsed = None
+    if status == 401:
+        raise HostedDeployError(
+            "DEPLOY_AUTHENTICATION_FAILED", "the selected Cloud credential was rejected"
+        )
+    if status == 402:
+        raise HostedDeployError(
+            "DEPLOY_SUBSCRIPTION_REQUIRED", "this workspace has no hosted deployment access"
+        )
+    if status == 429:
+        retry_after = response_headers.get("retry-after", "")
+        suffix = (
+            f" after {retry_after} seconds"
+            if retry_after.isdecimal() and 1 <= int(retry_after) <= 3600
+            else ""
+        )
+        raise HostedDeployError(
+            "DEPLOY_RATE_LIMITED", f"Cloud asked this deployment to retry{suffix}"
+        )
+    if status == 503:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_UNAVAILABLE",
+            "Studio is not configured, or stayed unavailable across every attempt",
+        )
+    if status != 200 or not isinstance(parsed, dict):
+        raise HostedDeployError(
+            "DEPLOY_TOKEN_EXCHANGE_FAILED", f"the Cloud token exchange failed (HTTP {status})"
+        )
+    base_url = _required_text(parsed, "studio_base_url")
+    workspace_id = _uuid(_required_text(parsed, "workspace_id"), "workspace_id")
+    token = _required_text(parsed, "token")
+    expires_at = _timestamp(_required_text(parsed, "expires_at"), "expires_at")
+    if expires_at <= now():
+        raise HostedDeployError(
+            "DEPLOY_TOKEN_EXCHANGE_FAILED", "the Cloud returned an expired Studio token"
+        )
+    return StudioToken(
+        studio_base_url=_service_url(base_url, "Studio base URL", allow_loopback_http=True),
+        workspace_id=workspace_id,
+        token=token,
+        expires_at=expires_at,
+    )
+
+
+_OPERATIONS: dict[str, tuple[str, str]] = {
+    "create_dataset": ("ContractCreateDatasetRequest", "create_dataset"),
+    "create_question": ("ContractCreateQuestionRequest", "create_question"),
+    "put_requirements": ("ContractUpsertCommand", "put_question_requirements"),
+    "register_source": ("ContractRegisterCommand", "register_source"),
+    "create_plan": ("ContractCreateCommand", "create_table_plan"),
+    "create_source_staging": ("CreateSourceStagingCommand", "create_source_staging"),
+    "complete_artifact_upload": (
+        "ContractCompleteArtifactUploadCommand",
+        "complete_artifact_upload",
+    ),
+    "finalize_source_staging": ("FinalizeSourceStagingCommand", "finalize_source_staging"),
+    "register_connector": (
+        "ConnectorConfigurationRegistrationCommand",
+        "register_connector_configuration",
+    ),
+    "create_proposal": ("ContractProposalCommand", "create_recipe_proposal"),
+    "request_approval": ("ContractApprovalCommand", "request_recipe_approval"),
+    # This is intentionally the dedicated V3 Table-recipe operation. The coordinated Studio client
+    # exposes only confirmation of the exact Table Recipe approval the Editor just requested, not
+    # generic approval decisions. Never map this to the generic V3 approval route or the retired V2
+    # recipe confirmation route.
+    "confirm_table_recipe_approval": (
+        "ContractDecisionCommand",
+        "confirm_table_recipe_approval",
+    ),
+    "activate_recipe": ("ContractActivateRecipeCommand", "activate_recipe"),
+}
+
+#: The read operations, as the generated method each one resolves to and the keyword it names its
+#: resource with.
+#:
+#: ⚠ A READ IS A DIFFERENT SHAPE, NOT A RARER WRITE. Every entry in `_OPERATIONS` above is built
+#: the same way: a request model from a body, an idempotency key, and a journaled plan written
+#: before the request is sent, because each of those operations changes something in Studio and
+#: has to be replayable. A read carries no body and no idempotency key, so there is nothing for
+#: that path to build and nothing for the journal to replay -- which is why `get_run` is here
+#: rather than as a thirteenth entry above, and why nothing on this path can mutate a Run by
+#: accident: the method names reachable through `read` are exactly these.
+_READ_OPERATIONS: dict[str, tuple[str, str]] = {
+    "get_proposal": ("get_recipe_proposal", "recipe_proposal_id"),
+    "get_run": ("get_run", "run_id"),
+}
+
+# The generated V3 distribution exports operations as modules.  Keep the deployment surface
+# closed by resolving only this audited inventory; no caller-provided operation name reaches an
+# import path.
+_GENERATED_OPERATION_MODULES = {
+    "create_dataset": ("datasets", "create_dataset"),
+    "create_question": ("questions", "create_question"),
+    "put_question_requirements": ("questions", "put_question_requirements"),
+    "register_source": ("sources", "register_source"),
+    "create_table_plan": ("plans", "create_table_plan"),
+    "create_source_staging": ("artifacts", "create_source_staging"),
+    "complete_artifact_upload": ("artifacts", "complete_artifact_upload"),
+    "finalize_source_staging": ("artifacts", "finalize_source_staging"),
+    "register_connector_configuration": ("connectors", "register_connector_configuration"),
+    "create_recipe_proposal": ("recipes", "create_recipe_proposal"),
+    "create_worker_policy_preflight": ("recipes", "create_worker_policy_preflight"),
+    "request_recipe_approval": ("recipes", "request_recipe_approval"),
+    "activate_recipe": ("recipes", "activate_recipe"),
+    "get_recipe_proposal": ("recipes", "get_recipe_proposal"),
+    "get_run": ("runs", "get_run"),
+}
+
+
+def build_editor_client(token: StudioToken) -> tuple[Any, Any]:
+    """Return the pinned V3 Table-recipe confirmation facade and its transport.
+
+    Written once because two lanes need the same thing: the deployment writes through this facade
+    and the dataset handoff reads through it, and a second copy of the construction would be a
+    second place for the contract pin, the redirect policy, or the timeout to be got wrong.
+
+    Raises:
+        HostedDeployError: when the pinned client is absent or incompatible.
+    """
+
+    try:
+        client_contract_identity()
+        client_module = importlib.import_module("mostlyright_studio.client")
+        authority_module = importlib.import_module("mostlyright_studio.authority")
+        authenticated = client_module.AuthenticatedClient(
+            base_url=token.studio_base_url,
+            token=token.token,
+            timeout=REQUEST_TIMEOUT_SECONDS,
+            follow_redirects=False,
+        )
+        return authenticated, authority_module.StudioV3RecipeConfirmationClient(authenticated)
+    except (ImportError, AttributeError, StudioBoundaryError) as error:
+        raise HostedDeployError("DEPLOY_STUDIO_CLIENT_INVALID", str(error)) from error
+
+
+class GeneratedStudioDeploymentClient:
+    """All remote deployment operations through the pinned generated editor facade."""
+
+    def __init__(self, token: StudioToken) -> None:
+        self._raw_client, self._editor_client = build_editor_client(token)
+        try:
+            self._models = importlib.import_module("mostlyright_studio.models")
+        except ImportError as error:
+            raise HostedDeployError("DEPLOY_STUDIO_CLIENT_INVALID", str(error)) from error
+        confirmation = getattr(self._editor_client, "confirm_table_recipe_approval", None)
+        if confirmation is None or not callable(getattr(confirmation, "sync_detailed", None)):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_CLIENT_INVALID",
+                "the pinned Studio client does not expose V3 Table-recipe confirmation; "
+                "install the coordinated regenerated Studio client before deploying",
+            )
+        try:
+            preflight = self._operation("create_worker_policy_preflight")
+        except ImportError as error:
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_CLIENT_INVALID",
+                "the installed generated Studio client does not expose "
+                "createWorkerPolicyPreflight; merge Studio #80 and install its regenerated client "
+                "before deploying",
+            ) from error
+        if not callable(getattr(preflight, "sync_detailed", None)):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_CLIENT_INVALID",
+                "the installed generated Studio client has no callable "
+                "createWorkerPolicyPreflight operation; merge Studio #80 and install its "
+                "regenerated client before deploying",
+            )
+        self._base_url = token.studio_base_url
+
+    def call(
+        self,
+        operation: str,
+        body: Mapping[str, Any] | None,
+        *,
+        idempotency_key: str | None = None,
+        resource_id: UUID | None = None,
+        if_match: str | None = None,
+    ) -> StudioResponse:
+        if operation in _READ_OPERATIONS:
+            return self.read(operation, resource_id=resource_id)
+        coordinate = _OPERATIONS.get(operation)
+        if coordinate is None or body is None or idempotency_key is None:
+            raise HostedDeployError("DEPLOY_REQUEST_INVALID", "deployment operation is incomplete")
+        model_name, method_name = coordinate
+        model = self._model(model_name, body)
+        kwargs: dict[str, Any] = {"body": model, "idempotency_key": idempotency_key}
+        if operation == "put_requirements":
+            kwargs.update(question_id=_required_uuid(resource_id, "question_id"), if_match=if_match)
+        elif operation in {"finalize_source_staging"}:
+            kwargs["source_staging_id"] = _required_uuid(resource_id, "source_staging_id")
+        elif operation == "complete_artifact_upload":
+            kwargs["artifact_id"] = _required_uuid(resource_id, "artifact_id")
+        elif operation in {"request_approval", "activate_recipe"}:
+            kwargs.update(
+                recipe_proposal_id=_required_uuid(resource_id, "recipe_proposal_id"),
+                if_match=if_match,
+            )
+        elif operation == "confirm_table_recipe_approval":
+            kwargs.update(
+                approval_request_id=_required_uuid(resource_id, "approval_request_id"),
+                if_match=if_match,
+            )
+        if operation == "confirm_table_recipe_approval":
+            confirmation = getattr(self._editor_client, method_name, None)
+            if confirmation is None or not callable(getattr(confirmation, "sync_detailed", None)):
+                raise HostedDeployError(
+                    "DEPLOY_STUDIO_CLIENT_INVALID",
+                    "the installed generated Studio client does not expose "
+                    "StudioV3RecipeConfirmationClient.confirm_table_recipe_approval; pin the "
+                    "coordinated "
+                    "regenerated Studio client before deployment",
+                )
+            response = confirmation.sync_detailed(**kwargs)
+        else:
+            response = self._operation(method_name).sync_detailed(client=self._raw_client, **kwargs)
+        return _generated_response(response)
+
+    def preflight(self, body: Mapping[str, Any]) -> StudioResponse:
+        """Resolve Studio's current worker policy without journaling it as a mutation."""
+
+        command = self._model("ContractWorkerPolicyPreflightCommand", body)
+        response = self._operation("create_worker_policy_preflight").sync_detailed(
+            client=self._raw_client,
+            body=command,
+        )
+        return _generated_response(response)
+
+    def read(self, operation: str, *, resource_id: UUID | None = None) -> StudioResponse:
+        """One bounded read of one Studio resource, sending no body and changing nothing.
+
+        Transport failures are deliberately not translated here. What a caller should say about an
+        unreachable Studio depends on what it was reading -- a status check that could not be made
+        is a retryable answer, an approved proposal that could not be fetched stops a deployment --
+        so the refusal is written where that is known rather than flattened into one code here.
+        """
+
+        coordinate = _READ_OPERATIONS.get(operation)
+        if coordinate is None:
+            raise HostedDeployError("DEPLOY_REQUEST_INVALID", "deployment operation is incomplete")
+        method_name, parameter = coordinate
+        response = self._operation(method_name).sync_detailed(
+            client=self._raw_client,
+            **{parameter: _required_uuid(resource_id, parameter)},
+        )
+        return _generated_response(response)
+
+    @staticmethod
+    def _operation(method_name: str) -> Any:
+        coordinate = _GENERATED_OPERATION_MODULES.get(method_name)
+        if coordinate is None:
+            raise HostedDeployError("DEPLOY_REQUEST_INVALID", "deployment operation is incomplete")
+        tag, module = coordinate
+        return importlib.import_module(f"mostlyright_studio.api.{tag}.{module}")
+
+    def upload(self, session: Mapping[str, Any], content: bytes) -> str:
+        expected_digest = "sha256:" + hashlib.sha256(content).hexdigest()
+        if (
+            session.get("direction") != "upload"
+            or session.get("method") != "PUT"
+            or session.get("route_authority") != "source_staging_editor"
+            or session.get("expected_content_digest") != expected_digest
+            or session.get("expected_size_bytes") != len(content)
+        ):
+            raise HostedDeployError(
+                "DEPLOY_SIGNED_SESSION_INVALID", "Studio returned a mismatched upload capability"
+            )
+        try:
+            import httpx
+        except ImportError as error:
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_CLIENT_INVALID", "the hosted extra does not contain httpx"
+            ) from error
+        headers = _signed_headers(session, size=len(content))
+        try:
+            with httpx.Client(
+                timeout=REQUEST_TIMEOUT_SECONDS, follow_redirects=False, trust_env=False
+            ) as client:
+                response = client.put(
+                    _transfer_url(_required_text(session, "signed_url"), self._base_url),
+                    headers=headers,
+                    content=content,
+                )
+        except httpx.RequestError as error:
+            raise HostedDeployError(
+                "DEPLOY_SOURCE_UPLOAD_FAILED", "the signed source upload could not be reached"
+            ) from error
+        if response.status_code not in {200, 201}:
+            if 400 <= response.status_code < 500:
+                raise HostedDeployError(
+                    "DEPLOY_SOURCE_UPLOAD_SESSION_REJECTED",
+                    "the signed source upload capability was rejected and must be renewed",
+                )
+            raise HostedDeployError(
+                "DEPLOY_SOURCE_UPLOAD_FAILED",
+                f"the signed source upload returned HTTP {response.status_code}",
+            )
+        generation = response.headers.get(
+            "x-mostlyright-object-generation", response.headers.get("x-goog-generation", "")
+        )
+        if _OBJECT_GENERATION.fullmatch(generation) is None:
+            raise HostedDeployError(
+                "DEPLOY_SOURCE_UPLOAD_FAILED", "the upload response omitted object generation"
+            )
+        return generation
+
+    def close(self) -> None:
+        client = getattr(self._raw_client, "_client", None)
+        if client is not None:
+            client.close()
+
+    def _model(self, name: str, body: Mapping[str, Any]) -> Any:
+        model_type = getattr(self._models, name, None)
+        if model_type is None:
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_CLIENT_INVALID", f"the generated Studio client lacks {name}"
+            )
+        try:
+            model = model_type.from_dict(dict(body))
+        except (KeyError, TypeError, ValueError) as error:
+            raise HostedDeployError(
+                "DEPLOY_REQUEST_INVALID", f"the deployment handoff is not a valid {name}"
+            ) from error
+        if model.to_dict() != dict(body):
+            raise HostedDeployError(
+                "DEPLOY_REQUEST_INVALID", f"the deployment handoff is not the exact {name} shape"
+            )
+        return model
+
+
+class FileDeploymentStateStore:
+    """Canonical, atomically replaced non-secret journal under the reviewed run directory."""
+
+    def __init__(self, run_dir: Path) -> None:
+        self._run_dir = Path(run_dir).absolute()
+        self._path = self._run_dir / STATE_RELATIVE_PATH
+        self._run_handle = None
+        self._directory_descriptors: list[int] = []
+        self._directory_bindings: list[tuple[int, str, int, int, int]] = []
+        try:
+            self._run_handle = pipeline._open_candidate_run_handle(self._run_dir)
+            evidence = self._open_directory(self._run_handle.run_fd, "evidence")
+            deployment = self._open_directory(evidence, "deployment")
+            self._deployment_fd = deployment
+            fcntl.flock(self._deployment_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            self._validate()
+        except (OSError, pipeline.BuildError) as error:
+            self.close()
+            raise HostedDeployError(
+                "DEPLOY_STATE_UNAVAILABLE",
+                "the deployment journal directory is unavailable, unsafe, or already in use",
+            ) from error
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def exists(self) -> bool:
+        self._validate()
+        try:
+            os.stat("state.json", dir_fd=self._deployment_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            return False
+        except OSError as error:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", "the deployment journal is unavailable or unsafe"
+            ) from error
+        return True
+
+    def load(self) -> dict[str, Any]:
+        try:
+            descriptor = os.open(
+                "state.json",
+                os.O_RDONLY
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_NONBLOCK", 0)
+                | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=self._deployment_fd,
+            )
+        except OSError as error:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", "the deployment journal is unavailable or unsafe"
+            ) from error
+        try:
+            info = os.fstat(descriptor)
+            if (
+                not stat.S_ISREG(info.st_mode)
+                or not 0 < info.st_size <= MAX_STATE_BYTES
+                or info.st_nlink != 1
+            ):
+                raise HostedDeployError(
+                    "DEPLOY_STATE_INVALID", "the deployment journal is not a bounded regular file"
+                )
+            chunks: list[bytes] = []
+            remaining = MAX_STATE_BYTES + 1
+            while remaining:
+                chunk = os.read(descriptor, min(64 * 1024, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            raw = b"".join(chunks)
+            after = os.fstat(descriptor)
+            named = os.stat("state.json", dir_fd=self._deployment_fd, follow_symlinks=False)
+            if _file_identity(after) != _file_identity(info) or _file_identity(
+                named
+            ) != _file_identity(info):
+                raise HostedDeployError(
+                    "DEPLOY_STATE_INVALID", "the deployment journal changed while being read"
+                )
+        finally:
+            os.close(descriptor)
+        self._validate()
+        try:
+            value = canonical.parse_canonical_json(raw)
+        except canonical.CanonicalJSONError as error:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", "the deployment journal is not canonical JSON"
+            ) from error
+        if not isinstance(value, dict):
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", "the deployment journal must be one object"
+            )
+        return value
+
+    def save(self, state: Mapping[str, Any]) -> None:
+        raw = canonical.canonical_json_bytes(dict(state))
+        if len(raw) > MAX_STATE_BYTES:
+            raise HostedDeployError("DEPLOY_STATE_INVALID", "the deployment journal is too large")
+        self._validate()
+        temporary = f".state.{os.getpid()}.{os.urandom(8).hex()}.partial"
+        descriptor = -1
+        try:
+            descriptor = os.open(
+                temporary,
+                os.O_WRONLY
+                | os.O_CREAT
+                | os.O_EXCL
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_CLOEXEC", 0),
+                0o600,
+                dir_fd=self._deployment_fd,
+            )
+            offset = 0
+            while offset < len(raw):
+                offset += os.write(descriptor, raw[offset:])
+            os.fsync(descriptor)
+            os.close(descriptor)
+            descriptor = -1
+            self._validate()
+            os.replace(
+                temporary,
+                "state.json",
+                src_dir_fd=self._deployment_fd,
+                dst_dir_fd=self._deployment_fd,
+            )
+            os.fsync(self._deployment_fd)
+            self._validate()
+        except Exception:
+            if descriptor >= 0:
+                os.close(descriptor)
+            try:
+                os.unlink(temporary, dir_fd=self._deployment_fd)
+            except FileNotFoundError:
+                pass
+            raise
+
+    def close(self) -> None:
+        descriptors = list(reversed(getattr(self, "_directory_descriptors", [])))
+        self._directory_descriptors = []
+        for descriptor in descriptors:
+            try:
+                os.close(descriptor)
+            except OSError:
+                pass
+        handle = getattr(self, "_run_handle", None)
+        self._run_handle = None
+        if handle is not None:
+            handle.close()
+
+    def _open_directory(self, parent_fd: int, name: str) -> int:
+        try:
+            os.mkdir(name, 0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            pass
+        descriptor = os.open(
+            name,
+            os.O_RDONLY
+            | getattr(os, "O_DIRECTORY", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=parent_fd,
+        )
+        opened = os.fstat(descriptor)
+        if not stat.S_ISDIR(opened.st_mode):
+            os.close(descriptor)
+            raise OSError("deployment state component is not a directory")
+        self._directory_descriptors.append(descriptor)
+        self._directory_bindings.append((parent_fd, name, descriptor, opened.st_dev, opened.st_ino))
+        return descriptor
+
+    def _validate(self) -> None:
+        if self._run_handle is None:
+            raise HostedDeployError("DEPLOY_STATE_INVALID", "the deployment journal is closed")
+        try:
+            pipeline._validate_candidate_run_handle(self._run_handle)
+            for parent_fd, name, descriptor, device, inode in self._directory_bindings:
+                opened = os.fstat(descriptor)
+                named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+                expected = (device, inode)
+                if (
+                    not stat.S_ISDIR(opened.st_mode)
+                    or not stat.S_ISDIR(named.st_mode)
+                    or (opened.st_dev, opened.st_ino) != expected
+                    or (named.st_dev, named.st_ino) != expected
+                ):
+                    raise OSError("deployment state directory changed")
+        except (OSError, pipeline.BuildError) as error:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", "the deployment journal path changed during deployment"
+            ) from error
+
+
+def journaled_reviewed_build(run_dir: Path) -> Mapping[str, Any] | None:
+    """Return a legacy reviewed-Build binding recorded in a deployment journal.
+
+    This compatibility reader does not participate in the ordinary Editor deploy path. That path
+    always rebuilds and re-verifies the local Build, then confirms its internal Studio approval in
+    the same invocation; ``--resume`` only replays an interrupted mutation chain.
+
+    Raises:
+        HostedDeployError: when there is no journal to resume, or it cannot be read safely.
+    """
+
+    store = FileDeploymentStateStore(run_dir)
+    try:
+        if not store.exists():
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISSING", f"no deployment journal exists at {store.path}"
+            )
+        state = store.load()
+    finally:
+        store.close()
+    resources = state.get("resources")
+    proposal = resources.get("proposal") if isinstance(resources, dict) else None
+    evidence = proposal.get("bootstrap_evidence") if isinstance(proposal, dict) else None
+    reviewed = evidence.get("reviewed_build") if isinstance(evidence, dict) else None
+    return reviewed if isinstance(reviewed, Mapping) else None
+
+
+def _legacy_local_build_bootstrap_table_digest(bootstrap: Mapping[str, Any]) -> str:
+    """Return the local-Build activation digest or refuse a Studio-owned first build.
+
+    ``deploy_managed_dataset`` predates hosted-first Recipes.  It owns the local Build it has just
+    staged, confirmed, and then activates by passing that Build's digest to Studio.  A
+    ``hosted_first_build`` has no such local Build: Studio/Cloud owns its atomic approval and
+    first-run transition.  Treating that object as local evidence would either leak a raw
+    ``KeyError`` or activate the same Recipe a second time.
+
+    Omitted ``origin`` remains the historical local shape for backwards compatibility.
+    """
+
+    origin = bootstrap.get("origin", "local_build")
+    if origin == "hosted_first_build":
+        raise HostedDeployError(
+            "DEPLOY_HOSTED_FIRST_STUDIO_OWNED",
+            "this Recipe's hosted first build is owned by Studio/Cloud; approve and start it "
+            "there instead of using the legacy local-Build deploy command",
+        )
+    if origin != "local_build":
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio returned an unknown Recipe bootstrap origin",
+        )
+    digest = bootstrap.get("bootstrap_table_digest")
+    if not isinstance(digest, str) or _DIGEST.fullmatch(digest) is None:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio's local-Build Recipe bootstrap omitted a valid bootstrap_table_digest",
+        )
+    return digest
+
+
+def deploy_managed_dataset(
+    request: DeploymentRequest,
+    *,
+    run_dir: Path,
+    previous_run_dir: Path | None,
+    token: StudioToken,
+    credentials: ResolvedCloudCredentials,
+    resume: bool,
+    cron: str = "0 0 * * *",
+    max_concurrent_runs: int = 1,
+    state_store: DeploymentStateStore | None = None,
+    client_factory: Callable[
+        [StudioToken], StudioDeploymentClient
+    ] = GeneratedStudioDeploymentClient,
+    cloud_transport: TokenExchangeTransport | None = None,
+) -> dict[str, Any]:
+    """Prepare and activate one exact Dataset, or resume it after interruption.
+
+    ``previous_run_dir`` is the run directory whose own deployment published the Dataset this one
+    updates, and naming it is what makes this a successor rather than a first deployment. Its
+    *absence* is refused here, by :func:`_deployment_predecessor`, and only for the one shape this
+    layer can judge alone: a Build whose Recipe is a successor version, which exists because a
+    Dataset it follows exists. The opposite rule -- that a Build executed as an ``initial`` run
+    must not name a predecessor, because it never read one -- is enforced where the request is
+    built, in :func:`deploy.build_deployment_request`, which is the only layer that can see the
+    execution mode. So this function trusts its caller for that half; every command in this
+    repository builds its request through that function first.
+    """
+
+    _deployment_options(request.dataset_name, cron, max_concurrent_runs)
+    if token.workspace_id is None:
+        raise HostedDeployError("DEPLOY_TOKEN_EXCHANGE_FAILED", "Studio workspace is missing")
+    predecessor = _deployment_predecessor(request, previous_run_dir)
+    owns_store = state_store is None
+    store = state_store or FileDeploymentStateStore(run_dir)
+    cloud_url = _service_url(credentials.cloud_url, "Cloud URL", allow_loopback_http=False)
+    identity = canonical.canonical_sha256(
+        {
+            "request_digest": request.digest(),
+            "workspace_id": str(token.workspace_id),
+            "cloud_url": cloud_url,
+            "cron": cron,
+            "max_concurrent_runs": max_concurrent_runs,
+            # Which live Dataset this updates is an input like the schedule is, and it is the one
+            # a resume can get wrong without changing the request at all. The key is present only
+            # when there is a predecessor, so every deployment that could already be in flight --
+            # all of them, until this release gave the command a flag to name one -- keeps the
+            # exact identity it was staged under.
+            **({} if predecessor is None else {"previous_run_dir": predecessor}),
+        }
+    )
+    inputs = _identity_inputs(
+        request,
+        workspace_id=token.workspace_id,
+        cloud_url=cloud_url,
+        cron=cron,
+        max_concurrent_runs=max_concurrent_runs,
+        previous_run_dir=predecessor,
+    )
+    if store.exists():
+        state = store.load()
+        _validate_state(
+            state,
+            identity,
+            token.workspace_id,
+            inputs=inputs,
+            request_digest=request.digest(),
+        )
+        _refuse_legacy_approval_journal(state)
+        if not resume and state.get("status") != "initialized":
+            raise HostedDeployError(
+                "DEPLOY_STATE_EXISTS",
+                f"deployment journal already exists at {store.path}; rerun with --resume",
+            )
+    else:
+        if resume:
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISSING", f"no deployment journal exists at {store.path}"
+            )
+        state = {
+            "schema_version": DEPLOYMENT_STATE_SCHEMA,
+            "deployment_identity": identity,
+            "request_digest": request.digest(),
+            # The inputs behind that identity, recorded so a refusal hours or days later can name
+            # the one that moved. The identity itself is unchanged and stays the only thing any
+            # check compares; this is what turns its refusal into a sentence.
+            "identity_inputs": inputs,
+            "workspace_id": str(token.workspace_id),
+            "status": "initialized",
+            "schedule": {
+                "cron": cron,
+                "timezone": "UTC",
+                "mode": "incremental_refresh",
+                "max_concurrent_runs": max_concurrent_runs,
+            },
+            "operations": {},
+            "resources": {},
+        }
+        store.save(state)
+
+    client: StudioDeploymentClient | None = None
+    try:
+        client = client_factory(token)
+        proposal = _prepare_and_decide_approval(
+            request,
+            state,
+            store,
+            client,
+            run_dir=Path(run_dir),
+            previous_run_dir=previous_run_dir,
+            workspace_id=token.workspace_id,
+        )
+        proposal_id = _uuid(proposal["recipe_proposal_id"], "recipe_proposal_id")
+        fetched = client.call("get_proposal", None, resource_id=proposal_id)
+        fetched_body = _success(fetched, {200}, "DEPLOY_PROPOSAL_READ_FAILED")
+        _same(fetched_body, "recipe_digest", request.recipe_digest)
+        activation_intent = {
+            "table_name": request.dataset_name,
+            "schedule": state["schedule"],
+        }
+        _same(fetched_body, "activation_intent", activation_intent)
+        if fetched_body.get("status") not in {"approved", "activation_started"}:
+            raise HostedDeployError(
+                "DEPLOY_APPROVAL_DECISION_INVALID",
+                "Studio has not recorded this authenticated Editor's approval for the exact "
+                "Recipe proposal",
+            )
+        etag = _etag(fetched, "proposal read")
+        approval_request_id = _uuid_field(fetched_body, "approval_request_id")
+        approval_decision_id = _uuid_field(fetched_body, "approval_decision_id")
+        bootstrap = fetched_body.get("bootstrap_evidence")
+        if not isinstance(bootstrap, dict):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_RESPONSE_INVALID", "the approved proposal omitted Build evidence"
+            )
+        bootstrap_table_digest = _legacy_local_build_bootstrap_table_digest(bootstrap)
+        activation_body = {
+            "schema_version": STUDIO_SCHEMA_VERSION,
+            "workspace_id": str(token.workspace_id),
+            "recipe_proposal_id": str(proposal_id),
+            "table_recipe_id": request.recipe_id,
+            "recipe_version": request.recipe_version,
+            "recipe_digest": request.recipe_digest,
+            "source_authority_bindings": fetched_body["source_authority_bindings"],
+            "source_authority_bindings_digest": fetched_body["source_authority_bindings_digest"],
+            "approval_request_id": str(approval_request_id),
+            "approval_decision_id": str(approval_decision_id),
+            "bootstrap_table_digest": bootstrap_table_digest,
+            "table_name": activation_intent["table_name"],
+            "schedule": activation_intent["schedule"],
+        }
+        activation = _mutate(
+            state,
+            store,
+            client,
+            name="activation",
+            operation="activate_recipe",
+            body=activation_body,
+            expected={202},
+            resource_id=proposal_id,
+            if_match=etag,
+        )
+        state["resources"]["activation"] = dict(activation)
+        state["status"] = "activation_queued"
+        store.save(state)
+        binding = _bind_cloud_dataset(
+            request,
+            state,
+            store,
+            credentials=credentials,
+            transport=cloud_transport,
+        )
+        state["resources"]["cloud_binding"] = dict(binding)
+        state["status"] = "cloud_dataset_bound"
+        store.save(state)
+        return _activation_receipt(state, store, cloud_url)
+    finally:
+        if client is not None:
+            client.close()
+        if owns_store:
+            store.close()
+
+
+def _worker_policy_preflight(
+    request: DeploymentRequest,
+    recipe_document: Mapping[str, Any],
+    proposal: Mapping[str, Any],
+    client: StudioDeploymentClient,
+) -> dict[str, Any]:
+    """Require Studio's selected fleet to match this runtime before approval."""
+
+    command_fields = (
+        "workspace_id",
+        "dataset_id",
+        "table_plan_id",
+        "table_recipe_id",
+        "recipe_version",
+        "recipe_digest",
+        "recipe_proposal_id",
+    )
+    try:
+        command = {field: proposal[field] for field in command_fields}
+    except KeyError as error:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio's recipe proposal omitted worker-policy preflight scope",
+        ) from error
+    if "table_id" in proposal:
+        command["table_id"] = proposal["table_id"]
+    response = client.preflight(command)
+    preflight = dict(_success(response, {200}, "DEPLOY_WORKER_POLICY_PREFLIGHT_FAILED"))
+
+    required = {
+        "schema_version",
+        "workspace_id",
+        "dataset_id",
+        "table_plan_id",
+        "table_recipe_id",
+        "recipe_version",
+        "recipe_digest",
+        "builder_image_digest",
+        "verifier_image_digest",
+        "validation_policy_digest",
+        "selection_fence",
+        "selection_id",
+        "policy_mode",
+        "validation_policy_digests",
+        "policy_set_digest",
+    }
+    expected_fields = required | ({"table_id"} if "table_id" in command else set())
+    if (
+        set(preflight) != expected_fields
+        or preflight.get("schema_version") != STUDIO_SCHEMA_VERSION
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio returned a non-exact worker-policy preflight",
+        )
+    for field in (
+        "workspace_id",
+        "dataset_id",
+        "table_plan_id",
+        "table_id",
+        "table_recipe_id",
+        "recipe_version",
+        "recipe_digest",
+    ):
+        if field in command and preflight.get(field) != command[field]:
+            raise HostedDeployError(
+                "DEPLOY_WORKER_POLICY_MISMATCH",
+                f"Studio's worker-policy preflight {field} differs from the frozen Recipe proposal",
+            )
+
+    transform_plan = recipe_document.get("transform_plan")
+    plan_schema = (
+        transform_plan.get("schema_version") if isinstance(transform_plan, Mapping) else None
+    )
+    modes = {
+        "local-table-plan.v1": "table",
+        "local-graph-table-plan.v1": "graph",
+    }
+    policy_mode = modes.get(plan_schema)
+    if policy_mode is None:
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID",
+            "the frozen Recipe has no supported table or graph transform plan",
+        )
+    local_policies = {
+        "table": "sha256:" + pipeline.validation_policy_digest(graph=False),
+        "graph": "sha256:" + pipeline.validation_policy_digest(graph=True),
+    }
+    local_policy_set_digest = "sha256:" + canonical.canonical_sha256(local_policies)
+    selected_policies = preflight.get("validation_policy_digests")
+    selected_policy = preflight.get("validation_policy_digest")
+    if (
+        selected_policies != local_policies
+        or preflight.get("policy_set_digest") != local_policy_set_digest
+        or preflight.get("policy_mode") != policy_mode
+        or selected_policy != local_policies[policy_mode]
+    ):
+        raise HostedDeployError(
+            "DEPLOY_WORKER_POLICY_MISMATCH",
+            "your CLI and the hosted workers disagree about the validation policy: "
+            f"Studio selected {selected_policy} for {preflight.get('policy_mode')}, while this "
+            f"Recipe runtime computes {local_policies[policy_mode]} for {policy_mode}; re-export "
+            "with 'mr-data recipe-export', or wait for the hosted fleet to be republished",
+        )
+
+    builder_image = preflight.get("builder_image_digest")
+    verifier_image = preflight.get("verifier_image_digest")
+    selection_fence = preflight.get("selection_fence")
+    selection_id = preflight.get("selection_id")
+    if (
+        not isinstance(builder_image, str)
+        or _IMMUTABLE_IMAGE.fullmatch(builder_image) is None
+        or not isinstance(verifier_image, str)
+        or _IMMUTABLE_IMAGE.fullmatch(verifier_image) is None
+        or not isinstance(selection_fence, str)
+        or _PREFIXED_DIGEST.fullmatch(selection_fence) is None
+        or not isinstance(selection_id, str)
+        or _DIGEST.fullmatch(selection_id) is None
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio returned an invalid worker-policy selection identity",
+        )
+    selection = {
+        "schema_version": "mostlyright-worker-policy-binding.v2",
+        "producer_image_digest": builder_image,
+        "verifier_image_digest": verifier_image,
+        "validation_policy_digests": local_policies,
+        "policy_set_digest": local_policy_set_digest,
+        "release_revision_coordinate": selection_fence,
+    }
+    if canonical.canonical_sha256(selection) != selection_id:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            "Studio's worker-policy selection ID does not bind its exact images, policy set, and "
+            "release fence",
+        )
+    if request.recipe_digest != preflight["recipe_digest"]:
+        raise HostedDeployError(
+            "DEPLOY_WORKER_POLICY_MISMATCH",
+            "Studio's worker-policy preflight does not bind the exact local Recipe",
+        )
+    return preflight
+
+
+def _prepare_and_decide_approval(
+    request: DeploymentRequest,
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    client: StudioDeploymentClient,
+    *,
+    run_dir: Path,
+    previous_run_dir: Path | None,
+    workspace_id: UUID,
+) -> Mapping[str, Any]:
+    recipe_document = canonical.parse_canonical_json(request.canonical_recipe_json.encode("utf-8"))
+    if not isinstance(recipe_document, dict):
+        raise HostedDeployError("DEPLOY_REQUEST_INVALID", "Recipe must be one object")
+    resources = state["resources"]
+    # Whether this deployment founds a Dataset or updates one is decided by whether it named a
+    # predecessor, which is the same question `recipe.verify_recipe_candidate` asks -- a Recipe
+    # execution names its predecessor exactly when its mode is not `initial`, and `deploy.py`
+    # refuses both shapes where the two would disagree. Branching on `recipe_version` instead
+    # looked equivalent and is not: a refresh of an unchanged Recipe is a successor whose Recipe
+    # version has not moved, and it would arrive here to have its project, question, plan and
+    # Dataset created a second time.
+    if previous_run_dir is None:
+        project = _mutate(
+            state,
+            store,
+            client,
+            name="project",
+            operation="create_dataset",
+            body={
+                "workspace_id": str(workspace_id),
+                "name": request.dataset_name,
+                "description": "Managed from an exact reviewed local Recipe Build.",
+            },
+            expected={201},
+        )
+        dataset_id = _uuid_field(project, "dataset_id")
+        question = _mutate(
+            state,
+            store,
+            client,
+            name="question",
+            operation="create_question",
+            body={
+                "workspace_id": str(workspace_id),
+                "dataset_id": str(dataset_id),
+                "question": recipe_document["question"]["text"],
+            },
+            expected={201},
+        )
+        question_id = _uuid_field(question, "question_id")
+        requirements_document = recipe_document["requirements"]
+        requirements = _mutate(
+            state,
+            store,
+            client,
+            name="requirements",
+            operation="put_requirements",
+            body={
+                "schema_version": STUDIO_SCHEMA_VERSION,
+                "workspace_id": str(workspace_id),
+                "population": requirements_document["population"],
+                "time_range": requirements_document["time_range"],
+                "output_grain": requirements_document["output_grain"]["columns"],
+                "required_fields": requirements_document["required_fields"],
+                "target_policy": requirements_document["target_policy"],
+                "success_criteria": requirements_document["success_criteria"],
+                "feasibility": _studio_feasibility(requirements_document["feasibility"]),
+                **(
+                    {"prediction_cutoff": requirements_document["prediction_cutoff"]}
+                    if "prediction_cutoff" in requirements_document
+                    else {}
+                ),
+            },
+            expected={200, 201},
+            resource_id=question_id,
+            # The requirements upsert is preconditioned on the REQUIREMENTS
+            # subresource's own version, not the question's: Studio's
+            # put_requirements allows the initial upsert only as If-Match: "*"
+            # (allow_initial), and the question ETag can never satisfy it.
+            if_match="*",
+        )
+        requirements_id = _uuid_field(requirements, "requirements_id")
+        source_registry_ids = _register_sources(
+            request,
+            recipe_document,
+            state,
+            store,
+            client,
+            run_dir=run_dir,
+            previous_run_dir=previous_run_dir,
+            dataset_id=dataset_id,
+            workspace_id=workspace_id,
+        )
+        policy = recipe_document.get("backfill_policy") or _default_backfill_policy(
+            requirements_document["time_range"]
+        )
+        plan = _mutate(
+            state,
+            store,
+            client,
+            name="plan",
+            operation="create_plan",
+            body={
+                "schema_version": STUDIO_SCHEMA_VERSION,
+                "workspace_id": str(workspace_id),
+                "dataset_id": str(dataset_id),
+                "question_id": str(question_id),
+                "requirements_id": str(requirements_id),
+                "source_ids": [str(value) for value in source_registry_ids],
+                "output_grain": requirements_document["output_grain"]["columns"],
+                "transformation_contract_version": "1.0.0",
+                "execution_plan_digest": "sha256:" + request.execution_plan_digest,
+                "validation_policy_digest": "sha256:"
+                + request.bootstrap_evidence["bootstrap_verification_digest"],
+                "approved_backfill_policy": policy,
+                "backfill_policy_digest": "sha256:" + canonical.canonical_sha256(policy),
+            },
+            expected={201},
+        )
+        table_plan_id = _uuid_field(plan, "table_plan_id")
+    else:
+        previous = _previous_deployment_resources(previous_run_dir)
+        dataset_id = _uuid(previous["dataset_id"], "dataset_id")
+        table_plan_id = _uuid(previous["table_plan_id"], "table_plan_id")
+        resources["previous_dataset_id"] = previous["dataset_id"]
+        store.save(state)
+
+    authorities = _source_authorities(
+        request,
+        recipe_document,
+        state,
+        store,
+        client,
+        run_dir=run_dir,
+        previous_run_dir=previous_run_dir,
+        workspace_id=workspace_id,
+    )
+    inventory_digest = canonical.canonical_sha256(
+        [
+            {
+                "source_id": item["source_id"],
+                "source_authority_digest": item["source_authority_digest"],
+            }
+            for item in authorities
+        ]
+    )
+    proposal_body = {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "dataset_id": str(dataset_id),
+        "table_plan_id": str(table_plan_id),
+        "recipe_media_type": "application/vnd.mostlyright.frozen-recipe+json",
+        "recipe_schema_version": request.recipe_schema_version,
+        "table_recipe_id": request.recipe_id,
+        "recipe_version": request.recipe_version,
+        "predecessor_recipe_digest": recipe_document.get("predecessor_recipe_digest"),
+        "canonical_recipe_json": request.canonical_recipe_json,
+        "recipe_digest": request.recipe_digest,
+        "source_authority_bindings": authorities,
+        "source_authority_bindings_digest": inventory_digest,
+        "bootstrap_evidence": request.bootstrap_evidence,
+        "activation_intent": {
+            "table_name": request.dataset_name,
+            "schedule": state["schedule"],
+        },
+        **({} if previous_run_dir is None else {"dataset_id": resources["previous_dataset_id"]}),
+    }
+    proposal = _mutate(
+        state,
+        store,
+        client,
+        name="proposal",
+        operation="create_proposal",
+        body=proposal_body,
+        expected={201},
+        # The approval request below conditions on this ETag.
+        requires_etag=True,
+    )
+    proposal_id = _uuid_field(proposal, "recipe_proposal_id")
+    _same(proposal, "recipe_digest", request.recipe_digest)
+    activation_operation = state["operations"].get("activation")
+    if (
+        state.get("status") == "cloud_dataset_bound"
+        and isinstance(resources.get("activation"), dict)
+        and isinstance(activation_operation, dict)
+        and activation_operation.get("status") == "completed"
+    ):
+        return proposal
+    worker_policy_preflight = _worker_policy_preflight(
+        request,
+        recipe_document,
+        proposal,
+        client,
+    )
+    proposal_etag = _resource_etag(state, "proposal")
+    approval = _mutate(
+        state,
+        store,
+        client,
+        name="approval_request",
+        operation="request_approval",
+        body={
+            "schema_version": STUDIO_SCHEMA_VERSION,
+            "workspace_id": str(workspace_id),
+            "recipe_proposal_id": str(proposal_id),
+            "recipe_digest": request.recipe_digest,
+            "worker_policy_preflight": worker_policy_preflight,
+        },
+        expected={201},
+        resource_id=proposal_id,
+        if_match=proposal_etag,
+        # The confirmation below conditions on this ETag, and reads it from the journal.
+        requires_etag=True,
+    )
+    approval_request_id = _uuid_field(approval, "approval_request_id")
+    _same(approval, "status", "pending")
+    _same(approval, "subject_digest", request.recipe_digest)
+    approval_version = _positive_int_field(approval, "version")
+    approval_etag = _resource_etag(state, "approval_request")
+    decision = _mutate(
+        state,
+        store,
+        client,
+        name="approval_confirmation",
+        operation="confirm_table_recipe_approval",
+        body={
+            "schema_version": STUDIO_SCHEMA_VERSION,
+            "workspace_id": str(workspace_id),
+            "decision": "approved",
+            "expected_request_version": approval_version,
+            "subject_digest": request.recipe_digest,
+        },
+        expected={200},
+        resource_id=approval_request_id,
+        if_match=approval_etag,
+    )
+    _same(decision, "approval_request_id", str(approval_request_id))
+    _same(decision, "decision", "approved")
+    _same(decision, "subject_digest", request.recipe_digest)
+    resources["approval_request_id"] = str(approval_request_id)
+    resources["approval_decision_id"] = str(_uuid_field(decision, "approval_decision_id"))
+    resources["dataset_id"] = str(dataset_id)
+    resources["table_plan_id"] = str(table_plan_id)
+    state["status"] = "approval_decided"
+    store.save(state)
+    return proposal
+
+
+def _acquisition_bundle(
+    request: DeploymentRequest,
+    *,
+    run_dir: Path,
+    previous_run_dir: Path | None,
+) -> Mapping[str, Any]:
+    """Return the closed acquisition-evidence bundle this request names, from either home.
+
+    A request that carries a reviewed-Build binding carries the bundle document inside it, and that
+    copy is used unchanged -- it is the exact document the binding's signature covers, so reading
+    it from anywhere else would check a different object than the one that was signed.
+
+    A request built for a dataset the caller publishes itself carries no binding, so the bundle is
+    read back out of the run directory under ``request.acquisition_bundle_digest``, which
+    :func:`deployment_evidence.load_acquisition_bundle_document` authenticates to this exact Build
+    before returning it. That digest is a field of the request, so it is inside the request digest,
+    so it is inside the deployment identity the journal is held to. This is the same route
+    ``_source_authorities`` already takes for the source bytes themselves.
+    """
+
+    reviewed = request.bootstrap_evidence.get("reviewed_build")
+    if isinstance(reviewed, Mapping):
+        bundle = reviewed["acquisition_bundle"]
+        if not isinstance(bundle, Mapping):
+            raise HostedDeployError(
+                "DEPLOY_REQUEST_INVALID", "the reviewed Build carries no acquisition bundle"
+            )
+        return bundle
+    try:
+        return deployment_evidence.load_acquisition_bundle_document(
+            run_dir,
+            request.acquisition_bundle_digest,
+            previous_run_dir=previous_run_dir,
+        )
+    except deployment_evidence.DeploymentEvidenceError as error:
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID",
+            f"the acquisition evidence for {run_dir} could not be read [{error.code}]",
+        ) from error
+
+
+def _register_sources(
+    request: DeploymentRequest,
+    recipe_document: Mapping[str, Any],
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    client: StudioDeploymentClient,
+    *,
+    run_dir: Path,
+    previous_run_dir: Path | None,
+    dataset_id: UUID,
+    workspace_id: UUID,
+) -> list[UUID]:
+    proposals = {item["source_id"]: item for item in recipe_document["source_proposals"]}
+    recipe_sources = {item["source_id"]: item for item in recipe_document["sources"]}
+    bundle_sources = {
+        item["source_id"]: item
+        for item in _acquisition_bundle(
+            request, run_dir=run_dir, previous_run_dir=previous_run_dir
+        )["sources"]
+    }
+    result: list[UUID] = []
+    for source_id in sorted(recipe_sources):
+        proposal = proposals[source_id]
+        source = recipe_sources[source_id]
+        bundle = bundle_sources[source_id]
+        locator = _source_locator(source, proposal, bundle)
+        response = _mutate(
+            state,
+            store,
+            client,
+            name=f"source_registry:{source_id}",
+            operation="register_source",
+            body={
+                "schema_version": STUDIO_SCHEMA_VERSION,
+                "workspace_id": str(workspace_id),
+                "dataset_id": str(dataset_id),
+                "name": proposal["display_name"],
+                "source_class": proposal["source_class"],
+                "locator": locator,
+                "credential_reference_ids": [],
+                "data_classification": source["declared_classification"],
+                "rights_claim": {
+                    "claimed_basis": (
+                        "permission_asserted"
+                        if proposal.get("rights_status") == "approved"
+                        else "unknown"
+                    ),
+                    "claim_evidence_digest": "sha256:"
+                    + canonical.canonical_sha256(proposal["evidence"]),
+                    "claim_note": source["lawful_basis"],
+                },
+                "retention_policy": {
+                    "raw_days": 30,
+                    "derived_days": 365,
+                    "tombstone_required": False,
+                },
+            },
+            expected={201},
+        )
+        result.append(_uuid_field(response, "source_id"))
+    return result
+
+
+def _source_authorities(
+    request: DeploymentRequest,
+    recipe_document: Mapping[str, Any],
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    client: StudioDeploymentClient,
+    *,
+    run_dir: Path,
+    previous_run_dir: Path | None,
+    workspace_id: UUID,
+) -> list[dict[str, Any]]:
+    bundle = _acquisition_bundle(request, run_dir=run_dir, previous_run_dir=previous_run_dir)
+    recipe_sources = {item["source_id"]: item for item in recipe_document["sources"]}
+    resources = state["resources"]
+    result: list[dict[str, Any]] = []
+    for entry in bundle["sources"]:
+        source_id = entry["source_id"]
+        if entry["authority_kind"] == "connector":
+            source = recipe_sources[source_id]
+            if source["adapter_id"] not in {"public.https", "external.openligadb"}:
+                raise HostedDeployError(
+                    "DEPLOY_CONNECTOR_UNSUPPORTED",
+                    f"{source_id} does not use a deployed refresh connector",
+                )
+            egress_attestation = (
+                PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION
+                if source["adapter_id"] == "public.https"
+                else OPENLIGADB_EGRESS_POLICY_ATTESTATION
+            )
+            body = {
+                "schema_version": STUDIO_SCHEMA_VERSION,
+                "workspace_id": str(workspace_id),
+                "source_id": source_id,
+                "adapter_id": source["adapter_id"],
+                "credential_mode": "none",
+                "crawler_egress_policy_attestation": egress_attestation,
+                **(
+                    {"query": source["query_template"]}
+                    if source["adapter_id"] == "public.https"
+                    else {}
+                ),
+            }
+            configuration = _mutate(
+                state,
+                store,
+                client,
+                name=f"connector:{source_id}",
+                operation="register_connector",
+                body=body,
+                expected={201},
+            )
+            authority = {
+                "source_id": source_id,
+                "authority_kind": "connector",
+                "source_authority_digest": "",
+                "adapter_id": source["adapter_id"],
+                "connector_configuration_id": configuration["connector_configuration_id"],
+                "connector_configuration_digest": configuration["configuration_digest"],
+                "credential_mode": "none",
+                "crawler_egress_policy_attestation": egress_attestation,
+            }
+            authority["source_authority_digest"] = canonical.canonical_sha256(
+                {key: value for key, value in authority.items() if key != "source_authority_digest"}
+            )
+            result.append(authority)
+            continue
+        payload = deployment_evidence.load_acquisition_source_payload(
+            run_dir,
+            request.acquisition_bundle_digest,
+            source_id,
+            previous_run_dir=previous_run_dir,
+        )
+        descriptors = {
+            role: {
+                "media_type": reference["media_type"],
+                "expected_content_digest": "sha256:" + reference["content_sha256"],
+                "expected_size_bytes": reference["size_bytes"],
+            }
+            for role, reference in (
+                ("source_data", entry["source_data"]),
+                ("acquisition_receipt", entry["acquisition_receipt"]),
+                ("source_observation", entry["source_observation"]),
+            )
+        }
+        content_by_role = {
+            "source_data": payload.source_data,
+            "acquisition_receipt": payload.acquisition_receipt,
+            "source_observation": payload.source_observation,
+        }
+        attempts = state.setdefault("source_staging_attempts", {})
+        attempt = attempts.get(source_id, 0)
+        if isinstance(attempt, bool) or not isinstance(attempt, int) or attempt < 0:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", f"source staging attempt for {source_id} is invalid"
+            )
+        renewed = False
+        while True:
+            suffix = "" if attempt == 0 else f":renew:{attempt}"
+            staging_id = _source_staging_id(request.digest(), workspace_id, source_id, attempt)
+            staging_command = {
+                "schema_version": STUDIO_SCHEMA_VERSION,
+                "source_staging_id": str(staging_id),
+                "workspace_id": str(workspace_id),
+                "source_id": source_id,
+                **descriptors,
+            }
+            staging = _mutate(
+                state,
+                store,
+                client,
+                name=f"source_staging:{source_id}{suffix}",
+                operation="create_source_staging",
+                body=staging_command,
+                expected={201},
+            )
+            artifacts = _validate_source_staging(
+                staging,
+                command=staging_command,
+                staging_id=staging_id,
+                workspace_id=workspace_id,
+                source_id=source_id,
+            )
+            if staging.get("status") == "finalized":
+                break
+            # A staging Studio has already sealed is replayed from its journaled finalize
+            # response instead of being walked again.
+            #
+            # ⚠ WHY THIS EXISTS. The create response journals signed upload sessions that live for
+            # minutes, and the whole point of a resume is that it arrives hours or days later,
+            # after a human has approved in Cloud. Walking the uploads again therefore always found
+            # those sessions expired, took the renewal path, and minted a SECOND staging: every
+            # source byte uploaded to Studio a second time, new artifact ids, and new source
+            # authorities -- which are inputs to the Recipe proposal the human already approved.
+            # The proposal short-circuit hid it, so the rebuilt bindings were discarded in silence
+            # and the resume looked fine. Reading the journaled request digest is what made it
+            # visible: the rebuilt proposal no longer matched the one Studio holds, because this
+            # invocation had just moved it.
+            #
+            # The sealed objects, their artifact ids and the source authority all come back in the
+            # finalize response, which is journaled. Replaying it keeps the authorities -- and the
+            # proposal built from them -- exactly what the approval was given against, and stops a
+            # resume re-uploading a Build that is already staged.
+            if isinstance(resources.get(f"source_finalize:{source_id}{suffix}"), dict):
+                staging = _mutate(
+                    state,
+                    store,
+                    client,
+                    name=f"source_finalize:{source_id}{suffix}",
+                    operation="finalize_source_staging",
+                    body={
+                        "schema_version": STUDIO_SCHEMA_VERSION,
+                        "workspace_id": str(workspace_id),
+                    },
+                    expected={200},
+                    resource_id=staging_id,
+                )
+                if staging.get("status") != "finalized":
+                    raise HostedDeployError(
+                        "DEPLOY_STUDIO_RESPONSE_INVALID",
+                        f"the journaled finalize for {source_id} does not report a sealed staging",
+                    )
+                artifacts = _validate_source_staging(
+                    staging,
+                    command=staging_command,
+                    staging_id=staging_id,
+                    workspace_id=workspace_id,
+                    source_id=source_id,
+                )
+                # The journaled finalize is what reconciled any transfer whose response was lost,
+                # so a replay records that here exactly as the live finalize does. Skipping it
+                # would leave the journal describing a transfer Studio has sealed as still planned.
+                _reconcile_lost_uploads(state, store, source_id)
+                break
+            try:
+                for role, artifact in artifacts.items():
+                    session = artifact["upload_session"]
+                    _validate_source_upload_session(
+                        session,
+                        role=role,
+                        artifact_id=_uuid(artifact["artifact_id"], "artifact_id"),
+                        staging_id=staging_id,
+                        workspace_id=workspace_id,
+                        descriptor=descriptors[role],
+                    )
+                    generation = _upload_once(
+                        state,
+                        store,
+                        client,
+                        name=f"source_upload:{source_id}:{role}{suffix}",
+                        session=session,
+                        content=content_by_role[role],
+                    )
+                    if generation is not None:
+                        _mutate(
+                            state,
+                            store,
+                            client,
+                            name=f"source_complete:{source_id}:{role}{suffix}",
+                            operation="complete_artifact_upload",
+                            body={
+                                "schema_version": STUDIO_SCHEMA_VERSION,
+                                "workspace_id": str(workspace_id),
+                                "reservation_id": session["reservation_id"],
+                                "reservation_digest": session["reservation_digest"],
+                                "upload_session_id": session["session_id"],
+                                "object_generation": generation,
+                                "observed_size_bytes": len(content_by_role[role]),
+                                "observed_content_digest": "sha256:"
+                                + hashlib.sha256(content_by_role[role]).hexdigest(),
+                            },
+                            expected={201},
+                            resource_id=_uuid(artifact["artifact_id"], "artifact_id"),
+                        )
+            except HostedDeployError as error:
+                if error.code != "DEPLOY_SOURCE_UPLOAD_SESSION_REJECTED" or renewed:
+                    raise
+                attempt += 1
+                attempts[source_id] = attempt
+                store.save(state)
+                renewed = True
+                continue
+            staging = _mutate(
+                state,
+                store,
+                client,
+                name=f"source_finalize:{source_id}{suffix}",
+                operation="finalize_source_staging",
+                body={"schema_version": STUDIO_SCHEMA_VERSION, "workspace_id": str(workspace_id)},
+                expected={200},
+                resource_id=staging_id,
+            )
+            artifacts = _validate_source_staging(
+                staging,
+                command=staging_command,
+                staging_id=staging_id,
+                workspace_id=workspace_id,
+                source_id=source_id,
+            )
+            _reconcile_lost_uploads(state, store, source_id)
+            break
+        authority = _validate_source_authority(
+            staging.get("authority"),
+            source_id=source_id,
+            workspace_id=workspace_id,
+            artifacts=artifacts,
+            descriptors=descriptors,
+        )
+        result.append(authority)
+    if [item["source_id"] for item in result] != sorted(recipe_sources):
+        raise HostedDeployError(
+            "DEPLOY_SOURCE_INVENTORY_MISMATCH", "Studio source authority inventory is not exact"
+        )
+    return result
+
+
+def _reconcile_lost_uploads(
+    state: dict[str, Any], store: DeploymentStateStore, source_id: str
+) -> None:
+    """Retire this source's still-planned transfers once Studio has sealed the staging.
+
+    A transfer can commit remotely while its response is lost, and :func:`_upload_once` leaves that
+    operation ``planned`` on purpose. The finalize response is what settles it: Studio names the
+    exact sealed object, so the plan is neither outstanding nor a failure. Recording it is not
+    bookkeeping for its own sake -- the journal is the evidence of what this deployment did.
+    """
+
+    for name, operation in list(state["operations"].items()):
+        if (
+            name.startswith(f"source_upload:{source_id}:")
+            and isinstance(operation, dict)
+            and operation.get("status") == "planned"
+        ):
+            state["operations"][name] = {**operation, "status": "reconciled"}
+    store.save(state)
+
+
+def _source_staging_id(
+    request_digest: str,
+    workspace_id: UUID,
+    source_id: str,
+    attempt: int,
+) -> UUID:
+    return uuid5(
+        NAMESPACE_URL,
+        f"mostlyright:source-staging:{request_digest}:{workspace_id}:{source_id}:attempt:{attempt}",
+    )
+
+
+_SOURCE_STAGING_ROLES = {
+    "source_data": ("raw_snapshot", "source_staging_source_data"),
+    "acquisition_receipt": (
+        "candidate_evidence",
+        "source_staging_acquisition_receipt",
+    ),
+    "source_observation": (
+        "candidate_evidence",
+        "source_staging_source_observation",
+    ),
+}
+
+
+def _validate_source_staging(
+    staging: Mapping[str, Any],
+    *,
+    command: Mapping[str, Any],
+    staging_id: UUID,
+    workspace_id: UUID,
+    source_id: str,
+) -> dict[str, Mapping[str, Any]]:
+    if (
+        staging.get("schema_version") != STUDIO_SCHEMA_VERSION
+        or staging.get("source_staging_id") != str(staging_id)
+        or staging.get("workspace_id") != str(workspace_id)
+        or staging.get("source_id") != source_id
+        or staging.get("requested_artifacts")
+        != {role: command[role] for role in _SOURCE_STAGING_ROLES}
+        or staging.get("status") not in {"preparing", "uploading", "finalized"}
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio returned a source staging outside the request for {source_id}",
+        )
+    raw = staging.get("artifacts")
+    if not isinstance(raw, list):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio returned an invalid source staging inventory for {source_id}",
+        )
+    artifacts: dict[str, Mapping[str, Any]] = {}
+    for item in raw:
+        if not isinstance(item, dict):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_RESPONSE_INVALID",
+                f"Studio returned an invalid source staging inventory for {source_id}",
+            )
+        role = item.get("role")
+        if role not in _SOURCE_STAGING_ROLES or role in artifacts:
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_RESPONSE_INVALID",
+                f"Studio returned a duplicate or unknown source staging role for {source_id}",
+            )
+        _uuid(item.get("artifact_id"), "artifact_id")
+        if not isinstance(item.get("upload_session"), dict):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_RESPONSE_INVALID",
+                f"Studio omitted a source staging session for {source_id}",
+            )
+        artifacts[role] = item
+    if set(artifacts) != set(_SOURCE_STAGING_ROLES):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio returned an incomplete source staging for {source_id}",
+        )
+    return artifacts
+
+
+def _validate_source_upload_session(
+    session: Mapping[str, Any],
+    *,
+    role: str,
+    artifact_id: UUID,
+    staging_id: UUID,
+    workspace_id: UUID,
+    descriptor: Mapping[str, Any],
+) -> None:
+    kind, purpose = _SOURCE_STAGING_ROLES[role]
+    forbidden = {"attempt_id", "producer_generation", "fence", "verification_generation"}
+    if (
+        session.get("schema_version") != STUDIO_SCHEMA_VERSION
+        or session.get("workspace_id") != str(workspace_id)
+        or session.get("run_id") != str(staging_id)
+        or session.get("artifact_id") != str(artifact_id)
+        or session.get("kind") != kind
+        or session.get("purpose") != purpose
+        or session.get("classification") != "restricted"
+        or session.get("media_type") != descriptor["media_type"]
+        or session.get("contract_version") != STUDIO_SCHEMA_VERSION
+        or session.get("direction") != "upload"
+        or session.get("route_authority") != "source_staging_editor"
+        or session.get("method") != "PUT"
+        or session.get("expected_content_digest") != descriptor["expected_content_digest"]
+        or session.get("expected_size_bytes") != descriptor["expected_size_bytes"]
+        or session.get("single_use") is not True
+        or any(field in session for field in forbidden)
+    ):
+        raise HostedDeployError(
+            "DEPLOY_SIGNED_SESSION_INVALID",
+            f"Studio returned an upload capability outside the {role} reservation",
+        )
+    for field in ("session_id", "reservation_id"):
+        _uuid(session.get(field), field)
+    for field in ("reservation_digest", "object_key_digest"):
+        value = session.get(field)
+        if (
+            not isinstance(value, str)
+            or not value.startswith("sha256:")
+            or _DIGEST.fullmatch(value.removeprefix("sha256:")) is None
+        ):
+            raise HostedDeployError(
+                "DEPLOY_SIGNED_SESSION_INVALID", f"Studio returned an invalid {field}"
+            )
+    issued_at = _timestamp(_required_text(session, "issued_at"), "issued_at")
+    expires_at = _timestamp(_required_text(session, "expires_at"), "expires_at")
+    if expires_at <= issued_at:
+        raise HostedDeployError(
+            "DEPLOY_SIGNED_SESSION_INVALID", "Studio returned an invalid upload session lifetime"
+        )
+    if expires_at <= datetime.now(UTC):
+        raise HostedDeployError(
+            "DEPLOY_SOURCE_UPLOAD_SESSION_REJECTED",
+            "the signed source upload session expired before it could be used",
+        )
+
+
+def _validate_source_authority(
+    raw: Any,
+    *,
+    source_id: str,
+    workspace_id: UUID,
+    artifacts: Mapping[str, Mapping[str, Any]],
+    descriptors: Mapping[str, Mapping[str, Any]],
+) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID", f"Studio omitted source authority for {source_id}"
+        )
+    authority = dict(raw)
+    reference_fields = {
+        "source_data": "source_artifact",
+        "acquisition_receipt": "acquisition_receipt_artifact",
+        "source_observation": "source_observation_artifact",
+    }
+    if (
+        authority.get("source_id") != source_id
+        or authority.get("authority_kind") != "sealed_artifact"
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio returned mismatched authority for {source_id}",
+        )
+    for role, field in reference_fields.items():
+        reference = authority.get(field)
+        if (
+            not isinstance(reference, dict)
+            or reference.get("workspace_id") != str(workspace_id)
+            or reference.get("artifact_id") != artifacts[role].get("artifact_id")
+            or reference.get("contract_version") != STUDIO_SCHEMA_VERSION
+            or reference.get("content_digest") != descriptors[role]["expected_content_digest"]
+        ):
+            raise HostedDeployError(
+                "DEPLOY_STUDIO_RESPONSE_INVALID",
+                f"Studio returned a mismatched {role} authority for {source_id}",
+            )
+    digest = authority.get("source_authority_digest")
+    expected = canonical.canonical_sha256(
+        {key: value for key, value in authority.items() if key != "source_authority_digest"}
+    )
+    if digest != expected:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio returned a mismatched authority digest for {source_id}",
+        )
+    return authority
+
+
+#: Where a journaled plan records one digest per top-level field of the request body.
+#:
+#: The whole-body digest says *that* a replayed request differs. This says *which* field does, and
+#: it is the difference between a refusal a person can act on and one they can only stare at. It is
+#: derived from the same body ``request_digest`` already covers, so it adds naming and never
+#: authority: no check reads it to decide whether a request matches, only to describe how it does
+#: not.
+_REQUEST_FIELDS = "request_field_digests"
+
+
+def _request_field_digests(body: Mapping[str, Any]) -> dict[str, str]:
+    """One digest per top-level field of a request body, so a replay can name what moved."""
+
+    return {str(field): canonical.canonical_sha256(value) for field, value in body.items()}
+
+
+def _journaled_request_digest(journaled: Any) -> str | None:
+    """The request digest a journaled operation records, or ``None`` when it records none."""
+
+    if not isinstance(journaled, Mapping):
+        return None
+    recorded = journaled.get("request_digest")
+    if not isinstance(recorded, str) or _DIGEST.fullmatch(recorded) is None:
+        return None
+    return recorded
+
+
+def _drifted_request_fields(journaled: Any, fields: Mapping[str, str]) -> str:
+    """The request fields that differ from the journaled plan, named for a person to read.
+
+    A plan journaled before per-field digests existed can only say that the request as a whole
+    differs, and that is exactly what this says about it. Naming a field the journal cannot see
+    would be a guess, and a guess in a refusal sends an operator to fix the wrong input.
+    """
+
+    recorded = journaled.get(_REQUEST_FIELDS) if isinstance(journaled, Mapping) else None
+    if not isinstance(recorded, Mapping):
+        return "the request"
+    drifted = sorted(
+        field for field in {*recorded, *fields} if recorded.get(field) != fields.get(field)
+    )
+    return ", ".join(drifted) if drifted else "the request"
+
+
+def _same_plan(journaled: Any, planned: Mapping[str, Any]) -> bool:
+    """Whether a journaled plan is the same plan, including one journaled before field naming.
+
+    ``request_field_digests`` is derived from the body ``request_digest`` already covers, so a plan
+    journaled without it is held to exactly the evidence it does carry, and one that carries it is
+    compared whole. A deployment interrupted before this field existed stays resumable rather than
+    having a recoverable lost response turned into a refusal by an upgrade.
+    """
+
+    if not isinstance(journaled, Mapping):
+        return False
+    if _REQUEST_FIELDS in journaled:
+        return dict(journaled) == dict(planned)
+    return dict(journaled) == {
+        field: value for field, value in planned.items() if field != _REQUEST_FIELDS
+    }
+
+
+def _mutate(
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    client: StudioDeploymentClient,
+    *,
+    name: str,
+    operation: str,
+    body: Mapping[str, Any],
+    expected: set[int],
+    resource_id: UUID | None = None,
+    if_match: str | None = None,
+    requires_etag: bool = False,
+) -> Mapping[str, Any]:
+    operations = state["operations"]
+    resources = state["resources"]
+    request_digest = canonical.canonical_sha256(dict(body))
+    fields = _request_field_digests(body)
+    existing = resources.get(name)
+    if isinstance(existing, dict):
+        # A completed operation short-circuits to its journaled response, and the request this
+        # invocation rebuilt is discarded rather than sent. So a local input that moved since
+        # staging is not transmitted -- it is IGNORED, silently, and the operator is handed the
+        # result of the request they no longer have. The journal has recorded the digest of what
+        # was actually sent since v3 for exactly this comparison; until now nothing read it.
+        journaled = operations.get(name)
+        recorded = _journaled_request_digest(journaled)
+        if recorded is None:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID",
+                f"deployment operation {name} recorded a result without the request that "
+                "produced it",
+            )
+        if recorded != request_digest:
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISMATCH",
+                f"deployment operation {name} already ran, and "
+                f"{_drifted_request_fields(journaled, fields)} here no longer matches what it "
+                "sent; this run would keep the recorded result and ignore the change, so start a "
+                "new deployment for it",
+            )
+        return existing
+    idempotency_key = _idempotency(name, state["deployment_identity"])
+    operation_state = operations.get(name)
+    planned = {
+        "operation": operation,
+        "request_digest": request_digest,
+        _REQUEST_FIELDS: fields,
+        "idempotency_key": idempotency_key,
+        "status": "planned",
+    }
+    if operation_state is None:
+        operations[name] = planned
+        store.save(state)
+    elif not _same_plan(operation_state, planned):
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            f"deployment operation {name} changed after journaling: "
+            f"{_drifted_request_fields(operation_state, fields)} is not what was journaled",
+        )
+    response = client.call(
+        operation,
+        body,
+        idempotency_key=idempotency_key,
+        resource_id=resource_id,
+        if_match=if_match,
+    )
+    result = dict(_success(response, expected, "DEPLOY_STUDIO_MUTATION_FAILED"))
+    if requires_etag and response.etag is None:
+        # Refuse to journal this as completed. A later step conditions its write on this
+        # response's ETag and reads it back from the journal, never from the wire -- so
+        # recording "completed" without one produces a deployment that cannot be finished
+        # AND cannot be resumed, because a completed operation is never re-issued. The
+        # proposal it already created still holds the Recipe digest, so the Build cannot be
+        # retried either.
+        #
+        # Leaving the operation "planned" is what makes this recoverable: a resume re-sends
+        # it under the same idempotency key, and a server that has learned to return the
+        # ETag answers the replay with one. That is exactly how this was recovered when
+        # Studio omitted it (mostlyrightmd/mostlyright-studio#57).
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID",
+            f"Studio omitted the ETag after {name}, which the next step must write against; "
+            "nothing was journaled as complete, so rerunning with --resume will ask again",
+        )
+    resources[name] = result
+    if response.etag is not None:
+        state.setdefault("etags", {})[name] = response.etag
+    operations[name] = {**planned, "status": "completed"}
+    store.save(state)
+    return result
+
+
+def _upload_once(
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    client: StudioDeploymentClient,
+    *,
+    name: str,
+    session: Mapping[str, Any],
+    content: bytes,
+) -> str | None:
+    operations = state["operations"]
+    completed = operations.get(name, {})
+    status = completed.get("status")
+    content_digest = hashlib.sha256(content).hexdigest()
+    if status in {"completed", "reconciled"}:
+        # Both of these short-circuit an object Studio has already sealed, and neither one sends
+        # the bytes this invocation just read. Local source evidence that moved since staging is
+        # therefore ignored rather than uploaded, so it is compared against the digest the journal
+        # recorded when the transfer actually happened.
+        recorded = _journaled_request_digest(completed)
+        if recorded is None:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID",
+                f"source upload {name} recorded a result without the content it sent",
+            )
+        if recorded != content_digest:
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISMATCH",
+                f"source upload {name} already ran, and the content here no longer matches what "
+                "it sent; this run would keep the sealed object and ignore the change, so start a "
+                "new deployment for it",
+            )
+        if status == "reconciled":
+            return None
+        generation = completed.get("object_generation")
+        if not isinstance(generation, str) or _OBJECT_GENERATION.fullmatch(generation) is None:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID", f"source upload {name} has no object generation"
+            )
+        return generation
+    planned = {
+        "operation": "signed_upload",
+        "request_digest": content_digest,
+        "session_id": session.get("session_id"),
+        "status": "planned",
+    }
+    current = operations.get(name)
+    if current is None:
+        operations[name] = planned
+        store.save(state)
+    elif current != planned:
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH", f"source upload {name} changed after journaling"
+        )
+    try:
+        generation = client.upload(session, content)
+    except HostedDeployError as error:
+        if error.code != "DEPLOY_SOURCE_UPLOAD_FAILED":
+            raise
+        # A transfer can commit remotely while its response is lost. Leave the upload planned;
+        # finalization or the next idempotent replay will reconcile the exact sealed object.
+        return None
+    operations[name] = {**planned, "status": "completed", "object_generation": generation}
+    store.save(state)
+    return generation
+
+
+def _approval_receipt(
+    state: Mapping[str, Any], store: DeploymentStateStore, cloud_url: str
+) -> dict[str, Any]:
+    proposal = state["resources"]["proposal"]
+    return {
+        "schema_version": DEPLOYMENT_RECEIPT_SCHEMA,
+        "status": "deployment_approval_required",
+        "workspace_id": state["workspace_id"],
+        "recipe_proposal_id": proposal["recipe_proposal_id"],
+        "approval_request_id": state["resources"]["approval_request_id"],
+        "state": str(store.path),
+        "dashboard_url": (
+            f"{_service_url(cloud_url, 'Cloud URL', allow_loopback_http=False)}/dashboard/approvals"
+        ),
+        "next": (
+            "approve the exact Recipe in Cloud Approvals, then rerun this command with --resume"
+        ),
+    }
+
+
+def _activation_receipt(
+    state: Mapping[str, Any], store: DeploymentStateStore, cloud_url: str
+) -> dict[str, Any]:
+    activation = state["resources"]["activation"]
+    binding = state["resources"]["cloud_binding"]
+    table_id = _uuid_field(activation, "table_id")
+    run_id = _uuid_field(activation, "run_id")
+    return {
+        "schema_version": DEPLOYMENT_RECEIPT_SCHEMA,
+        "status": "dataset_activation_queued",
+        "workspace_id": state["workspace_id"],
+        "dataset_id": state["resources"]["dataset_id"],
+        "table_plan_id": state["resources"]["table_plan_id"],
+        "table_id": str(table_id),
+        "cloud_dataset_id": _required_text(binding, "cloud_dataset_id"),
+        "current_path": _required_text(binding, "current_path"),
+        "run_id": str(run_id),
+        # The reviewed schedule is the coordinate that says when this Dataset refreshes itself,
+        # and it is the one activation coordinate the receipt used to omit -- so the operator who
+        # just deployed had no way to read back the cadence Studio activated without reopening
+        # the journal. It is the exact object the activation body carried, held in ``state`` from
+        # the moment the deployment was initialized.
+        "schedule": dict(state["schedule"]),
+        "recipe_proposal_id": state["resources"]["proposal"]["recipe_proposal_id"],
+        "state": str(store.path),
+        "dashboard_url": (
+            f"{_service_url(cloud_url, 'Cloud URL', allow_loopback_http=False)}/dashboard/datasets"
+        ),
+        # The queued Run is not a released version, and this receipt is where somebody learns that
+        # for the first time. Its sibling above has always ended by naming the next command; this
+        # one ended at a dashboard URL, which is exactly the trip to Cloud the status command now
+        # removes.
+        "next": "run mr-data deploy-status RUN_DIR to follow the run this queued",
+    }
+
+
+def cloud_dashboard_url(cloud_url: str, page: str) -> str:
+    """The Cloud page an operator opens about this deployment, from one validated origin.
+
+    Every receipt that points somebody at Cloud goes through here, so the origin is checked the
+    same way each time and the three surfaces cannot drift into three spellings of one URL.
+    """
+
+    origin = _service_url(cloud_url, "Cloud URL", allow_loopback_http=False)
+    return f"{origin}/dashboard/workspace/{page}"
+
+
+def _bind_cloud_dataset(
+    request: DeploymentRequest,
+    state: dict[str, Any],
+    store: DeploymentStateStore,
+    *,
+    credentials: ResolvedCloudCredentials,
+    transport: TokenExchangeTransport | None,
+) -> Mapping[str, Any]:
+    _require_cli_credential(credentials)
+    resources = state["resources"]
+    activation = resources.get("activation")
+    if not isinstance(activation, dict):
+        raise HostedDeployError(
+            "DEPLOY_STATE_INVALID", "Cloud Dataset binding requires a completed activation"
+        )
+    body = {
+        "schema_version": CLOUD_TABLE_BINDING_SCHEMA_VERSION,
+        "studio_workspace_id": state["workspace_id"],
+        "studio_dataset_id": _required_text(resources, "dataset_id"),
+        "studio_table_id": str(_uuid_field(activation, "table_id")),
+        "table_recipe": {
+            "table_recipe_id": request.recipe_id,
+            "recipe_version": request.recipe_version,
+            "recipe_digest": request.recipe_digest,
+        },
+    }
+    request_digest = canonical.canonical_sha256(body)
+    fields = _request_field_digests(body)
+    operations = state["operations"]
+    existing = resources.get("cloud_binding")
+    if isinstance(existing, dict):
+        # The binding Cloud already persisted is returned without contacting Cloud again, so a
+        # rebuilt body that moved is ignored rather than sent. The body is built before this
+        # short-circuit for that comparison alone.
+        journaled = operations.get("cloud_binding")
+        recorded = _journaled_request_digest(journaled)
+        if recorded is None:
+            raise HostedDeployError(
+                "DEPLOY_STATE_INVALID",
+                "the Cloud Dataset binding recorded a result without the request that produced it",
+            )
+        if recorded != request_digest:
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISMATCH",
+                "the Cloud Dataset binding already ran, and "
+                f"{_drifted_request_fields(journaled, fields)} here no longer matches what it "
+                "sent; this run would keep the recorded binding and ignore the change, so start a "
+                "new deployment for it",
+            )
+        return existing
+    planned = {
+        "operation": "bind_cloud_dataset",
+        "request_digest": request_digest,
+        _REQUEST_FIELDS: fields,
+        "status": "planned",
+    }
+    current = operations.get("cloud_binding")
+    if current is None:
+        operations["cloud_binding"] = planned
+        store.save(state)
+    elif not _same_plan(current, planned):
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "the Cloud Dataset binding changed after journaling: "
+            f"{_drifted_request_fields(current, fields)} is not what was journaled",
+        )
+    selected = transport or UrlLibTokenExchangeTransport()
+    cloud_url = _service_url(credentials.cloud_url, "Cloud URL", allow_loopback_http=False)
+    try:
+        status, raw, _response_headers = selected.request(
+            "POST",
+            f"{cloud_url}{CLOUD_DATASET_BINDINGS_PATH}",
+            {
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": credentials.raw_key,
+                "Idempotency-Key": _idempotency(
+                    "cloud-table-binding", state["deployment_identity"]
+                ),
+            },
+            canonical.canonical_json_bytes(body),
+            MAX_BINDING_RESPONSE_BYTES,
+        )
+    except HostedDeployError:
+        raise
+    except Exception as error:
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_FAILED",
+            "the Cloud Dataset binding could not be reached; rerun with --resume",
+        ) from error
+    try:
+        parsed = canonical.parse_json(raw)
+    except canonical.CanonicalJSONError:
+        parsed = None
+    if status == 401:
+        raise HostedDeployError(
+            "DEPLOY_AUTHENTICATION_FAILED", "the selected CLI credential was rejected"
+        )
+    if status == 402:
+        raise HostedDeployError(
+            "DEPLOY_SUBSCRIPTION_REQUIRED", "this workspace has no hosted deployment access"
+        )
+    if status == 409:
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_CONFLICT",
+            "Cloud could not bind the exact accepted Studio activation",
+        )
+    if status in {429, 503}:
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_UNAVAILABLE",
+            "Cloud could not finish Dataset binding; rerun with --resume",
+        )
+    if status != 200 or not isinstance(parsed, dict):
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_FAILED",
+            f"the Cloud Dataset binding failed (HTTP {status})",
+        )
+    if set(parsed) != {
+        "schema_version",
+        "cloud_dataset_id",
+        "cloud_table_id",
+        "studio_dataset_id",
+        "studio_table_id",
+        "current_path",
+    }:
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_FAILED", "Cloud returned an invalid Dataset binding"
+        )
+    if parsed["schema_version"] != CLOUD_TABLE_BINDING_SCHEMA_VERSION:
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_FAILED", "Cloud returned an invalid binding schema"
+        )
+    cloud_dataset_id = _uuid(_required_text(parsed, "cloud_dataset_id"), "cloud_dataset_id")
+    cloud_table_id = _uuid(_required_text(parsed, "cloud_table_id"), "cloud_table_id")
+    studio_dataset_id = _uuid(_required_text(parsed, "studio_dataset_id"), "studio_dataset_id")
+    studio_table_id = _uuid(_required_text(parsed, "studio_table_id"), "studio_table_id")
+    expected_studio_dataset_id = _uuid(_required_text(resources, "dataset_id"), "dataset_id")
+    expected_studio_table_id = _uuid_field(activation, "table_id")
+    current_path = _required_text(parsed, "current_path")
+    if (
+        studio_dataset_id != expected_studio_dataset_id
+        or studio_table_id != expected_studio_table_id
+        or current_path != f"/api/v2/tables/{cloud_table_id}/current"
+    ):
+        raise HostedDeployError(
+            "DEPLOY_CLOUD_BINDING_FAILED", "Cloud returned a mismatched Dataset binding"
+        )
+    result = {
+        "cloud_dataset_id": str(cloud_dataset_id),
+        "cloud_table_id": str(cloud_table_id),
+        "studio_dataset_id": str(studio_dataset_id),
+        "studio_table_id": str(studio_table_id),
+        "current_path": current_path,
+    }
+    resources["cloud_binding"] = result
+    operations["cloud_binding"] = {**planned, "status": "completed"}
+    store.save(state)
+    return result
+
+
+def _deployment_predecessor(
+    request: DeploymentRequest, previous_run_dir: Path | None
+) -> str | None:
+    """Settle which live Dataset this deployment updates, before it writes or sends anything of
+    its own.
+
+    ``mr-data deploy`` has one predecessor, not two. ``--previous-run-dir`` names the run directory
+    whose deployment published the Dataset this version updates, and the same directory is what
+    :func:`recipe.verify_recipe_candidate` authenticates the version chain out of. The two layers
+    ask one question because :func:`deploy.build_deployment_request` refuses both shapes where they
+    could differ: a Recipe execution whose mode is not ``initial`` must name its predecessor, and
+    one whose mode is ``initial`` must not. So by the time a request reaches here, "a predecessor
+    was named" and "this Build follows a sealed one" are the same fact, and that -- not the Recipe
+    version -- is what :func:`_prepare_and_request_approval` branches on. A refresh of an unchanged
+    Recipe is a successor whose Recipe version has not moved.
+
+    What the Recipe version still decides is the one shape it alone can see: a successor Recipe
+    exists because a Dataset it follows exists, so deploying one that names no predecessor at all
+    would found a second Dataset and strand the first. That is refused here rather than at the
+    Studio call, so it leaves no journal behind -- ``DEPLOY_PREDECESSOR_REQUIRED`` names a flag,
+    and the rerun that supplies it has to be able to stage cleanly instead of meeting the identity
+    gate holding the journal of the run that refused.
+
+    Returns:
+        The predecessor coordinate this deployment's identity is computed from, or None when there
+        is no predecessor.
+    """
+
+    if previous_run_dir is None:
+        if request.recipe_version > 1:
+            # `_previous_deployment_resources` owns this sentence; calling it with nothing is what
+            # moves its refusal ahead of the journal this run would otherwise have written.
+            _previous_deployment_resources(previous_run_dir)
+        return None
+    # Resolved, because a resume is run from whatever directory the operator happens to be standing
+    # in and the predecessor it names is the same one either way.
+    coordinate = str(Path(previous_run_dir).resolve())
+    # Reads the predecessor's own activation receipt, so one that never finished activating is
+    # refused here rather than at the Studio call. This does open a journal store on the
+    # predecessor, which creates its `evidence/deployment` directory and takes a lock there; what
+    # is not yet written is anything belonging to the deployment being started.
+    _previous_deployment_resources(previous_run_dir)
+    return coordinate
+
+
+def _previous_deployment_resources(previous_run_dir: Path | None) -> Mapping[str, str]:
+    if previous_run_dir is None:
+        raise HostedDeployError(
+            "DEPLOY_PREDECESSOR_REQUIRED", "a successor deployment needs --previous-run-dir"
+        )
+    store = FileDeploymentStateStore(previous_run_dir)
+    try:
+        state = store.load()
+    finally:
+        store.close()
+    resources = state.get("resources")
+    activation = resources.get("activation") if isinstance(resources, dict) else None
+    if not isinstance(resources, dict) or not isinstance(activation, dict):
+        raise HostedDeployError(
+            "DEPLOY_PREDECESSOR_INVALID", "the previous Build has no completed activation receipt"
+        )
+    return {
+        "dataset_id": _required_text(resources, "dataset_id"),
+        "table_plan_id": _required_text(resources, "table_plan_id"),
+        "table_id": str(_uuid_field(activation, "table_id")),
+    }
+
+
+def _source_locator(
+    source: Mapping[str, Any], proposal: Mapping[str, Any], bundle: Mapping[str, Any]
+) -> dict[str, Any]:
+    if bundle["authority_kind"] == "sealed_artifact":
+        return {
+            "kind": "artifact",
+            "display_locator": "urn:sha256:" + bundle["source_data"]["content_sha256"],
+        }
+    if source["adapter_id"] == "public.https":
+        return {
+            "kind": "https_url",
+            "display_locator": source["query_template"]["url"],
+            "connector_contract_version": source["adapter_version"],
+        }
+    return {
+        "kind": "sdk_connector",
+        "display_locator": proposal["locator"],
+        "connector_contract_version": source["adapter_version"],
+    }
+
+
+def _studio_feasibility(value: Mapping[str, Any]) -> dict[str, Any]:
+    mapping = {
+        "sufficient_evidence": "SUFFICIENT_EVIDENCE",
+        "limited_coverage": "LIMITED_COVERAGE",
+        "unacceptable_delay": "UNACCEPTABLE_DELAY",
+        "rights_unclear": "RIGHTS_UNCLEAR",
+        "no_reliable_source": "NO_RELIABLE_SOURCE",
+        "target_not_observable": "TARGET_NOT_OBSERVABLE",
+    }
+    return {
+        "decision": value["decision"],
+        "reason_codes": [mapping[item] for item in value["reason_codes"]],
+        "narrative": value["narrative"],
+    }
+
+
+def _default_backfill_policy(time_range: Mapping[str, Any]) -> dict[str, Any]:
+    start = _timestamp(_required_text(time_range, "start_inclusive"), "start_inclusive")
+    end = _timestamp(_required_text(time_range, "end_exclusive"), "end_exclusive")
+    seconds = int((end - start).total_seconds())
+    if seconds < 1:
+        raise HostedDeployError("DEPLOY_REQUEST_INVALID", "Recipe time range is empty")
+    return {
+        "schema_version": "local-backfill-policy.v1",
+        "coverage_envelope": dict(time_range),
+        "max_window_seconds": seconds,
+        "overlap_policy": "disallow_released_coverage",
+        "partition_scope": {"fields": [], "allowed_values": {}, "max_partitions_per_run": 1},
+    }
+
+
+#: Every operator-visible input the deployment identity is computed from, and what to call it when
+#: it moves. A resume is by definition something a person comes back to hours later, after an
+#: approval, with the original command long gone from their scrollback, so getting one of these
+#: wrong is the expected case rather than the exceptional one.
+#:
+#: Two of them are not arguments at all. The Cloud URL comes from the environment, and the review
+#: authority comes from whether this shell is inside a coordinator review session -- which is why a
+#: refusal that names the review authority must not offer an argument list as the fix.
+_IDENTITY_INPUT_LABELS: dict[str, str] = {
+    "dataset_name": "--dataset-name",
+    "cron": "--cron",
+    "previous_run_dir": "--previous-run-dir",
+    "max_runs_per_month": "--max-runs-per-month",
+    "max_concurrent_runs": "--max-concurrent-runs",
+    "max_monthly_cost_units": "--max-monthly-cost-units",
+    "recipe_id": "the Recipe id",
+    "recipe_version": "the Recipe version",
+    "recipe_digest": "the Recipe",
+    "candidate_digest": "the reviewed Build",
+    "cloud_url": "the Cloud URL",
+    "workspace_id": "the workspace",
+    "review_authority": "the review authority",
+}
+
+#: The journal key under which a staged deployment records the inputs above.
+_IDENTITY_INPUTS = "identity_inputs"
+
+#: Which authority the staged request carried. A request carries the signed reviewed-Build binding
+#: or it carries none, and which one it is moves the request digest; nothing on the command line
+#: says so.
+_REVIEW_SESSION = "review_session"
+_UNATTESTED = "unattested"
+
+#: What can still move a request digest once every named input matches. None of it is an argument,
+#: which is what makes listing it honest rather than unhelpful: it tells an operator that no rerun
+#: of the same command will converge.
+_UNNAMED_REQUEST_INPUTS = (
+    "the sealed Build evidence the request carries",
+    "the release of this command that staged it",
+)
+
+
+def _identity_inputs(
+    request: DeploymentRequest,
+    *,
+    workspace_id: UUID,
+    cloud_url: str,
+    cron: str,
+    max_concurrent_runs: int,
+    previous_run_dir: str | None,
+) -> dict[str, Any]:
+    """The named inputs behind one deployment identity, in the shape the journal records them.
+
+    ``previous_run_dir`` is recorded on every deployment, including the initial ones where it is
+    None. The identity digest carries it only when there is one -- an absent key there would move
+    every identity staged before this release -- but the journal has no such constraint, and
+    recording the absence is what lets a resume that adds a predecessor be named as the input that
+    moved rather than listed as one of the inputs the journal could not resolve.
+    """
+
+    return {
+        "candidate_digest": request.candidate_digest,
+        "cloud_url": cloud_url,
+        "cron": cron,
+        "table_name": request.dataset_name,
+        "max_concurrent_runs": max_concurrent_runs,
+        "max_monthly_cost_units": request.caps.max_monthly_cost_units,
+        "max_runs_per_month": request.caps.max_runs_per_month,
+        "previous_run_dir": previous_run_dir,
+        "recipe_digest": request.recipe_digest,
+        "table_recipe_id": request.recipe_id,
+        "recipe_version": request.recipe_version,
+        "review_authority": (
+            _REVIEW_SESSION if request.review_decision_digest is not None else _UNATTESTED
+        ),
+        "workspace_id": str(workspace_id),
+    }
+
+
+def _journaled_identity_inputs(state: Mapping[str, Any]) -> dict[str, Any]:
+    """What this journal can say about the inputs it was staged with.
+
+    A journal written since staging began recording them answers for every input. An older one
+    answers only for what it happened to need: the schedule it sent to Studio, and -- once Studio
+    held a Recipe proposal -- the Dataset name inside the activation intent. Whatever it cannot
+    answer is left out here, so a refusal lists it as a possibility rather than saying it matched.
+    """
+
+    recorded = state.get(_IDENTITY_INPUTS)
+    if isinstance(recorded, Mapping):
+        return {name: recorded[name] for name in _IDENTITY_INPUT_LABELS if name in recorded}
+    inputs: dict[str, Any] = {}
+    schedule = state.get("schedule")
+    if isinstance(schedule, Mapping):
+        for name in ("cron", "max_concurrent_runs"):
+            if name in schedule:
+                inputs[name] = schedule[name]
+    resources = state.get("resources")
+    proposal = resources.get("proposal") if isinstance(resources, Mapping) else None
+    intent = proposal.get("activation_intent") if isinstance(proposal, Mapping) else None
+    if isinstance(intent, Mapping) and "dataset_name" in intent:
+        inputs["table_name"] = intent["table_name"]
+    return inputs
+
+
+def _drifted_identity_inputs(journaled: Mapping[str, Any], inputs: Mapping[str, Any]) -> list[str]:
+    """The named inputs this journal can prove moved, in a stable order."""
+
+    return sorted(name for name, value in journaled.items() if inputs.get(name) != value)
+
+
+def _identity_drift_sentence(
+    journaled: Mapping[str, Any], inputs: Mapping[str, Any], names: list[str]
+) -> str:
+    """Each differing input, as the value it was staged with and the value it has here."""
+
+    return "; ".join(
+        f"{_IDENTITY_INPUT_LABELS[name]} was staged as {journaled[name]} and is "
+        f"{inputs.get(name)} here"
+        for name in names
+    )
+
+
+def _validate_state(
+    state: Mapping[str, Any],
+    identity: str,
+    workspace_id: UUID,
+    *,
+    inputs: Mapping[str, Any],
+    request_digest: str,
+) -> None:
+    """Hold one journal to one exact handoff, and say which input moved when it does not.
+
+    The identity comparison is unchanged: one digest over the request, the workspace, the Cloud
+    URL, the schedule and the concurrency cap, and it either names this handoff or it does not.
+    What changes is what a person is told when it does not. The journal is holding the answer --
+    it recorded the inputs it was staged with -- and until now the refusal said only that the two
+    disagreed, which is the one thing the operator already knew.
+    """
+
+    if (
+        state.get("schema_version") != DEPLOYMENT_STATE_SCHEMA
+        or not isinstance(state.get("operations"), dict)
+        or not isinstance(state.get("resources"), dict)
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH", "the deployment journal belongs to another exact handoff"
+        )
+    staged_workspace = state.get("workspace_id")
+    if staged_workspace != str(workspace_id):
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            f"this deployment journal was staged in workspace {staged_workspace} and this run is "
+            f"authenticated to workspace {workspace_id}; sign in to the one it was staged in, or "
+            "start a new deployment",
+        )
+    if state.get("deployment_identity") == identity:
+        return
+    journaled = _journaled_identity_inputs(state)
+    drifted = _drifted_identity_inputs(journaled, inputs)
+    if "review_authority" in drifted:
+        # The sixth input, and the only one that is invisible from the command line: `mr-data
+        # deploy` reads the review authority off the ambient shell, so a session-staged deployment
+        # resumed from an ordinary terminal rebuilds an unattested request, moves the digest, and
+        # lands here with no differing flag to name. Printing an argument list for this one would
+        # send an operator to retype a command that already matches.
+        if journaled["review_authority"] == _REVIEW_SESSION:
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISMATCH",
+                "this deployment was staged inside a coordinator review session and this run has "
+                "none, so it rebuilt a different request; no argument list can bridge that -- "
+                "resume it from a review session, or start a new deployment",
+            )
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "this deployment was staged outside a coordinator review session and this run is "
+            "inside one, so it rebuilt a different request; no argument list can bridge that -- "
+            "resume it outside the session, or start a new deployment",
+        )
+    if drifted:
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "this deployment journal was staged with different inputs: "
+            f"{_identity_drift_sentence(journaled, inputs, drifted)}; rerun it with the values it "
+            "was staged with, or start a new deployment",
+        )
+    if state.get("request_digest") != request_digest:
+        candidates = [
+            *sorted(
+                _IDENTITY_INPUT_LABELS[name]
+                for name in _IDENTITY_INPUT_LABELS
+                if name not in journaled and name != "workspace_id"
+            ),
+            *_UNNAMED_REQUEST_INPUTS,
+        ]
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "this deployment journal was staged from a different request, and every input it "
+            f"records still matches, so what moved is one of: {', '.join(candidates)} -- rerun it "
+            "the way it was staged, or start a new deployment",
+        )
+    raise HostedDeployError(
+        "DEPLOY_STATE_MISMATCH", "the deployment journal belongs to another exact handoff"
+    )
+
+
+def _refuse_legacy_approval_journal(state: Mapping[str, Any]) -> None:
+    """Refuse every old human-gate pause rather than inventing a direct confirmation.
+
+    The direct Editor flow never writes ``approval_required``. Even an old journal that happens to
+    carry a complete approval-request response and ETag has no journaled Editor confirmation, so
+    that status alone is sufficient to identify a handoff that cannot safely cross into activation.
+    """
+
+    if state.get("status") != "approval_required":
+        return
+    raise HostedDeployError(
+        "DEPLOY_LEGACY_APPROVAL_JOURNAL",
+        "this deployment journal was paused by the former human-approval flow and has no "
+        "journaled Editor confirmation; it cannot be activated safely, so start a new deployment "
+        "from a fresh verified Build directory",
+    )
+
+
+def _resource_etag(state: Mapping[str, Any], name: str) -> str:
+    value = state.get("etags", {}).get(name) if isinstance(state.get("etags"), dict) else None
+    if not isinstance(value, str) or not value.startswith('"') or not value.endswith('"'):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID", f"Studio omitted the ETag after {name}"
+        )
+    return value
+
+
+def _generated_response(response: Any) -> StudioResponse:
+    parsed = getattr(response, "parsed", None)
+    body = parsed.to_dict() if parsed is not None and hasattr(parsed, "to_dict") else {}
+    headers = getattr(response, "headers", {})
+    return StudioResponse(
+        status_code=int(response.status_code),
+        body=body,
+        etag=headers.get("ETag") if hasattr(headers, "get") else None,
+    )
+
+
+def _success(response: StudioResponse, expected: set[int], code: str) -> Mapping[str, Any]:
+    if response.status_code not in expected:
+        api_code = response.body.get("code")
+        suffix = f" ({api_code})" if isinstance(api_code, str) else ""
+        raise HostedDeployError(
+            code, f"Studio refused the operation (HTTP {response.status_code}){suffix}"
+        )
+    return response.body
+
+
+def _etag(response: StudioResponse, operation: str) -> str:
+    value = response.etag
+    if not isinstance(value, str) or not value.startswith('"') or not value.endswith('"'):
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID", f"Studio omitted the ETag after {operation}"
+        )
+    return value
+
+
+def _idempotency(operation: str, identity: str) -> str:
+    digest = hashlib.sha256(f"{operation}:{identity}".encode()).hexdigest()
+    return f"mr-data.deploy.v3:{digest}"
+
+
+def _same(value: Mapping[str, Any], field: str, expected: Any) -> None:
+    if value.get(field) != expected:
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH", f"{field} differs from the authenticated deployment scope"
+        )
+
+
+def _required_text(value: Mapping[str, Any], field: str) -> str:
+    selected = value.get(field)
+    if not isinstance(selected, str) or not selected:
+        raise HostedDeployError("DEPLOY_RESPONSE_INVALID", f"the response omitted {field}")
+    return selected
+
+
+def _required_uuid(value: UUID | None, field: str) -> UUID:
+    if value is None:
+        raise HostedDeployError("DEPLOY_REQUEST_INVALID", f"{field} is missing")
+    return value
+
+
+def _uuid(value: Any, field: str) -> UUID:
+    try:
+        parsed = UUID(value) if isinstance(value, str) else None
+    except ValueError:
+        parsed = None
+    if parsed is None or str(parsed) != value:
+        raise HostedDeployError("DEPLOY_RESPONSE_INVALID", f"{field} is not a canonical UUID")
+    return parsed
+
+
+def _uuid_field(value: Mapping[str, Any], field: str) -> UUID:
+    try:
+        return _uuid(value.get(field), field)
+    except HostedDeployError as error:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID", f"Studio omitted a valid {field}"
+        ) from error
+
+
+def _positive_int_field(value: Mapping[str, Any], field: str) -> int:
+    selected = value.get(field)
+    if isinstance(selected, bool) or not isinstance(selected, int) or selected < 1:
+        raise HostedDeployError(
+            "DEPLOY_STUDIO_RESPONSE_INVALID", f"Studio omitted a positive {field}"
+        )
+    return selected
+
+
+def _timestamp(value: str, field: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as error:
+        raise HostedDeployError("DEPLOY_RESPONSE_INVALID", f"{field} is not a timestamp") from error
+    if parsed.tzinfo is None or parsed.utcoffset() != UTC.utcoffset(parsed):
+        raise HostedDeployError("DEPLOY_RESPONSE_INVALID", f"{field} is not UTC")
+    return parsed
+
+
+def _deployment_options(dataset_name: Any, cron: Any, maximum: Any) -> None:
+    if (
+        not isinstance(dataset_name, str)
+        or not 1 <= len(dataset_name) <= 200
+        or dataset_name.strip() != dataset_name
+        or not dataset_name
+    ):
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID", "dataset name must be 1-200 trimmed nonblank characters"
+        )
+    if (
+        not isinstance(cron, str)
+        or not 9 <= len(cron) <= 100
+        or cron.strip() != cron
+        or len(cron.split()) != 5
+        or "\n" in cron
+        or "\r" in cron
+    ):
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID", "cron must be one satisfiable five-field UTC expression"
+        )
+    try:
+        croniter(cron, datetime(2000, 1, 1, tzinfo=UTC)).get_next(datetime)
+    except (CroniterBadCronError, CroniterBadDateError, ValueError) as error:
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID", "cron must be one satisfiable five-field UTC expression"
+        ) from error
+    if isinstance(maximum, bool) or not isinstance(maximum, int) or not 1 <= maximum <= 10:
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID", "max concurrent runs must be between 1 and 10"
+        )
+
+
+def _service_url(value: str, label: str, *, allow_loopback_http: bool) -> str:
+    if not isinstance(value, str) or not 1 <= len(value) <= 2048 or value.endswith("/"):
+        raise HostedDeployError("DEPLOY_CONFIG_INVALID", f"{label} is not a usable origin")
+    parsed = urlsplit(value)
+    loopback = False
+    if parsed.hostname:
+        try:
+            loopback = ipaddress.ip_address(parsed.hostname).is_loopback
+        except ValueError:
+            loopback = parsed.hostname == "localhost"
+    if (
+        parsed.scheme not in ({"https", "http"} if allow_loopback_http else {"https"})
+        or (parsed.scheme == "http" and not loopback)
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+        or parsed.path not in {"", "/"}
+        or parsed.query
+    ):
+        raise HostedDeployError(
+            "DEPLOY_CONFIG_INVALID",
+            f"{label} must be an HTTPS origin without user information, path, query, or fragment",
+        )
+    return value
+
+
+def _require_cli_credential(credentials: ResolvedCloudCredentials) -> None:
+    if _CLI_KEY.fullmatch(credentials.raw_key) is None:
+        raise HostedDeployError(
+            "DEPLOY_AUTHENTICATION_FAILED",
+            "managed deployment requires an mr_cli_ credential; "
+            "a live data key has read-only scope",
+        )
+
+
+def _transfer_url(url: str, base_url: str) -> str:
+    parsed = urlsplit(url)
+    base = urlsplit(base_url)
+    if (
+        parsed.scheme not in {"https", "http"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+    ):
+        raise HostedDeployError("DEPLOY_SIGNED_SESSION_INVALID", "signed upload URL is invalid")
+    if parsed.scheme == "http" and (
+        base.scheme != "http" or parsed.hostname != base.hostname or parsed.port != base.port
+    ):
+        raise HostedDeployError(
+            "DEPLOY_SIGNED_SESSION_INVALID",
+            "insecure signed upload URL differs from the local Studio origin",
+        )
+    return url
+
+
+def _signed_headers(session: Mapping[str, Any], *, size: int) -> dict[str, str]:
+    result: dict[str, str] = {}
+    required = session.get("required_headers")
+    if not isinstance(required, list):
+        raise HostedDeployError("DEPLOY_SIGNED_SESSION_INVALID", "signed upload headers are absent")
+    for item in required:
+        if not isinstance(item, dict):
+            raise HostedDeployError(
+                "DEPLOY_SIGNED_SESSION_INVALID", "signed upload header is invalid"
+            )
+        name = item.get("name")
+        value = item.get("value")
+        if (
+            not isinstance(name, str)
+            or not isinstance(value, str)
+            or name.lower() in {"authorization", "cookie", "host", "proxy-authorization"}
+            or re.fullmatch(r"[A-Za-z0-9-]{1,128}", name) is None
+            or "\r" in value
+            or "\n" in value
+            or name.lower() in result
+        ):
+            raise HostedDeployError(
+                "DEPLOY_SIGNED_SESSION_INVALID", "signed upload header is unsafe"
+            )
+        result[name.lower()] = value
+    media_type = _required_text(session, "media_type")
+    if result.get("content-type", media_type) != media_type:
+        raise HostedDeployError(
+            "DEPLOY_SIGNED_SESSION_INVALID", "signed upload content type differs"
+        )
+    result["content-type"] = media_type
+    result["content-length"] = str(size)
+    return result
+
+
+def _file_identity(value: os.stat_result) -> tuple[int, int, int, int, int, int, int]:
+    return (
+        value.st_dev,
+        value.st_ino,
+        value.st_mode,
+        value.st_nlink,
+        value.st_size,
+        value.st_mtime_ns,
+        value.st_ctime_ns,
+    )
+
+
+__all__ = [
+    "DEPLOYMENT_RECEIPT_SCHEMA",
+    "DEPLOYMENT_STATE_SCHEMA",
+    "FileDeploymentStateStore",
+    "GeneratedStudioDeploymentClient",
+    "HostedDeployError",
+    "StudioDeploymentClient",
+    "StudioResponse",
+    "StudioToken",
+    "TokenExchangeTransport",
+    "build_editor_client",
+    "deploy_managed_dataset",
+    "exchange_studio_token",
+    "journaled_reviewed_build",
+]