mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/deploy.py

@@ -0,0 +1,924 @@
+"""Build a deployment request from a reviewed recipe and sealed build.
+
+A deployment request says WHAT should run live — which recipe, which sealed build of it, which
+target project, which caps, and how often. It is the seam between the terminal, where a human
+approves a recipe, and Studio, where the dataset keeps itself current.
+
+Three boundaries this module holds on purpose:
+
+* **It describes, it does not run.** Nothing here schedules, fetches, or refreshes. That is
+  why the request is a versioned, digestible artifact rather than a function call: the two sides
+  can be written, reviewed, and changed independently, and the digest says whether they are talking
+  about the same thing.
+* **It records caps, it does not enforce them.** A :class:`governors.CapPolicy` is a required
+  component of every request, never optional, so no live dataset can exist without a stated ceiling.
+  Turning that ceiling into a refused run happens at the hosted entrypoint, not here. No string this
+  module emits may claim a limit was applied.
+
+  A recorded cap is advisory and is not currently read. The admission check
+  (:func:`hosted_bootstrap.admission_ledger`) builds its ledger with no policy, so every workspace
+  is admitted against :class:`governors.CapPolicy` defaults whatever the request says. A request
+  tightened to ten runs a month does not make the eleventh run refuse. The gap is not closable from
+  this side: the worker job is shared by every workspace, so job-level configuration cannot carry a
+  per-workspace policy either. What would close it is a policy delivered per run in the validated
+  bootstrap response.
+* **It never touches a credential.** :func:`build_deployment_request` accepts no key argument at
+  all, so a request cannot carry one. That is a property of the signature, not of a filter.
+
+Refusals are quiet and typed. Every path that cannot produce a deployment plan raises
+:class:`DeployRefused` with named reasons, or returns a refusing :class:`DeployPlanResult` — so a
+caller has exactly one thing to catch and exactly one shape to render.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness import (
+    canonical,
+    deploy_target,
+    deployment_evidence,
+    package_version,
+    pipeline,
+    recipe,
+    review,
+)
+from mostlyright.data_harness.governors import CapPolicy
+from mostlyright.data_harness.pipeline import canonical_json_line_bytes
+from mostlyright.data_harness.signing import (
+    SignerProviderError,
+    TrustedReviewAuthorityProvider,
+    resolve_review_authority,
+)
+
+#: The wire name of the artifact this module produces, in the convention used by
+#: ``hosted_bootstrap.WORKER_BOOTSTRAP_REQUEST_VERSION``: one product-scoped name and one integer
+#: version, bumped whenever the fields change meaning.
+#:
+#: v5 is v4 with two fields that may now be absent, and it is a new integer rather than a widened
+#: v4 because a reader of v4 was entitled to assume both were always there: a request built for a
+#: dataset the caller publishes itself carries no reviewed-Build binding under
+#: ``bootstrap_evidence`` and no ``review_decision_digest``. See
+#: :func:`build_deployment_request` for which of the three authorities produced a given request.
+DEPLOYMENT_REQUEST_SCHEMA = "mostlyright-deployment-request.v6"
+
+#: The wire name of what the command line renders, in the ``mr-data-*.v1`` style every other
+#: command already emits.
+DEPLOY_PLAN_RESULT_SCHEMA = "mr-data-deploy-plan.v6"
+# Compatibility names for library callers while the truthful command name moves to deploy-plan.
+GO_LIVE_RESULT_SCHEMA = DEPLOY_PLAN_RESULT_SCHEMA
+
+MAX_NAME_LENGTH = 128
+MAX_TEMPLATE_LENGTH = 256
+
+_DIGEST = re.compile(r"\A[0-9a-f]{64}\Z")
+
+# One plain line: no ASCII control/DEL and no Unicode boundary that ``str.splitlines`` treats as a
+# new rendered line. U+0085, U+2028 and U+2029 are outside the ASCII ranges but can otherwise
+# smuggle an attacker-authored line into terminal output or a log record.
+_PLAIN_LINE = re.compile(r"\A[^\x00-\x1f\x7f\x85\u2028\u2029]+\Z")
+
+
+class DeployRefused(RuntimeError):
+    """Go live was declined, with every reason named. Never a partial deployment.
+
+    A refusal is an expected outcome, not a defect: an unreviewed build, an ambiguous target, or a
+    refresh whose predecessor was not named are all things the operator can act on. Every refusing
+    path in this module raises this one type, so the command line has exactly one thing to catch.
+    """
+
+    def __init__(self, *reasons: str) -> None:
+        cleaned = tuple(reason.strip() for reason in reasons if reason and reason.strip())
+        if not cleaned:
+            raise ValueError("a refusal must name at least one reason")
+        self.reasons: tuple[str, ...] = cleaned
+        super().__init__("; ".join(cleaned))
+
+
+def _plain_name(value: Any, label: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise DeployRefused(f"the request does not name {label}")
+    text = value.strip()
+    if len(text) > MAX_NAME_LENGTH:
+        raise DeployRefused(f"{label} is longer than {MAX_NAME_LENGTH} characters")
+    if _PLAIN_LINE.fullmatch(text) is None:
+        raise DeployRefused(f"{label} must be one plain line of text")
+    return text
+
+
+@dataclass(frozen=True)
+class Cadence:
+    """How often the live dataset should look for new data, as a plain descriptor.
+
+    This module does not interpret either field. ``label`` is the operator's name for
+    the rhythm ("daily", "hourly", "each model run"); ``cycle_template`` is an optional template
+    string naming the cycle variable a source publishes on. This request records both as
+    uninterpreted descriptors.
+
+    ``FrozenRecipe.refresh_policy`` is different. That field holds integer drift
+    bounds (``min_row_count_percent``, ``max_row_count_percent``, ``allow_column_additions``); using
+    it as a schedule would put meaningless numbers in the request.
+    """
+
+    label: str
+    cycle_template: str | None = None
+
+    def __post_init__(self) -> None:
+        _plain_name(self.label, "a cadence")
+        if self.cycle_template is not None:
+            if not isinstance(self.cycle_template, str) or not self.cycle_template.strip():
+                raise DeployRefused("the cadence cycle template must be text, or absent")
+            if len(self.cycle_template) > MAX_TEMPLATE_LENGTH:
+                raise DeployRefused(
+                    f"the cadence cycle template is longer than {MAX_TEMPLATE_LENGTH} characters"
+                )
+            if _PLAIN_LINE.fullmatch(self.cycle_template) is None:
+                raise DeployRefused("the cadence cycle template must be one plain line of text")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the descriptor as plain data, uninterpreted."""
+
+        return {"label": self.label.strip(), "cycle_template": self.cycle_template}
+
+
+@dataclass(frozen=True)
+class DeploymentRequest:
+    """One reviewed recipe, one named target, one set of caps: what should run live.
+
+    The request carries the recipe's identity and the digest of the exact build that was reviewed —
+    never the recipe body. Two reasons: the body is large and already immutably stored under its
+    digest, and a request that repeated it could disagree with it. A digest cannot disagree with
+    what it names.
+
+    :meth:`digest` is a content digest over the whole request, so any alteration between building it
+    and acting on it is detectable by whoever acts on it.
+
+    ``review_decision_digest`` and ``bootstrap_evidence["reviewed_build"]`` are the two things a
+    request may not have. They are present together or absent together, and absent means what it
+    says: this deployment carries no external review attestation, and nothing signed it. Every
+    other field is present on every request, including on that one.
+    """
+
+    schema: str
+    recipe_id: str
+    recipe_version: int
+    recipe_digest: str
+    candidate_digest: str
+    review_decision_digest: str | None
+    acquisition_bundle_digest: str
+    execution_plan_digest: str
+    canonical_recipe_json: str
+    recipe_schema_version: str
+    bootstrap_evidence: dict[str, Any]
+    dataset_name: str
+    target: deploy_target.DeployTarget | None
+    caps: CapPolicy
+    cadence: Cadence
+
+    def __post_init__(self) -> None:
+        if self.schema != DEPLOYMENT_REQUEST_SCHEMA:
+            raise DeployRefused(f"a deployment request must be {DEPLOYMENT_REQUEST_SCHEMA}")
+        _plain_name(self.recipe_id, "a recipe")
+        _plain_name(self.dataset_name, "a live dataset")
+        if type(self.recipe_version) is not int or self.recipe_version < 1:
+            raise DeployRefused("the recipe version must be a whole number of at least 1")
+        for name in (
+            "recipe_digest",
+            "candidate_digest",
+            "acquisition_bundle_digest",
+            "execution_plan_digest",
+        ):
+            value = getattr(self, name)
+            if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+                raise DeployRefused(f"{name} must be a 64-character lowercase hex digest")
+        # The one digest that may be absent, and only absent: a deployment that carries no
+        # reviewed-Build binding has no signed review decision to name. Absent is written as
+        # ``None`` rather than as an empty or zero digest, because a reader that treats a
+        # 64-character field as present would read either of those as a decision that exists.
+        if self.review_decision_digest is not None and (
+            not isinstance(self.review_decision_digest, str)
+            or _DIGEST.fullmatch(self.review_decision_digest) is None
+        ):
+            raise DeployRefused(
+                "review_decision_digest must be a 64-character lowercase hex digest, or absent"
+            )
+        if self.target is not None and not isinstance(self.target, deploy_target.DeployTarget):
+            raise DeployRefused("the target must be one fully resolved go-live target, or absent")
+        if not isinstance(self.caps, CapPolicy):
+            raise DeployRefused("the caps must be a cap policy; a live dataset is never uncapped")
+        if not isinstance(self.cadence, Cadence):
+            raise DeployRefused("the cadence must be a cadence descriptor")
+        try:
+            canonical_recipe = canonical.parse_canonical_json(
+                self.canonical_recipe_json.encode("utf-8")
+            )
+        except canonical.CanonicalJSONError as error:
+            raise DeployRefused("canonical_recipe_json is not exact canonical JSON") from error
+        if (
+            not isinstance(canonical_recipe, dict)
+            or canonical_recipe.get("schema_version") != self.recipe_schema_version
+            or canonical_recipe.get("recipe_id") != self.recipe_id
+            or canonical_recipe.get("recipe_version") != self.recipe_version
+            or hashlib.sha256(self.canonical_recipe_json.encode("utf-8")).hexdigest()
+            != self.recipe_digest
+        ):
+            raise DeployRefused("canonical_recipe_json differs from the reviewed Recipe identity")
+        if not isinstance(self.bootstrap_evidence, dict):
+            raise DeployRefused("bootstrap_evidence must bind the exact reviewed Build")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the request as plain JSON-safe data. Carries digests and names, never a key."""
+
+        return {
+            "schema": self.schema,
+            "recipe_id": self.recipe_id,
+            "recipe_version": self.recipe_version,
+            "recipe_digest": self.recipe_digest,
+            "candidate_digest": self.candidate_digest,
+            "review_decision_digest": self.review_decision_digest,
+            "acquisition_bundle_digest": self.acquisition_bundle_digest,
+            "execution_plan_digest": self.execution_plan_digest,
+            "canonical_recipe_json": self.canonical_recipe_json,
+            "recipe_schema_version": self.recipe_schema_version,
+            "bootstrap_evidence": self.bootstrap_evidence,
+            "dataset_name": self.dataset_name,
+            "target": None if self.target is None else self.target.to_dict(),
+            "caps": {
+                "max_runs_per_month": self.caps.max_runs_per_month,
+                "max_concurrent_runs": self.caps.max_concurrent_runs,
+                "max_monthly_cost_units": self.caps.max_monthly_cost_units,
+            },
+            "cadence": self.cadence.to_dict(),
+        }
+
+    def digest(self) -> str:
+        """Return the canonical content digest of the whole request."""
+
+        return canonical.canonical_sha256(self.to_dict())
+
+    def to_summary_dict(self) -> dict[str, Any]:
+        """Return printable handoff coordinates without replaying executable Recipe bytes."""
+
+        bootstrap = self.bootstrap_evidence
+        return {
+            "schema": self.schema,
+            "recipe_id": self.recipe_id,
+            "recipe_version": self.recipe_version,
+            "recipe_digest": self.recipe_digest,
+            "recipe_schema_version": self.recipe_schema_version,
+            "candidate_digest": self.candidate_digest,
+            "review_decision_digest": self.review_decision_digest,
+            "acquisition_bundle_digest": self.acquisition_bundle_digest,
+            "execution_plan_digest": self.execution_plan_digest,
+            "bootstrap_table_digest": bootstrap["bootstrap_table_digest"],
+            "bootstrap_verification_digest": bootstrap["bootstrap_verification_digest"],
+            "artifact_manifest_digest": bootstrap["artifact_manifest_digest"],
+            "lineage_digest": bootstrap["lineage_digest"],
+            "dataset_name": self.dataset_name,
+            "target": None if self.target is None else self.target.to_dict(),
+            "caps": {
+                "max_runs_per_month": self.caps.max_runs_per_month,
+                "max_concurrent_runs": self.caps.max_concurrent_runs,
+                "max_monthly_cost_units": self.caps.max_monthly_cost_units,
+            },
+            "cadence": self.cadence.to_dict(),
+        }
+
+
+def _refusal_for(error: recipe.RecipeError, candidate_run_dir: Path) -> str:
+    """Turn a typed recipe failure into one plain sentence the operator can act on."""
+
+    if error.code == "RECIPE_PREDECESSOR" and error.path == "previous_run_dir":
+        # A different next action from every other refusal: the build is fine, the operator simply
+        # has not said which live version this one follows. Paraphrasing it as a verification
+        # failure would send them off to rebuild something that is not broken.
+        return (
+            f"the run directory {candidate_run_dir} holds a refresh of a dataset that is already "
+            "live, so the previous run directory — the version this one follows — has to be "
+            "named: pass it with --previous-run-dir [RECIPE_PREDECESSOR]"
+        )
+    # The failing part and the code travel; the verifier's own free-text detail does not. That
+    # detail is written in the engineering vocabulary ("is not a recipe candidate"), and these
+    # reasons are printed straight to an operator. The code is the precise, greppable handle, and
+    # `mr-data recipe-verify` on the same directory prints the full engineering text.
+    return (
+        f"the run directory {candidate_run_dir} does not hold a reviewed recipe build that can go "
+        f"live: {error.path} [{error.code}]"
+    )
+
+
+def _predecessor_forbidden_refusal(candidate_run_dir: Path) -> str:
+    """The other half of the predecessor rule, in the same voice as the half above.
+
+    :func:`recipe.execute_recipe` refuses a predecessor to an execution whose mode is ``initial``,
+    so a Build produced that way never read the predecessor's bytes and its version chain was never
+    authenticated against them. :func:`recipe.verify_recipe_candidate` enforces only the "is
+    required" direction and silently ignores a predecessor handed to an initial run -- which is
+    exactly how a Build with no authenticated predecessor could otherwise reach a deployment that
+    updates the predecessor's Dataset. This is that direction, stated where the request is built,
+    so both commands that build one get it and neither ignores what it was handed.
+    """
+
+    return (
+        f"the run directory {candidate_run_dir} holds an initial run, which starts a dataset "
+        "rather than following one, so there is no previous run directory for it to name: rerun "
+        "it without --previous-run-dir, or build the version that follows the live one as a "
+        "refresh of it [RECIPE_PREDECESSOR]"
+    )
+
+
+def _require_passing_local_checks(candidate_run_dir: Path) -> None:
+    """Refuse a Build whose own deterministic checks do not pass, naming every one that failed.
+
+    This is the gate on the path that carries no reviewed-Build binding. The checks are exactly the
+    ones :func:`ux.local_review.run_local_review` reports -- the seal replay, the recorded quality
+    checks under the names the Build recorded them with, the join row multiplier, lineage
+    completeness, and the per-source rights findings -- so what refuses a deployment here is the
+    same set of facts ``mr-data review --local`` prints, read from the same single verified
+    reading. Nothing is written, and no decision is sealed: this module cannot approve a Build and
+    does not claim to.
+
+    Two things this deliberately does not do. It does not stand in for the external two-reviewer
+    attestation, which is a judgement no machine makes. And it does not replace anything the caller
+    already ran: :func:`build_deployment_request` has verified the sealed Build, its recorded drift
+    report, and its acquisition evidence before it gets here.
+
+    The import is deferred rather than module-level. ``ux`` is the layer above this one and imports
+    freely from it; today nothing under ``ux`` imports this module back, and taking the dependency
+    at call time rather than at import time keeps that from being a thing a later edit has to know.
+    """
+
+    from mostlyright.data_harness.ux.local_review import run_local_review
+
+    try:
+        local = run_local_review(Path(candidate_run_dir))
+    except pipeline.BuildError as error:
+        # Unreachable through `build_deployment_request`, which has already read this directory as
+        # a sealed recipe Build. Translated rather than left to escape, because a caller of this
+        # module catches `DeployRefused` and nothing else.
+        raise DeployRefused(
+            f"the deterministic checks could not be run on {candidate_run_dir} [{error.finding_id}]"
+        ) from error
+    if local.passed:
+        return
+    failed = ", ".join(check.name for check in local.checks if not check.passed)
+    raise DeployRefused(
+        f"the build in {candidate_run_dir} did not pass its own deterministic checks, so it "
+        f"cannot go live: {failed} [LOCAL_CHECKS_FAILED]"
+    )
+
+
+#: The exact key set one reviewed-Build binding carries. A journal that offers anything else is
+#: not the document this function wrote, so it is refused by name rather than digested silently.
+_REVIEWED_BUILD_KEYS = frozenset(
+    {
+        "schema_version",
+        "candidate_digest",
+        "acquisition_bundle_digest",
+        "review_key_id",
+        "review_key_version",
+        "acquisition_bundle",
+        "decision",
+        "binding_digest",
+        "binding_signature",
+    }
+)
+
+
+def _adoptable_reviewed_build(
+    value: Mapping[str, Any],
+    candidate_run_dir: Path,
+) -> dict[str, Any]:
+    """Read one journaled reviewed-Build binding, or refuse it in the word that names the fault.
+
+    Only the shape is settled here. Whether the binding describes *this* run directory is settled
+    where the run directory's own recomputed digests are in hand, so a moved binding is refused as
+    a moved binding rather than as an unreadable one.
+    """
+
+    if not isinstance(value, Mapping) or set(value) != _REVIEWED_BUILD_KEYS:
+        raise DeployRefused(
+            f"the journaled reviewed Build for {candidate_run_dir} is not the agreed shape "
+            "[REVIEW_BINDING_UNREADABLE]"
+        )
+    decision = value["decision"]
+    if not isinstance(decision, Mapping):
+        raise DeployRefused(
+            f"the journaled reviewed Build for {candidate_run_dir} carries no signed decision "
+            "[REVIEW_BINDING_UNREADABLE]"
+        )
+    adopted = {
+        "candidate_digest": value["candidate_digest"],
+        "acquisition_bundle_digest": value["acquisition_bundle_digest"],
+        "review_key_id": value["review_key_id"],
+        "review_key_version": value["review_key_version"],
+        "decision": decision,
+        "decision_digest": decision.get("decision_digest"),
+        "binding_digest": value["binding_digest"],
+        "binding_signature": value["binding_signature"],
+    }
+    for name in (
+        "candidate_digest",
+        "acquisition_bundle_digest",
+        "decision_digest",
+        "binding_digest",
+    ):
+        if not isinstance(adopted[name], str) or _DIGEST.fullmatch(adopted[name]) is None:
+            raise DeployRefused(
+                f"the journaled reviewed Build for {candidate_run_dir} does not name a "
+                f"{name.replace('_', ' ')} [REVIEW_BINDING_UNREADABLE]"
+            )
+    if (
+        value["schema_version"] != "mostlyright-reviewed-build-bootstrap.v1"
+        or not isinstance(adopted["binding_signature"], str)
+        or not adopted["binding_signature"]
+        or decision.get("status") != "reviewed_candidate"
+    ):
+        raise DeployRefused(
+            f"the journaled reviewed Build for {candidate_run_dir} is not a signed reviewed "
+            "decision this Build can go live on [REVIEW_BINDING_UNREADABLE]"
+        )
+    return adopted
+
+
+def _adopted_binding_signature(
+    adopted: Mapping[str, Any],
+    binding_payload: Mapping[str, Any],
+    binding_digest: str,
+) -> str:
+    """Return the journaled signature, once every value it covers was recomputed and agreed.
+
+    The signature is the one thing that cannot be recomputed without the review session that made
+    it. Everything it was made over is recomputed here from the run directory, and the binding
+    digest is recomputed from those recomputed values, so a signature is carried across only when
+    it still stands over exactly what this Build says today.
+    """
+
+    covered = (
+        "candidate_digest",
+        "acquisition_bundle_digest",
+        "review_key_id",
+        "review_key_version",
+        "decision_digest",
+    )
+    if any(adopted[name] != binding_payload[name] for name in covered) or (
+        adopted["binding_digest"] != binding_digest
+    ):
+        raise DeployRefused(
+            "the journaled reviewed Build binds different evidence than this Build produced "
+            "[REVIEW_BINDING_MISMATCH]"
+        )
+    signature: str = adopted["binding_signature"]
+    return signature
+
+
+def build_deployment_request(
+    *,
+    candidate_run_dir: Path,
+    previous_run_dir: Path | None = None,
+    dataset_name: str,
+    target: deploy_target.DeployTarget | None,
+    caps: CapPolicy,
+    cadence: Cadence,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+    journaled_reviewed_build: Mapping[str, Any] | None = None,
+    require_reviewed_build: bool = True,
+) -> DeploymentRequest:
+    """Build the request that turns one verified, sealed run directory into a live dataset.
+
+    The input is a sealed run directory, not a Recipe file. Deployment uses work that
+    has already been produced and reviewed, so the thing being promoted must be the exact reviewed
+    artifact. The protected review decision and :func:`recipe.verify_recipe_candidate` are both
+    verified and must name the same candidate. Nothing that skipped review can reach this
+    function's return statement. The resulting request also names the exact signed decision and
+    the manifest-last acquisition-evidence bundle derived under ``candidate_run_dir``.
+
+    ``previous_run_dir`` is required whenever the build is a refresh or a backfill of a dataset that
+    is already live, because the predecessor is authenticated as part of verification, and it is
+    refused for an initial run, which follows nothing. Both execution modes are supported; a missing
+    predecessor is refused as a missing predecessor, not as a refusal of refresh mode, and a
+    predecessor handed to an initial run is refused rather than ignored.
+
+    Three authorities can stand behind the resulting request, and they are tried in that order.
+    A **journaled binding** is adopted when one is passed. Otherwise a **coordinator review
+    session**, when ``review_authority_provider`` is not None, verifies the installed two-reviewer
+    decision and signs a fresh binding — the path every Mostly Right-published dataset takes, and
+    the preferred one whenever a session exists. Otherwise, and only when the caller has explicitly
+    passed ``require_reviewed_build=False``, the request is built with **no reviewed-Build binding
+    at all**: no signature, no signing key, and no ``reviewed_build`` under ``bootstrap_evidence``.
+
+    That third path is for the customer publishing their own dataset. Nothing about the Build is
+    taken on trust there: the sealed Build is verified, its own recorded checks must have passed,
+    its acquisition evidence is closed and rebound, the whole reading is repeated under a verified
+    snapshot, and :func:`ux.local_review.run_local_review` reruns the deterministic checks —
+    exactly what ``mr-data review --local`` reports — and refuses if any one of them fails. What is
+    absent is the external two-reviewer attestation, not the verification of the Build. The
+    authority that admits such a proposal is the authenticated workspace human on the far side, and
+    the in-product approval remains the gate before anything activates.
+
+    ``require_reviewed_build`` defaults to True, so a caller that simply has no provider to pass
+    still gets the refusal it has always got. Dropping the binding is something a caller says, not
+    something it can fall into.
+
+    ``journaled_reviewed_build`` is the reviewed-Build binding an earlier, session-backed build of
+    this same request already minted and journaled — the one a paused hosted deployment records
+    before it stops for human approval. Passing it **adopts** that binding instead of minting a new
+    one, which is what lets ``mr-data deploy --resume`` run from an ordinary terminal long after the
+    coordinator's review session has ended. Adoption is not trust: every field the binding covers is
+    recomputed from ``candidate_run_dir`` here and must agree with it, the binding digest is
+    recomputed from those recomputed fields, and the resulting request is byte-identical to the one
+    the session-backed build produced — so the deployment identity the caller checks the journal
+    against still names this exact handoff. Only the signature itself is carried over, because the
+    key that made it lives in the session that has closed. Without it, nothing changes: the binding
+    is minted from ``review_authority_provider`` exactly as before.
+
+    This function accepts no key, token, or credential of any kind, which is why a request cannot
+    carry one.
+
+    Raises:
+        DeployRefused: when the run directory is not a reviewed recipe build, when its predecessor
+            was not named, when the build did not pass its own checks, when a deterministic local
+            check fails on a request that carries no reviewed-Build binding, when an adopted
+            binding is not the agreed shape or names another Build, or when any named value is not
+            the agreed shape.
+    """
+
+    try:
+        inspection, embedded = recipe.verify_recipe_candidate(
+            Path(candidate_run_dir),
+            # Always passed explicitly: this module's boundary is where the default lives, so the
+            # verifier's own required keyword is never silently omitted.
+            previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+        )
+    except recipe.RecipeError as error:
+        raise DeployRefused(_refusal_for(error, candidate_run_dir)) from error
+    except pipeline.BuildError as error:
+        if error.finding_id == "VALIDATION_POLICY_MISMATCH":
+            # Recipe verification is still entirely local at this point: no Studio request,
+            # approval, or deployment journal has happened. Preserve the verifier's two digests
+            # and exact re-export remedy instead of collapsing them to a finding id after the
+            # human would otherwise be asked to approve an unschedulable Recipe (#235).
+            raise DeployRefused(
+                "this deployment was refused before Studio staging, approval, or activation: "
+                f"{error} [{error.finding_id}]"
+            ) from error
+        # A directory with no sealed build in it at all is refused one layer below the recipe
+        # rules, so the greppable code here is the build gate's finding id rather than a recipe
+        # code. The operator's next action is the same either way: point at a reviewed build.
+        raise DeployRefused(
+            f"the run directory {candidate_run_dir} does not hold a reviewed recipe build that "
+            f"can go live [{error.finding_id}]"
+        ) from error
+    except (canonical.CanonicalJSONError, OSError) as error:
+        raise DeployRefused(
+            f"the run directory {candidate_run_dir} could not be read as a reviewed recipe build "
+            f"[{type(error).__name__}]"
+        ) from error
+
+    drift_report = embedded["drift_report"]
+    if drift_report.status != "passed":
+        # Release eligibility is what ``mr-data recipe-verify`` reports, and a version that failed
+        # its own checks is not a version to make self-updating.
+        codes = ", ".join(sorted({item.code for item in drift_report.findings})) or drift_report
+        raise DeployRefused(
+            f"the build in {candidate_run_dir} did not pass its own checks, so it cannot go live: "
+            f"{codes}"
+        )
+
+    if previous_run_dir is not None and embedded["execution"].mode == "initial":
+        raise DeployRefused(_predecessor_forbidden_refusal(candidate_run_dir))
+
+    unattested = (
+        journaled_reviewed_build is None
+        and review_authority_provider is None
+        and not require_reviewed_build
+    )
+    if unattested:
+        # The customer's own dataset: no review session, no trust anchor, no key, no signature.
+        # Everything above this line has already verified the sealed Build; the deterministic
+        # checks a person would read out of `mr-data review --local` are rerun here so the
+        # cheapest way to reach this branch is not also the way to skip them.
+        _require_passing_local_checks(Path(candidate_run_dir))
+        adopted = None
+        review_candidate_digest = None
+        review_decision_digest = None
+        decision = None
+    elif journaled_reviewed_build is None:
+        try:
+            review_result = review.verify_enrolled_review_decision(
+                Path(candidate_run_dir),
+                review_authority_provider=review_authority_provider,
+            )
+        except review.ReviewError as error:
+            code = error.code or "REVIEW_INVALID"
+            raise DeployRefused(
+                f"the run directory {candidate_run_dir} does not have an exact protected review "
+                f"that can authorize this Build [{code}]"
+            ) from error
+        except SignerProviderError as error:
+            raise DeployRefused(
+                f"the protected review authority for {candidate_run_dir} is unavailable "
+                "[REVIEW_AUTHORITY_UNAVAILABLE]"
+            ) from error
+        if review_result.status != "reviewed_candidate":
+            raise DeployRefused(
+                f"the signed review for {candidate_run_dir} requires fixes, so this Build cannot "
+                "go live [REVIEW_FIXES_REQUIRED]"
+            )
+        adopted = None
+        review_candidate_digest = review_result.candidate_digest
+        review_decision_digest = review_result.decision_digest
+        decision = dict(review_result.decision_document)
+    else:
+        adopted = _adoptable_reviewed_build(journaled_reviewed_build, candidate_run_dir)
+        review_candidate_digest = adopted["candidate_digest"]
+        decision = dict(adopted["decision"])
+        review_decision_digest = adopted["decision_digest"]
+
+    frozen = embedded["recipe"]
+    execution = embedded["execution"]
+    if (
+        review_candidate_digest is not None
+        and review_candidate_digest != inspection.candidate_digest
+    ):
+        raise DeployRefused(
+            f"the signed review for {candidate_run_dir} names a different Build "
+            "[REVIEW_CANDIDATE_MISMATCH]"
+        )
+    try:
+        acquisition_bundle = deployment_evidence.persist_acquisition_bundle(
+            Path(candidate_run_dir),
+            previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+        )
+    except deployment_evidence.DeploymentEvidenceError as error:
+        raise DeployRefused(
+            f"the acquisition evidence for {candidate_run_dir} could not be closed [{error.code}]"
+        ) from error
+    except (
+        recipe.RecipeError,
+        pipeline.BuildError,
+        canonical.CanonicalJSONError,
+        OSError,
+    ) as error:
+        raise DeployRefused(
+            f"the acquisition evidence for {candidate_run_dir} could not be closed "
+            f"[{type(error).__name__}]"
+        ) from error
+    if (
+        acquisition_bundle.candidate_digest != inspection.candidate_digest
+        or acquisition_bundle.recipe_digest != execution.recipe_digest
+        or acquisition_bundle.execution_digest != execution.digest
+    ):
+        raise DeployRefused(
+            f"the acquisition evidence for {candidate_run_dir} names a different reviewed Build "
+            "[DEPLOYMENT_EVIDENCE_BINDING]"
+        )
+    try:
+        bundle_document = deployment_evidence.load_acquisition_bundle_document(
+            Path(candidate_run_dir),
+            acquisition_bundle.bundle_digest,
+            previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+        )
+        with pipeline.open_verified_snapshot(Path(candidate_run_dir)) as snapshot:
+            repeated_inspection, repeated_embedded = recipe.verify_recipe_candidate(
+                Path(candidate_run_dir),
+                previous_run_dir=None if previous_run_dir is None else Path(previous_run_dir),
+                _snapshot=snapshot,
+            )
+            manifest_raw = snapshot.member_bytes("manifest.json")
+            plan_raw = snapshot.member_bytes("plan.json")
+            lineage_raw = snapshot.member_bytes("evidence/lineage.json")
+            snapshot.validate()
+    except (
+        deployment_evidence.DeploymentEvidenceError,
+        recipe.RecipeError,
+        pipeline.BuildError,
+    ) as error:
+        raise DeployRefused(
+            f"the Studio handoff for {candidate_run_dir} could not authenticate its Build evidence "
+            f"[{type(error).__name__}]"
+        ) from error
+    if (
+        repeated_inspection.candidate_digest != inspection.candidate_digest
+        or repeated_embedded["recipe"].digest != frozen.digest
+    ):
+        raise DeployRefused(
+            f"the Studio handoff for {candidate_run_dir} changed during preparation "
+            "[DEPLOYMENT_EVIDENCE_RACE]"
+        )
+    reviewed_build: dict[str, Any] | None = None
+    if decision is not None:
+        try:
+            review_key_id = decision["verifier_principal"]
+            if not isinstance(review_key_id, str) or not review_key_id:
+                raise ValueError("review verifier principal is absent")
+            binding_payload = {
+                "schema_version": "mostlyright-reviewed-build-bootstrap.v1",
+                "candidate_digest": review_candidate_digest,
+                "acquisition_bundle_digest": acquisition_bundle.bundle_digest,
+                "review_key_id": review_key_id,
+                "review_key_version": 1,
+                "decision_digest": review_decision_digest,
+            }
+            binding_digest = hashlib.sha256(canonical_json_line_bytes(binding_payload)).hexdigest()
+            binding_body = {**binding_payload, "binding_digest": binding_digest}
+            if adopted is None:
+                authority = resolve_review_authority(review_authority_provider)
+                verifier_signer = authority.verifier_signer()
+                binding_signature = base64.b64encode(
+                    verifier_signer.sign(canonical_json_line_bytes(binding_body))
+                ).decode("ascii")
+            else:
+                binding_signature = _adopted_binding_signature(
+                    adopted, binding_payload, binding_digest
+                )
+        except (KeyError, TypeError, ValueError, SignerProviderError) as error:
+            raise DeployRefused(
+                f"the protected review authority for {candidate_run_dir} could not bind the Studio "
+                "handoff [REVIEW_AUTHORITY_UNAVAILABLE]"
+            ) from error
+        reviewed_build = {
+            "schema_version": binding_payload["schema_version"],
+            "candidate_digest": binding_payload["candidate_digest"],
+            "acquisition_bundle_digest": binding_payload["acquisition_bundle_digest"],
+            "review_key_id": binding_payload["review_key_id"],
+            "review_key_version": binding_payload["review_key_version"],
+            "acquisition_bundle": bundle_document,
+            "decision": decision,
+            "binding_digest": binding_digest,
+            "binding_signature": binding_signature,
+        }
+    canonical_recipe_json = canonical.canonical_json_bytes(frozen.to_dict()).decode("utf-8")
+    bootstrap_evidence = {
+        "bootstrap_table_digest": inspection.table_sha256,
+        "bootstrap_verification_digest": inspection.validation_policy_digest,
+        "artifact_manifest_digest": hashlib.sha256(manifest_raw).hexdigest(),
+        "lineage_digest": hashlib.sha256(lineage_raw).hexdigest(),
+        "harness_version": package_version(),
+        # Present exactly when a binding was adopted or minted. Absent, rather than present and
+        # empty: a caller reading a key that is there has no way to tell an unsigned placeholder
+        # from a signature it should have checked. `bundle_document` still travels to Studio inside
+        # it on the two attested paths; on this one the bundle is read back out of the run
+        # directory under `acquisition_bundle_digest`, which is a field of the request itself.
+        **({} if reviewed_build is None else {"reviewed_build": reviewed_build}),
+    }
+    return DeploymentRequest(
+        schema=DEPLOYMENT_REQUEST_SCHEMA,
+        recipe_id=frozen.recipe_id,
+        recipe_version=frozen.recipe_version,
+        recipe_digest=execution.recipe_digest,
+        candidate_digest=inspection.candidate_digest,
+        review_decision_digest=review_decision_digest,
+        acquisition_bundle_digest=acquisition_bundle.bundle_digest,
+        execution_plan_digest=hashlib.sha256(plan_raw).hexdigest(),
+        canonical_recipe_json=canonical_recipe_json,
+        recipe_schema_version=frozen.schema_version,
+        bootstrap_evidence=bootstrap_evidence,
+        dataset_name=_plain_name(dataset_name, "a live dataset"),
+        target=target,
+        caps=caps,
+        cadence=cadence,
+    )
+
+
+@dataclass(frozen=True)
+class DeployPlanResult:
+    """The verdict on one deployment-planning attempt: a request, or why there is none.
+
+    Invariant: ``ok`` is true if and only if ``refusals`` is empty and ``request`` is not None. Only
+    two shapes exist, exactly as in :class:`deploy_target.DeployPreflight`. A refused result never
+    hands back a request, because a request in hand is the thing a caller acts on.
+
+    ``caps`` is present in both shapes: the caps a live dataset would run under are worth reporting
+    even when the answer is no.
+    """
+
+    ok: bool
+    refusals: tuple[str, ...]
+    request: DeploymentRequest | None
+    caps: CapPolicy
+
+    def __post_init__(self) -> None:
+        if type(self.ok) is not bool:
+            raise DeployRefused("ok must be a boolean verdict")
+        if type(self.refusals) is not tuple or any(
+            type(item) is not str or not item.strip() for item in self.refusals
+        ):
+            raise DeployRefused("refusals must be a tuple of named reasons")
+        if self.request is not None and not isinstance(self.request, DeploymentRequest):
+            raise DeployRefused("request must be a deployment request or nothing")
+        if not isinstance(self.caps, CapPolicy):
+            raise DeployRefused("a deployment plan always carries the caps it was asked for")
+        clean = not self.refusals and self.request is not None
+        if self.ok is not clean:
+            raise DeployRefused(
+                "a deployment plan succeeds only when there are no refusals and a request was built"
+            )
+
+    @property
+    def request_digest(self) -> str | None:
+        """The content digest of the request, or nothing when there is no request."""
+
+        return None if self.request is None else self.request.digest()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the one fact set both renderings are built from.
+
+        Every human line and every JSON field this product prints for a deployment plan comes from
+        here, so the two cannot report different things.
+        """
+
+        return {
+            "schema_version": DEPLOY_PLAN_RESULT_SCHEMA,
+            "status": "deployment_plan_ready" if self.ok else "deployment_plan_refused",
+            "ok": self.ok,
+            "refusals": list(self.refusals),
+            "request": None if self.request is None else self.request.to_summary_dict(),
+            "request_digest": self.request_digest,
+            "caps": {
+                "max_runs_per_month": self.caps.max_runs_per_month,
+                "max_concurrent_runs": self.caps.max_concurrent_runs,
+                "max_monthly_cost_units": self.caps.max_monthly_cost_units,
+            },
+            "caps_enforced_here": False,
+        }
+
+
+def plan_deployment(
+    *,
+    descriptor: Mapping[str, object],
+    corroboration: Mapping[str, object],
+    candidate_run_dir: Path,
+    previous_run_dir: Path | None = None,
+    dataset_name: str,
+    caps: CapPolicy,
+    cadence: Cadence,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> DeployPlanResult:
+    """Plan whether this recipe could go live, without deploying or contacting anything.
+
+    Order is load-bearing and is checked first on purpose: **the target before anything else.**
+    Establishing where a dataset would be published is the cheapest check available and the most
+    expensive one to get wrong — it spends real money in a real project. So nothing is read,
+    fetched, sent, or written before we know where it would go. When the target is ambiguous this
+    function returns before the run directory is even opened.
+
+    No network call happens on any path through this function. Verification is local, and the
+    request is data.
+
+    Raises:
+        deploy_target.TargetAmbiguityError: only when ``descriptor`` or ``corroboration`` is not a
+            well-formed mapping — a structurally invalid call, not an ambiguous target.
+    """
+
+    if not isinstance(caps, CapPolicy):
+        raise DeployRefused("the caps must be a cap policy; a live dataset is never uncapped")
+
+    verdict = deploy_target.preflight(descriptor, corroboration=corroboration)
+    if not verdict.ok:
+        # The preflight's reasons are carried verbatim: it already names both projects, and
+        # rewording them here would create a second wording of the same fact.
+        return DeployPlanResult(ok=False, refusals=verdict.refusals, request=None, caps=caps)
+
+    assert verdict.target is not None  # the preflight invariant, restated for the type checker
+    try:
+        request = build_deployment_request(
+            candidate_run_dir=candidate_run_dir,
+            previous_run_dir=previous_run_dir,
+            dataset_name=dataset_name,
+            target=verdict.target,
+            caps=caps,
+            cadence=cadence,
+            review_authority_provider=review_authority_provider,
+        )
+    except DeployRefused as refusal:
+        return DeployPlanResult(ok=False, refusals=refusal.reasons, request=None, caps=caps)
+
+    return DeployPlanResult(ok=True, refusals=(), request=request, caps=caps)
+
+
+# Compatibility aliases for callers of the pre-35 library vocabulary. Neither alias grants a
+# deployment acknowledgement or changes the planning-only semantics.
+GoLiveResult = DeployPlanResult
+plan_go_live = plan_deployment
+
+
+__all__ = [
+    "DEPLOYMENT_REQUEST_SCHEMA",
+    "DEPLOY_PLAN_RESULT_SCHEMA",
+    "GO_LIVE_RESULT_SCHEMA",
+    "Cadence",
+    "DeployPlanResult",
+    "DeployRefused",
+    "DeploymentRequest",
+    "GoLiveResult",
+    "build_deployment_request",
+    "plan_deployment",
+    "plan_go_live",
+]