mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/propose.py

@@ -0,0 +1,2759 @@
+"""``mr-data propose``: the hosted authoring front door ADR 0021 left open.
+
+WHAT WAS MISSING. ADR 0021 makes the product hosted-only and the client thin, but the only thing
+that created a recipe proposal was the LOCAL lane -- ``mr-data deploy`` from a sealed local Build,
+through :mod:`mostlyright.data_harness.hosted_deploy`, which imports pyarrow, croniter and the
+generated client and is forbidden in the thin profile. ``mr-data build --recipe-proposal ID
+--recipe-digest D`` therefore needed a proposal that nothing thin could make. This command makes
+one, over the same V3 routes ``hosted_deploy`` drives, in pure Python and urllib only.
+
+THE DOCUMENTS AN AGENT AUTHORS. A bundle directory holds the documents the hosted API needs, each
+in the exact shape ``docs/HOSTED-AUTHORING.md`` records and each checked here, against that shape,
+BEFORE a credential is minted or a request is sent:
+
+* ``dataset.json`` -> ``POST /v3/datasets``
+* ``question.json`` -> ``POST /v3/questions`` then ``PUT /v3/questions/{id}/requirements``
+* ``sources.json`` (a list) -> one ``POST /v3/sources`` and one
+  ``POST /v3/connector-configurations`` per entry
+* ``table_plan.json`` -> ``POST /v3/table-plans``
+* ``recipe.json`` -> the recipe document itself, whose coordinates become the proposal's and whose
+  canonical bytes are the ``recipe_digest``
+* ``activation.json`` -> the ``activation_intent`` sealed into the proposal
+
+Each of the first four may instead ADOPT a resource that already exists, by naming its id
+(``{"dataset_id": "..."}``), so a second bundle can attach to what a first one registered.
+
+WHY ``--through sources`` EXISTS. A recipe names its sources by the Studio source id, which does
+not exist until the source is registered. So an agent runs ``propose --through sources`` FIRST to
+register the Dataset, Question and Sources, opens a research session against them
+(``mr-data research-open --bundle``), probes, and only then writes ``recipe.json`` referencing the
+registered ids and re-runs ``propose`` to finish. The journal is what carries the registered ids
+across the two runs.
+
+WHAT THE JOURNAL PINS, AND WHEN. A document's digest is pinned the moment the first resource built
+from it completes -- ``dataset.json`` when the Dataset exists, ``question.json`` when the
+requirements are written, ``sources.json`` when the last connector is registered,
+``table_plan.json`` when the plan exists, ``recipe.json`` and ``activation.json`` when the
+proposal exists. Until then a
+document is free to change: a refused document is corrected and re-run, not abandoned. After it,
+a changed document is refused with the document named, because the resource Studio holds was built
+from the earlier one and a proposal a person is asked to approve must be the proposal that was
+authored.
+
+WHAT THIS COMMAND NEVER DOES. It records an approval ASK, exactly as ``mr-data approve`` does; it
+never grants one. A Table recipe is confirmed from a signed-in editor session in the dashboard,
+which a Cloud-minted service token cannot be, so the final receipt names the proposal, the recipe
+digest, the approval request, the dashboard address a person opens, and the two commands that
+follow -- ``mr-data recipe-approve`` (the ask a person settles) and then ``mr-data build``. It does
+NOT validate the transform rules inside the recipe: that is the local lane's job and imports the
+modules this profile forbids. Studio validates what Studio validates, and the hosted worker refuses
+a recipe its engine cannot run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import secrets
+import stat
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness import package_version
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_json,
+)
+from mostlyright.data_harness.formats import PARSER_FORMAT_ORDER
+
+# The externally enforced public-crawler egress policies, as their canonical attestations. Reused
+# rather than recomputed here for the reason the acquire lane reuses `session_probes`: a second
+# copy of a security-critical constant is a second thing to keep in step, and this one is the
+# digest Studio's own `STUDIO_PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION` is set to at deploy time.
+from mostlyright.data_harness.hosted_crawler_protocol import (
+    OPENLIGADB_EGRESS_POLICY_ATTESTATION,
+    PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+)
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+from mostlyright.data_harness.thin.approvals import GET_APPROVAL_PATH
+from mostlyright.data_harness.thin.research import GET_SESSION_PATH, RetryAfterRefusal
+from mostlyright.data_harness.thin.runs import (
+    GET_RECIPE_PROPOSAL_PATH,
+    StudioApiClient,
+)
+from mostlyright.data_harness.thin.session import (
+    StudioSession,
+    approval_dashboard_url,
+    dataset_dashboard_url,
+    open_studio_session,
+    run_dashboard_url,
+)
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+from mostlyright.data_harness.ux.path_kind import UNKNOWN_KIND, presence_at
+from mostlyright.data_harness.ux.plain_file import PlainFileRefusal, read_plain_file
+
+PROPOSE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-propose.v1"
+JOURNAL_SCHEMA = f"{THIN_SCHEMA_PREFIX}-propose-journal.v1"
+
+#: The V3 wire this lane speaks. The creates are each bound to an idempotency key, the one PUT
+#: upserts requirements, and the GETs either adopt a resource that already exists or read the
+#: proposal back for the ETag its approval is pinned to. None of them approves, activates,
+#: releases or decides. They are the exact routes :mod:`mostlyright.data_harness.hosted_deploy`
+#: drives, written out so a reviewer diffs them against ``contracts/openapi/studio-v3.yaml``.
+CREATE_DATASET_PATH = "/v3/datasets"
+GET_DATASET_PATH = "/v3/datasets/{dataset_id}"
+CREATE_QUESTION_PATH = "/v3/questions"
+GET_QUESTION_PATH = "/v3/questions/{question_id}"
+PUT_REQUIREMENTS_PATH = "/v3/questions/{question_id}/requirements"
+GET_REQUIREMENTS_PATH = "/v3/questions/{question_id}/requirements"
+REGISTER_SOURCE_PATH = "/v3/sources"
+GET_SOURCE_PATH = "/v3/sources/{source_id}"
+REGISTER_CONNECTOR_PATH = "/v3/connector-configurations"
+GET_CONNECTOR_PATH = "/v3/connector-configurations/{connector_configuration_id}"
+CREATE_TABLE_PLAN_PATH = "/v3/table-plans"
+GET_TABLE_PLAN_PATH = "/v3/table-plans/{table_plan_id}"
+WORKER_POLICY_PREFLIGHT_PATH = "/v3/worker-policy-preflights"
+CREATE_RECIPE_PROPOSAL_PATH = "/v3/recipe-proposals"
+#: ``createRecipeProposal`` answers 201 with NO ETag -- Studio declares no ``etag_kind`` on that
+#: route, and an idempotent replay never carries one either -- so the proposal is read back,
+#: where the ETag is, before the approval is pinned to it (``runs.GET_RECIPE_PROPOSAL_PATH``, the
+#: read ``build`` shares). A real run against Studio is what found this: a fake that invented an
+#: ETag on the create kept every test green over a lane that could never open its approval.
+REQUEST_RECIPE_APPROVAL_PATH = "/v3/recipe-proposals/{recipe_proposal_id}/approval"
+
+#: The V3 contract version every command body carries.
+STUDIO_SCHEMA_VERSION = "3.0.0"
+
+#: The media type a recipe travels under, and the recipe schema versions Studio's
+#: ``recipe_schema_version`` enum admits. Held here so a document naming a version Studio would
+#: refuse is a sentence at the terminal rather than a 422 three routes in.
+RECIPE_MEDIA_TYPE = "application/vnd.mostlyright.frozen-recipe+json"
+RECIPE_SCHEMA_VERSIONS = ("frozen-recipe.v1", "frozen-recipe.v3")
+
+#: The one bootstrap origin this lane sends. There is no local Build behind a hosted-first Recipe,
+#: so the first hosted Build is the bootstrap and the in-product approval plus the hosted
+#: independent check are the gates. Studio admits the hosted shape only on a first Recipe
+#: (``recipe_version`` 1 with a null predecessor), which this lane refuses locally before it can
+#: become a 422.
+HOSTED_BOOTSTRAP_ORIGIN = "hosted_first_build"
+
+#: The two credential-free public connector adapters, and the egress attestation each one carries.
+#: A source outside this map is a credentialed or sealed-artifact source, which the hosted
+#: authoring front door does not register -- those enter through the local lane's staged uploads.
+CONNECTOR_EGRESS_ATTESTATION = {
+    "public.https": PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+    "external.openligadb": OPENLIGADB_EGRESS_POLICY_ATTESTATION,
+}
+
+#: The stages ``--through`` may stop after, in the order a bundle is built. ``approval`` is the
+#: whole run and the default.
+STAGES = ("dataset", "question", "sources", "plan", "proposal", "approval")
+
+#: The bundle documents, and the stage each is first read for. A document is refused as missing
+#: only when a stage that needs it is reached, so ``--through sources`` never asks for a
+#: ``recipe.json`` that has not been written yet. ``recipe.json`` is read for the plan stage as
+#: well as the proposal, because the plan's digests describe the recipe.
+DOCUMENTS = {
+    "dataset": ("dataset.json",),
+    "question": ("question.json",),
+    "sources": ("sources.json",),
+    "plan": ("table_plan.json", "recipe.json"),
+    "proposal": ("activation.json",),
+}
+
+#: Which documents each stage pins when it completes. A pin is the statement "a resource Studio
+#: holds was built from this exact document"; a stage that has not completed has made no such
+#: statement, and its documents stay editable.
+PINS = {
+    "dataset": ("dataset.json",),
+    "question": ("question.json",),
+    "sources": ("sources.json",),
+    "plan": ("table_plan.json",),
+    "proposal": ("recipe.json", "activation.json"),
+}
+
+#: A bundle document is read whole under the same open-then-fstat rule every named path is read
+#: under, and one four times the canonical recipe ceiling is refused before it is parsed.
+MAX_DOCUMENT_BYTES = 4 * 262_144
+
+#: The journal embeds every resource Studio answered with -- the proposal, with its canonical
+#: recipe bytes, among them -- so its ceiling is above a single document's.
+MAX_JOURNAL_BYTES = 4 * MAX_DOCUMENT_BYTES
+
+#: ``canonical_recipe_json`` is bounded by the contract at 262144 UTF-8 bytes. Checked here so a
+#: recipe that canonicalises larger is a sentence rather than a 422.
+MAX_CANONICAL_RECIPE_BYTES = 262_144
+
+#: Studio's ``Retry-After`` is delta-seconds. Bounded the way the research lane bounds its own: a
+#: window this lane does not understand is reported as no window rather than as a number nobody
+#: checked.
+MAX_RETRY_AFTER_SECONDS = 3_600
+
+#: The journal directory and file, created 0700 and 0600 so a bundle checked out on a shared
+#: machine does not leave a workspace's created-resource ids world-readable.
+JOURNAL_DIR = ".mr-data"
+JOURNAL_FILE = "propose.journal.json"
+
+#: The schedule a bundle gets when ``activation.json`` leaves one out: daily at midnight UTC, one
+#: run at a time -- the same defaults ``mr-data deploy`` applies.
+DEFAULT_SCHEDULE = {
+    "cron": "0 0 * * *",
+    "timezone": "UTC",
+    "mode": "incremental_refresh",
+    "max_concurrent_runs": 1,
+}
+
+# The structural rules Studio's JSON Schema files declare for the bodies this lane sends, restated
+# here so a document is refused at the terminal in the words of the document rather than three
+# routes in with a JSON pointer. Every enum and pattern is the contract's own, and the cross-repo
+# gate in `tests/test_thin_propose.py` holds every body built from them against the schema files.
+_HARNESS_VERSION = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
+_UUID_TEXT = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
+_PREFIXED_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_BARE_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_COLUMN = re.compile(r"^[a-z][a-z0-9_]{0,62}$")
+_SEMVER = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+_TIMESTAMP = re.compile(
+    r"^(?:[0-9]{4})-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])"
+    r"T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\.[0-9]{1,9})?Z$"
+)
+_HTTPS_URL = re.compile(r"^https://[^:/?#@]+(?:(?:/[^#]*)|(?:\?[^#]*))?$")
+_FILENAME = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+
+_SOURCE_CLASSES = (
+    "mostlyright_sdk",
+    "external_adapter",
+    "user_file",
+    "user_url",
+    "user_api",
+    "database_extract",
+    "webhook",
+    "stream",
+)
+_LOCATOR_KINDS = ("sdk_connector", "https_url", "artifact", "webhook", "stream", "database")
+_CLASSIFICATIONS = ("public", "internal", "confidential", "restricted")
+_CLAIMED_BASES = (
+    "unknown",
+    "prohibited",
+    "permission_asserted",
+    "public_domain_asserted",
+    "contractual_license_asserted",
+    "terms_of_service_asserted",
+)
+_TARGET_POLICIES = ("none", "required_if_supportable")
+_FEASIBILITY_DECISIONS = ("supportable", "supportable_with_limits", "unsupported")
+_REASON_CODES = (
+    "SUFFICIENT_EVIDENCE",
+    "LIMITED_COVERAGE",
+    "UNACCEPTABLE_DELAY",
+    "RIGHTS_UNCLEAR",
+    "NO_RELIABLE_SOURCE",
+    "TARGET_NOT_OBSERVABLE",
+)
+_OVERLAP_POLICIES = ("disallow_released_coverage", "allow_within_envelope")
+_BACKFILL_POLICY_SCHEMA = "local-backfill-policy.v1"
+_QUERY_LIMIT_CEILINGS = {
+    "max_source_bytes": 268_435_456,
+    "max_normalized_bytes": 4_294_967_296,
+    "max_rows": 10_000_000,
+    "max_columns": 1_024,
+}
+
+
+class ProposeError(ThinLaneError):
+    """A typed refusal from the authoring front door, carrying an operator action.
+
+    Distinct from a plain :class:`ThinLaneError` only in that it always names what to do next --
+    the document to fix, or the command to run first -- so a refusal an agent reads is actionable
+    rather than merely typed.
+    """
+
+    def __init__(self, code: str, detail: str) -> None:
+        super().__init__(code, detail)
+
+
+# --------------------------------------------------------------------------------------------
+# The client
+# --------------------------------------------------------------------------------------------
+
+
+class StudioProposeClient(StudioApiClient):
+    """The V3 authoring calls: creates under an idempotency key, and reads. Nothing decides.
+
+    ``request_recipe_approval`` is the one that opens an approval, and it opens an ASK: Studio
+    writes one immutable request row and never a decision, which is why this lane can create the
+    thing ``mr-data recipe-approve`` later points a human at without ever being able to grant it.
+    """
+
+    def create(
+        self,
+        path: str,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str,
+        expected: int,
+        method: str = "POST",
+        if_match: str | None = None,
+        response_headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key}
+        if if_match is not None:
+            headers["If-Match"] = if_match
+        captured: dict[str, str] = {}
+        try:
+            result = self._call(
+                method,
+                path,
+                body=body,
+                extra_headers=headers,
+                expected=(expected,),
+                response_headers=captured,
+            )
+        except ThinLaneError as refusal:
+            raise _maybe_retry_after(refusal, captured) from refusal
+        if response_headers is not None:
+            response_headers.update(captured)
+        return result
+
+    def read(self, path: str, *, response_headers: dict[str, str] | None = None) -> dict[str, Any]:
+        """One bounded GET of one Studio resource, with the ETag it answered under."""
+
+        captured: dict[str, str] = {}
+        try:
+            result = self._call("GET", path, expected=(200,), response_headers=captured)
+        except ThinLaneError as refusal:
+            raise _maybe_retry_after(refusal, captured) from refusal
+        if response_headers is not None:
+            response_headers.update(captured)
+        return result
+
+    def worker_policy_preflight(self, body: Mapping[str, Any]) -> dict[str, Any]:
+        """Studio's current worker selection for this proposal, read without journaling a write.
+
+        The preflight is not a mutation: it resolves the deployed fleet's images and validation
+        policy for the recipe's mode, and the approval request below carries it back so Studio can
+        re-check it against the same immutable TablePlan. This lane never re-derives that policy --
+        that needs the engine this profile does not carry -- so it passes Studio's own answer
+        through, and Studio re-checks it at approval and at build.
+        """
+
+        captured: dict[str, str] = {}
+        try:
+            return self._call(
+                "POST",
+                WORKER_POLICY_PREFLIGHT_PATH,
+                body=body,
+                expected=(200,),
+                response_headers=captured,
+            )
+        except ThinLaneError as refusal:
+            raise _maybe_retry_after(refusal, captured) from refusal
+
+
+def _maybe_retry_after(refusal: ThinLaneError, headers: Mapping[str, str]) -> ThinLaneError:
+    """Carry a ``Retry-After`` window on a refusal Studio stamped one on, never sleep through it.
+
+    A workspace Studio is rate-limiting answers with a window rather than a queue, and the honest
+    thing is to report the window and let the caller decide, the way the research lane reports a
+    full-workspace refusal. Any refusal that arrives with a usable ``Retry-After`` becomes a
+    :class:`RetryAfterRefusal` carrying the number the router already knows how to surface.
+    """
+
+    raw = headers.get("retry-after", "")
+    if not raw.isdecimal():
+        return refusal
+    window = int(raw)
+    if not 1 <= window <= MAX_RETRY_AFTER_SECONDS:
+        return refusal
+    windowed = RetryAfterRefusal(
+        refusal.code,
+        f"{refusal.detail}; Studio asked this command to retry after {window} seconds. "
+        "Nothing further was created, and this command did not wait",
+        retry_after_seconds=window,
+    )
+    # The facts about the answer ride along, so the applied-or-not question below can still be
+    # asked of a windowed refusal.
+    windowed.http_status = getattr(refusal, "http_status", None)  # type: ignore[attr-defined]
+    windowed.studio_code = getattr(refusal, "studio_code", None)  # type: ignore[attr-defined]
+    return windowed
+
+
+#: The statuses under which Studio answered with a problem document BEFORE any write: the request
+#: failed validation, named a resource that is not there, asserted a stale version, or carried no
+#: authority for the route. Every one of them is raised before ``v3_idempotent`` reserves a key.
+_REFUSED_BEFORE_WRITE = frozenset({401, 403, 404, 412, 422})
+
+
+def _nothing_was_applied(refusal: ThinLaneError) -> bool:
+    """Whether a refusal means Studio answered and applied nothing -- decided narrowly.
+
+    Only a problem document from Studio under a validation or conflict status says that: 401, 403,
+    404, 412 and 422, and a 409 whose code is not one of the idempotency codes. Everything else
+    keeps the plan. A 5xx may be a gateway answering after Studio applied the write; an answer
+    this lane could not read as a problem document says nothing about what happened behind it; and
+    the two ``IDEMPOTENCY_*`` 409s are Studio saying the key IS reserved -- in progress, or
+    reserved without its record because ``v3_idempotent`` writes the resource and completes the
+    record in two transactions -- so the write may well have landed. For all of those the only
+    honest resume is the identical request under the identical key, which Studio replays.
+    """
+
+    status = getattr(refusal, "http_status", None)
+    studio_code = getattr(refusal, "studio_code", None)
+    if not isinstance(status, int) or not isinstance(studio_code, str):
+        return False
+    if status in _REFUSED_BEFORE_WRITE:
+        return True
+    return status == 409 and not studio_code.startswith("IDEMPOTENCY_")
+
+
+# --------------------------------------------------------------------------------------------
+# The bundle, read and checked before anything is minted
+# --------------------------------------------------------------------------------------------
+
+
+def _invalid(name: str, path: str, what: str) -> ProposeError:
+    where = f"{name} {path}" if path else name
+    return ProposeError("THIN_PROPOSE_DOCUMENT_INVALID", f"{where} {what}")
+
+
+def _bundle_directory(value: Any) -> Path:
+    """The bundle directory, refused before a credential is resolved if it is not one.
+
+    The refusals name what the open actually observed rather than asserting a kind: ``presence_at``
+    reads the mode the look found, so "there is nothing there" and "there is a file there" are
+    answers to a look, not guesses -- the same rule ``thin.acquire`` reads a named path under, and
+    the one ``scripts/path_kind_gate.py`` holds every surface to.
+    """
+
+    if not isinstance(value, str) or not value:
+        raise ProposeError("THIN_PROPOSE_BUNDLE_INVALID", "propose names one bundle directory")
+    path = Path(value).expanduser()
+    try:
+        info = path.lstat()
+    except OSError:
+        raise ProposeError(
+            "THIN_PROPOSE_BUNDLE_INVALID",
+            f"there is {presence_at(path) or UNKNOWN_KIND} at {path}: propose reads its documents "
+            "out of a directory",
+        ) from None
+    if stat.S_ISLNK(info.st_mode) or not path.is_dir():
+        raise ProposeError(
+            "THIN_PROPOSE_BUNDLE_INVALID",
+            f"there is {presence_at(path) or UNKNOWN_KIND} at {path}, not the directory propose "
+            "reads its documents out of",
+        )
+    return path
+
+
+def _read_document(bundle: Path, name: str) -> tuple[Any, str]:
+    """One bundle document and the digest of its bytes, parsed as STRICT JSON.
+
+    Strict, not foreign: every number in a bundle reaches a canonical digest or a Studio body that
+    is digested there, and the Harness data model admits no fractional number anywhere on that
+    path. A float is refused here, by document and position, rather than three stages in as a
+    canonicalisation error out of a request body.
+    """
+
+    target = bundle / name
+    try:
+        raw = read_plain_file(target, max_bytes=MAX_DOCUMENT_BYTES)
+    except PlainFileRefusal as refusal:
+        raise ProposeError(
+            "THIN_PROPOSE_DOCUMENT_UNREADABLE",
+            f"{name} could not be read from the bundle ({refusal.reason}); author it at {target}",
+        ) from None
+    except OSError as error:
+        raise ProposeError(
+            "THIN_PROPOSE_DOCUMENT_UNREADABLE", f"{name} could not be read: {error}"
+        ) from error
+    try:
+        parsed = parse_json(raw)
+    except CanonicalJSONError as error:
+        raise ProposeError(
+            "THIN_PROPOSE_DOCUMENT_INVALID",
+            f"{name} is not strict JSON at {error.path}: {error.detail}; a bundle carries "
+            "integers, strings, booleans, null, objects and lists, and never a fractional number",
+        ) from error
+    return parsed, hashlib.sha256(raw).hexdigest()
+
+
+# -- the checks, in the vocabulary of the document --------------------------------------------
+
+
+def _object(value: Any, name: str, path: str = "") -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise _invalid(name, path, "must be a JSON object")
+    return value
+
+
+def _keys(
+    value: Mapping[str, Any],
+    name: str,
+    path: str,
+    required: Sequence[str],
+    optional: Sequence[str] = (),
+) -> None:
+    missing = [key for key in required if key not in value]
+    if missing:
+        raise _invalid(name, path, f"is missing {', '.join(repr(key) for key in missing)}")
+    extra = sorted(set(value) - set(required) - set(optional))
+    if extra:
+        raise _invalid(
+            name,
+            path,
+            f"carries {', '.join(repr(key) for key in extra)}, which the shape has no room for",
+        )
+
+
+def _string(
+    value: Any,
+    name: str,
+    path: str,
+    *,
+    minimum: int = 1,
+    maximum: int | None = None,
+    pattern: re.Pattern[str] | None = None,
+    what: str = "",
+) -> str:
+    if not isinstance(value, str):
+        raise _invalid(name, path, "must be a string")
+    if len(value) < minimum:
+        raise _invalid(name, path, f"must be at least {minimum} character(s)")
+    if maximum is not None and len(value) > maximum:
+        raise _invalid(name, path, f"must be at most {maximum} characters")
+    if pattern is not None and pattern.fullmatch(value) is None:
+        raise _invalid(name, path, f"is not {what or 'in the shape the contract admits'}")
+    return value
+
+
+def _enum(value: Any, name: str, path: str, allowed: Sequence[str]) -> str:
+    if value not in allowed:
+        raise _invalid(name, path, f"must be one of: {', '.join(allowed)}")
+    return value
+
+
+def _integer(value: Any, name: str, path: str, *, minimum: int, maximum: int) -> int:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise _invalid(name, path, f"must be an integer from {minimum} to {maximum}")
+    return value
+
+
+def _boolean(value: Any, name: str, path: str) -> bool:
+    if type(value) is not bool:
+        raise _invalid(name, path, "must be true or false")
+    return value
+
+
+def _uuid_text(value: Any, name: str, path: str) -> str:
+    if not isinstance(value, str) or _UUID_TEXT.fullmatch(value) is None:
+        raise _invalid(name, path, "must be an identifier Studio assigned (a UUID)")
+    return value
+
+
+def _digest(value: Any, name: str, path: str) -> str:
+    return _string(value, name, path, pattern=_PREFIXED_DIGEST, what="a sha256:-prefixed digest")
+
+
+def _timestamp(value: Any, name: str, path: str) -> str:
+    return _string(value, name, path, pattern=_TIMESTAMP, what="a UTC timestamp ending in Z")
+
+
+def _time_range(value: Any, name: str, path: str) -> dict[str, str]:
+    window = _object(value, name, path)
+    _keys(window, name, path, ("start_inclusive", "end_exclusive"))
+    return {
+        "start_inclusive": _timestamp(window["start_inclusive"], name, f"{path}.start_inclusive"),
+        "end_exclusive": _timestamp(window["end_exclusive"], name, f"{path}.end_exclusive"),
+    }
+
+
+def _column_list(
+    value: Any,
+    name: str,
+    path: str,
+    *,
+    minimum_items: int = 1,
+    maximum_items: int | None = None,
+) -> list[str]:
+    if not isinstance(value, list) or len(value) < minimum_items:
+        raise _invalid(name, path, f"must be a list of at least {minimum_items} column name(s)")
+    if maximum_items is not None and len(value) > maximum_items:
+        raise _invalid(name, path, f"must name at most {maximum_items} columns")
+    columns = [
+        _string(item, name, f"{path}[{index}]", pattern=_COLUMN, what="a lowercase column name")
+        for index, item in enumerate(value)
+    ]
+    if len(set(columns)) != len(columns):
+        raise _invalid(name, path, "must not name a column twice")
+    return columns
+
+
+def check_dataset(document: Any) -> dict[str, Any]:
+    """``dataset.json``: a name and an optional description, or the id of a Dataset to adopt."""
+
+    value = _object(document, "dataset.json")
+    if "dataset_id" in value:
+        _keys(value, "dataset.json", "", ("dataset_id",))
+        return {"dataset_id": _uuid_text(value["dataset_id"], "dataset.json", "dataset_id")}
+    _keys(value, "dataset.json", "", ("name",), ("description",))
+    checked = {"name": _string(value["name"], "dataset.json", "name", maximum=160)}
+    if "description" in value:
+        checked["description"] = _string(
+            value["description"], "dataset.json", "description", minimum=0, maximum=4000
+        )
+    return checked
+
+
+def check_requirements(value: Any, name: str, path: str) -> dict[str, Any]:
+    """The ``RequirementsUpsertCommand`` content, in the contract's own enums and patterns."""
+
+    requirements = _object(value, name, path)
+    _keys(
+        requirements,
+        name,
+        path,
+        (
+            "population",
+            "time_range",
+            "output_grain",
+            "required_fields",
+            "target_policy",
+            "success_criteria",
+            "feasibility",
+        ),
+        ("prediction_cutoff",),
+    )
+    feasibility = _object(requirements["feasibility"], name, f"{path}.feasibility")
+    _keys(feasibility, name, f"{path}.feasibility", ("decision", "reason_codes", "narrative"))
+    codes = feasibility["reason_codes"]
+    if not isinstance(codes, list) or len(set(map(str, codes))) != len(codes):
+        raise _invalid(name, f"{path}.feasibility.reason_codes", "must be a list without repeats")
+    criteria = requirements["success_criteria"]
+    if not isinstance(criteria, list) or not criteria:
+        raise _invalid(name, f"{path}.success_criteria", "must be a non-empty list")
+    checked: dict[str, Any] = {
+        "population": _string(requirements["population"], name, f"{path}.population", maximum=2000),
+        "time_range": _time_range(requirements["time_range"], name, f"{path}.time_range"),
+        "output_grain": _column_list(requirements["output_grain"], name, f"{path}.output_grain"),
+        "required_fields": _column_list(
+            requirements["required_fields"], name, f"{path}.required_fields"
+        ),
+        "target_policy": _enum(
+            requirements["target_policy"], name, f"{path}.target_policy", _TARGET_POLICIES
+        ),
+        "success_criteria": [
+            _string(item, name, f"{path}.success_criteria[{index}]", maximum=1000)
+            for index, item in enumerate(criteria)
+        ],
+        "feasibility": {
+            "decision": _enum(
+                feasibility["decision"],
+                name,
+                f"{path}.feasibility.decision",
+                _FEASIBILITY_DECISIONS,
+            ),
+            "reason_codes": [
+                _enum(item, name, f"{path}.feasibility.reason_codes[{index}]", _REASON_CODES)
+                for index, item in enumerate(codes)
+            ],
+            "narrative": _string(
+                feasibility["narrative"], name, f"{path}.feasibility.narrative", maximum=4000
+            ),
+        },
+    }
+    if "prediction_cutoff" in requirements:
+        checked["prediction_cutoff"] = _timestamp(
+            requirements["prediction_cutoff"], name, f"{path}.prediction_cutoff"
+        )
+    return checked
+
+
+def check_question(document: Any) -> dict[str, Any]:
+    """``question.json``: the question text and its requirements, or the id of one to adopt."""
+
+    value = _object(document, "question.json")
+    if "question_id" in value:
+        _keys(value, "question.json", "", ("question_id",))
+        return {"question_id": _uuid_text(value["question_id"], "question.json", "question_id")}
+    _keys(value, "question.json", "", ("question", "requirements"))
+    return {
+        "question": _string(value["question"], "question.json", "question", maximum=8000),
+        "requirements": check_requirements(value["requirements"], "question.json", "requirements"),
+    }
+
+
+def _check_query(value: Any, name: str, path: str) -> dict[str, Any]:
+    """The ``public_https_query`` a ``public.https`` connector is registered with."""
+
+    query = _object(value, name, path)
+    _keys(
+        query,
+        name,
+        path,
+        ("url", "data_format", "filename", "reader_pin", "resource_caps", "limits"),
+    )
+    limits = _object(query["limits"], name, f"{path}.limits")
+    _keys(limits, name, f"{path}.limits", tuple(_QUERY_LIMIT_CEILINGS))
+    pin = query["reader_pin"]
+    if pin is not None and not isinstance(pin, dict):
+        raise _invalid(name, f"{path}.reader_pin", "must be null or a Reader pin object")
+    caps = query["resource_caps"]
+    if caps is not None:
+        if pin is None:
+            raise _invalid(name, f"{path}.resource_caps", "must be null when reader_pin is null")
+        caps = _object(caps, name, f"{path}.resource_caps")
+        _keys(
+            caps,
+            name,
+            f"{path}.resource_caps",
+            ("max_declared_cells", "max_container_members", "max_nesting_depth"),
+        )
+        _integer(
+            caps["max_declared_cells"],
+            name,
+            f"{path}.resource_caps.max_declared_cells",
+            minimum=1,
+            maximum=2**53,
+        )
+        _integer(
+            caps["max_container_members"],
+            name,
+            f"{path}.resource_caps.max_container_members",
+            minimum=1,
+            maximum=2**53,
+        )
+        if caps["max_nesting_depth"] != 1:
+            raise _invalid(name, f"{path}.resource_caps.max_nesting_depth", "must be 1")
+    return {
+        "url": _string(
+            query["url"],
+            name,
+            f"{path}.url",
+            maximum=2048,
+            pattern=_HTTPS_URL,
+            what="an https:// address with no credential",
+        ),
+        "data_format": _enum(
+            query["data_format"], name, f"{path}.data_format", PARSER_FORMAT_ORDER
+        ),
+        "filename": _string(
+            query["filename"],
+            name,
+            f"{path}.filename",
+            maximum=255,
+            pattern=_FILENAME,
+            what="a file name without a path",
+        ),
+        "reader_pin": pin,
+        "resource_caps": caps,
+        "limits": {
+            key: _integer(limits[key], name, f"{path}.limits.{key}", minimum=1, maximum=ceiling)
+            for key, ceiling in _QUERY_LIMIT_CEILINGS.items()
+        },
+    }
+
+
+def _check_connector(value: Any, name: str, path: str) -> dict[str, Any]:
+    connector = _object(value, name, path)
+    _keys(connector, name, path, ("adapter_id",), ("credential_mode", "query"))
+    adapter_id = connector["adapter_id"]
+    if adapter_id not in CONNECTOR_EGRESS_ATTESTATION:
+        allowed = ", ".join(sorted(CONNECTOR_EGRESS_ATTESTATION))
+        raise ProposeError(
+            "THIN_PROPOSE_CONNECTOR_UNSUPPORTED",
+            f"{name} {path}.adapter_id names {adapter_id!r}; the hosted authoring front door "
+            f"registers credential-free connectors ({allowed}), and a credentialed or staged-file "
+            "source enters through the local lane instead",
+        )
+    if connector.get("credential_mode", "none") != "none":
+        raise ProposeError(
+            "THIN_PROPOSE_CONNECTOR_UNSUPPORTED",
+            f"{name} {path}.credential_mode must be none: a {adapter_id} connector is "
+            "credential-free, and this lane registers no other kind",
+        )
+    checked: dict[str, Any] = {"adapter_id": adapter_id, "credential_mode": "none"}
+    if adapter_id == "public.https":
+        if "query" not in connector:
+            raise _invalid(name, path, "needs a 'query' for a public.https connector")
+        checked["query"] = _check_query(connector["query"], name, f"{path}.query")
+    elif "query" in connector:
+        raise _invalid(name, f"{path}.query", "is only carried by a public.https connector")
+    return checked
+
+
+def check_sources(document: Any) -> list[dict[str, Any]]:
+    """``sources.json``: one entry per source, each registering or adopting one."""
+
+    name = "sources.json"
+    if not isinstance(document, list) or not document:
+        raise _invalid(name, "", "must be a non-empty list of source entries")
+    entries: list[dict[str, Any]] = []
+    for index, item in enumerate(document):
+        path = f"[{index}]"
+        entry = _object(item, name, path)
+        if "source_id" in entry:
+            _keys(entry, name, path, ("name", "source_id", "connector_configuration_id"))
+            entries.append(
+                {
+                    "name": _string(entry["name"], name, f"{path}.name", maximum=200),
+                    "source_id": _uuid_text(entry["source_id"], name, f"{path}.source_id"),
+                    "connector_configuration_id": _uuid_text(
+                        entry["connector_configuration_id"],
+                        name,
+                        f"{path}.connector_configuration_id",
+                    ),
+                }
+            )
+            continue
+        _keys(
+            entry,
+            name,
+            path,
+            (
+                "name",
+                "source_class",
+                "locator",
+                "credential_reference_ids",
+                "data_classification",
+                "rights_claim",
+                "retention_policy",
+                "connector",
+            ),
+        )
+        locator = _object(entry["locator"], name, f"{path}.locator")
+        _keys(
+            locator,
+            name,
+            f"{path}.locator",
+            ("kind", "display_locator"),
+            ("connector_contract_version",),
+        )
+        checked_locator = {
+            "kind": _enum(locator["kind"], name, f"{path}.locator.kind", _LOCATOR_KINDS),
+            "display_locator": _string(
+                locator["display_locator"], name, f"{path}.locator.display_locator", maximum=2048
+            ),
+        }
+        if "connector_contract_version" in locator:
+            checked_locator["connector_contract_version"] = _string(
+                locator["connector_contract_version"],
+                name,
+                f"{path}.locator.connector_contract_version",
+                pattern=_SEMVER,
+                what="a version like 1.0.0",
+            )
+        if entry["credential_reference_ids"] != []:
+            raise ProposeError(
+                "THIN_PROPOSE_CONNECTOR_UNSUPPORTED",
+                f"{name} {path}.credential_reference_ids must be empty: this lane registers "
+                "credential-free sources only",
+            )
+        claim = _object(entry["rights_claim"], name, f"{path}.rights_claim")
+        _keys(
+            claim,
+            name,
+            f"{path}.rights_claim",
+            ("claimed_basis", "claim_evidence_digest"),
+            ("claim_note",),
+        )
+        checked_claim = {
+            "claimed_basis": _enum(
+                claim["claimed_basis"], name, f"{path}.rights_claim.claimed_basis", _CLAIMED_BASES
+            ),
+            "claim_evidence_digest": _digest(
+                claim["claim_evidence_digest"], name, f"{path}.rights_claim.claim_evidence_digest"
+            ),
+        }
+        if "claim_note" in claim:
+            checked_claim["claim_note"] = _string(
+                claim["claim_note"], name, f"{path}.rights_claim.claim_note", maximum=2000
+            )
+        retention = _object(entry["retention_policy"], name, f"{path}.retention_policy")
+        _keys(
+            retention,
+            name,
+            f"{path}.retention_policy",
+            ("raw_days", "derived_days", "tombstone_required"),
+        )
+        entries.append(
+            {
+                "name": _string(entry["name"], name, f"{path}.name", maximum=200),
+                "source_class": _enum(
+                    entry["source_class"], name, f"{path}.source_class", _SOURCE_CLASSES
+                ),
+                "locator": checked_locator,
+                "credential_reference_ids": [],
+                "data_classification": _enum(
+                    entry["data_classification"],
+                    name,
+                    f"{path}.data_classification",
+                    _CLASSIFICATIONS,
+                ),
+                "rights_claim": checked_claim,
+                "retention_policy": {
+                    "raw_days": _integer(
+                        retention["raw_days"],
+                        name,
+                        f"{path}.retention_policy.raw_days",
+                        minimum=0,
+                        maximum=3650,
+                    ),
+                    "derived_days": _integer(
+                        retention["derived_days"],
+                        name,
+                        f"{path}.retention_policy.derived_days",
+                        minimum=0,
+                        maximum=3650,
+                    ),
+                    "tombstone_required": _boolean(
+                        retention["tombstone_required"],
+                        name,
+                        f"{path}.retention_policy.tombstone_required",
+                    ),
+                },
+                "connector": _check_connector(entry["connector"], name, f"{path}.connector"),
+            }
+        )
+    names = [entry["name"] for entry in entries]
+    if len(set(names)) != len(names):
+        raise _invalid(
+            name,
+            "",
+            "must give each entry a distinct 'name'; the name is how the registered source id is "
+            "reported back for recipe.json to reference",
+        )
+    return entries
+
+
+def check_backfill_policy(value: Any, name: str, path: str) -> dict[str, Any]:
+    policy = _object(value, name, path)
+    _keys(
+        policy,
+        name,
+        path,
+        (
+            "schema_version",
+            "coverage_envelope",
+            "max_window_seconds",
+            "overlap_policy",
+            "partition_scope",
+        ),
+    )
+    if policy["schema_version"] != _BACKFILL_POLICY_SCHEMA:
+        raise _invalid(name, f"{path}.schema_version", f"must be {_BACKFILL_POLICY_SCHEMA}")
+    scope = _object(policy["partition_scope"], name, f"{path}.partition_scope")
+    _keys(
+        scope,
+        name,
+        f"{path}.partition_scope",
+        ("fields", "allowed_values", "max_partitions_per_run"),
+    )
+    allowed = _object(scope["allowed_values"], name, f"{path}.partition_scope.allowed_values")
+    if len(allowed) > 16:
+        raise _invalid(
+            name, f"{path}.partition_scope.allowed_values", "must name at most 16 fields"
+        )
+    checked_allowed: dict[str, list[str]] = {}
+    for field, values in allowed.items():
+        where = f"{path}.partition_scope.allowed_values.{field}"
+        if not isinstance(values, list) or not 1 <= len(values) <= 10_000:
+            raise _invalid(name, where, "must be a list of 1 to 10000 values")
+        items = [
+            _string(item, name, f"{where}[{index}]", maximum=256)
+            for index, item in enumerate(values)
+        ]
+        if len(set(items)) != len(items):
+            raise _invalid(name, where, "must not repeat a value")
+        checked_allowed[field] = items
+    return {
+        "schema_version": _BACKFILL_POLICY_SCHEMA,
+        "coverage_envelope": _time_range(
+            policy["coverage_envelope"], name, f"{path}.coverage_envelope"
+        ),
+        "max_window_seconds": _integer(
+            policy["max_window_seconds"],
+            name,
+            f"{path}.max_window_seconds",
+            minimum=1,
+            maximum=315_360_000,
+        ),
+        "overlap_policy": _enum(
+            policy["overlap_policy"], name, f"{path}.overlap_policy", _OVERLAP_POLICIES
+        ),
+        "partition_scope": {
+            "fields": _column_list(
+                scope["fields"],
+                name,
+                f"{path}.partition_scope.fields",
+                minimum_items=0,
+                maximum_items=16,
+            ),
+            "allowed_values": checked_allowed,
+            "max_partitions_per_run": _integer(
+                scope["max_partitions_per_run"],
+                name,
+                f"{path}.partition_scope.max_partitions_per_run",
+                minimum=1,
+                maximum=10_000,
+            ),
+        },
+    }
+
+
+def check_table_plan(document: Any) -> dict[str, Any]:
+    """``table_plan.json``: the authored plan content, or the id of a plan to adopt.
+
+    The three digests are optional: each is derived from ``recipe.json`` when left out, and held
+    to that derivation when written, so an author never has to compute one and cannot get one
+    wrong. ``approved_backfill_policy`` defaults to the recipe's own ``backfill_policy``.
+    """
+
+    name = "table_plan.json"
+    value = _object(document, name)
+    if "table_plan_id" in value:
+        _keys(value, name, "", ("table_plan_id",))
+        return {"table_plan_id": _uuid_text(value["table_plan_id"], name, "table_plan_id")}
+    _keys(
+        value,
+        name,
+        "",
+        ("output_grain", "transformation_contract_version"),
+        (
+            "execution_plan_digest",
+            "validation_policy_digest",
+            "approved_backfill_policy",
+            "backfill_policy_digest",
+        ),
+    )
+    checked: dict[str, Any] = {
+        "output_grain": _column_list(value["output_grain"], name, "output_grain"),
+        "transformation_contract_version": _string(
+            value["transformation_contract_version"],
+            name,
+            "transformation_contract_version",
+            pattern=_SEMVER,
+            what="a version like 1.0.0",
+        ),
+    }
+    for field in ("execution_plan_digest", "validation_policy_digest", "backfill_policy_digest"):
+        if field in value:
+            checked[field] = _digest(value[field], name, field)
+    if "approved_backfill_policy" in value:
+        checked["approved_backfill_policy"] = check_backfill_policy(
+            value["approved_backfill_policy"], name, "approved_backfill_policy"
+        )
+    return checked
+
+
+def check_activation(document: Any) -> dict[str, Any]:
+    """``activation.json``: the Table name and the refresh schedule, defaults filled in."""
+
+    name = "activation.json"
+    value = _object(document, name)
+    _keys(value, name, "", ("table_name",), ("schedule",))
+    table_name = _string(value["table_name"], name, "table_name", maximum=200)
+    if not table_name.strip():
+        raise _invalid(name, "table_name", "must not be blank")
+    schedule = dict(DEFAULT_SCHEDULE)
+    if "schedule" in value:
+        authored = _object(value["schedule"], name, "schedule")
+        _keys(authored, name, "schedule", (), tuple(DEFAULT_SCHEDULE))
+        schedule.update(authored)
+    checked_schedule = {
+        "cron": _string(schedule["cron"], name, "schedule.cron", minimum=9, maximum=100),
+        "timezone": _enum(schedule["timezone"], name, "schedule.timezone", ("UTC",)),
+        "mode": _enum(schedule["mode"], name, "schedule.mode", ("incremental_refresh",)),
+        "max_concurrent_runs": _integer(
+            schedule["max_concurrent_runs"],
+            name,
+            "schedule.max_concurrent_runs",
+            minimum=1,
+            maximum=10,
+        ),
+    }
+    return {"table_name": table_name, "schedule": checked_schedule}
+
+
+def check_recipe(document: Any) -> tuple[dict[str, Any], bytes, str]:
+    """``recipe.json``: its coordinates, its canonical bytes and their digest.
+
+    Only what the proposal restates is checked -- the schema version, the first-recipe coordinate,
+    the source inventory's shape, and the two members the plan's digests derive from. The transform
+    rules, the Reader pins and the unit semantics are NOT checked here: that is the local lane's
+    job and imports the modules this profile forbids, and the hosted worker refuses a recipe its
+    engine cannot run.
+    """
+
+    name = "recipe.json"
+    recipe = _object(document, name)
+    for field in (
+        "schema_version",
+        "recipe_id",
+        "recipe_version",
+        "predecessor_recipe_digest",
+        "sources",
+        "transform_plan",
+        "validation",
+    ):
+        if field not in recipe:
+            raise _invalid(name, "", f"is missing {field!r}")
+    _enum(recipe["schema_version"], name, "schema_version", RECIPE_SCHEMA_VERSIONS)
+    _string(
+        recipe["recipe_id"],
+        name,
+        "recipe_id",
+        pattern=_IDENTIFIER,
+        what="a recipe identifier (letters, digits, '_', '.', '-')",
+    )
+    if recipe["recipe_version"] != 1:
+        raise ProposeError(
+            "THIN_PROPOSE_RECIPE_COORDINATE",
+            "a hosted-first recipe is a first recipe: recipe.json must carry recipe_version 1 "
+            f"(it carries {recipe['recipe_version']!r})",
+        )
+    if recipe["predecessor_recipe_digest"] is not None:
+        raise ProposeError(
+            "THIN_PROPOSE_RECIPE_COORDINATE",
+            "a hosted-first recipe has no predecessor: recipe.json predecessor_recipe_digest "
+            "must be null",
+        )
+    sources = recipe["sources"]
+    if not isinstance(sources, list) or not sources:
+        raise _invalid(name, "sources", "must be a non-empty list")
+    seen: set[str] = set()
+    for index, item in enumerate(sources):
+        source = _object(item, name, f"sources[{index}]")
+        source_id = _string(
+            source.get("source_id"),
+            name,
+            f"sources[{index}].source_id",
+            pattern=_IDENTIFIER,
+            what="a source identifier",
+        )
+        _string(
+            source.get("adapter_id"),
+            name,
+            f"sources[{index}].adapter_id",
+            pattern=_IDENTIFIER,
+            what="an adapter identifier",
+        )
+        if source_id in seen:
+            raise _invalid(
+                name,
+                f"sources[{index}].source_id",
+                f"repeats {source_id!r}; a recipe names each source once",
+            )
+        seen.add(source_id)
+    _object(recipe["transform_plan"], name, "transform_plan")
+    validation = _object(recipe["validation"], name, "validation")
+    _string(
+        validation.get("policy_digest"),
+        name,
+        "validation.policy_digest",
+        pattern=_BARE_DIGEST,
+        what="a bare lowercase sha256 digest",
+    )
+    if "backfill_policy" in recipe:
+        check_backfill_policy(recipe["backfill_policy"], name, "backfill_policy")
+    try:
+        canonical_bytes = canonical_json_bytes(recipe)
+    except CanonicalJSONError as error:
+        raise ProposeError(
+            "THIN_PROPOSE_RECIPE_NONCANONICAL",
+            f"recipe.json cannot be canonicalised at {error.path}: {error.detail}",
+        ) from error
+    if len(canonical_bytes) > MAX_CANONICAL_RECIPE_BYTES:
+        raise ProposeError(
+            "THIN_PROPOSE_RECIPE_TOO_LARGE",
+            f"recipe.json is {len(canonical_bytes)} canonical bytes, over the "
+            f"{MAX_CANONICAL_RECIPE_BYTES}-byte contract ceiling",
+        )
+    return recipe, canonical_bytes, hashlib.sha256(canonical_bytes).hexdigest()
+
+
+def harness_version() -> str:
+    """The X.Y.Z this client records as ``harness_version``, refused when there is none.
+
+    Checked before the first request rather than at the proposal stage: a checkout that reports
+    ``uninstalled`` would otherwise register four stages of resources and then stop.
+    """
+
+    version = package_version()
+    if _HARNESS_VERSION.fullmatch(version) is None:
+        raise ProposeError(
+            "THIN_PROPOSE_HARNESS_VERSION",
+            f"this client reports version {version!r}, which is not the X.Y.Z a hosted bootstrap "
+            "records; run propose from an installed release",
+        )
+    return version
+
+
+# -- the derived plan digests -----------------------------------------------------------------
+
+
+def execution_plan_digest(recipe: Mapping[str, Any]) -> str:
+    """The digest of the recipe's transform plan as the hosted worker seals it.
+
+    The worker writes ``plan.json`` as the plan's sorted-key compact JSON terminated by one
+    newline and binds that member's digest; for a plan in its normalized form those bytes are the
+    canonical bytes plus the newline, so the plan's ``execution_plan_digest`` can describe the
+    recipe exactly without this lane carrying the engine.
+    """
+
+    return (
+        "sha256:"
+        + hashlib.sha256(canonical_json_bytes(recipe["transform_plan"]) + b"\n").hexdigest()
+    )
+
+
+def validation_policy_digest(recipe: Mapping[str, Any]) -> str:
+    return "sha256:" + str(recipe["validation"]["policy_digest"])
+
+
+def backfill_policy_digest(policy: Mapping[str, Any]) -> str:
+    return "sha256:" + canonical_sha256(dict(policy))
+
+
+def plan_content(plan: Mapping[str, Any], recipe: Mapping[str, Any]) -> dict[str, Any]:
+    """The table plan's authored content, its digests derived from the recipe and held to it."""
+
+    name = "table_plan.json"
+    derived = {
+        "execution_plan_digest": execution_plan_digest(recipe),
+        "validation_policy_digest": validation_policy_digest(recipe),
+    }
+    policy = plan.get("approved_backfill_policy")
+    if policy is None:
+        policy = recipe.get("backfill_policy")
+        if not isinstance(policy, dict):
+            raise _invalid(
+                name,
+                "approved_backfill_policy",
+                "is required when recipe.json carries no backfill_policy",
+            )
+        policy = check_backfill_policy(policy, "recipe.json", "backfill_policy")
+    derived["backfill_policy_digest"] = backfill_policy_digest(policy)
+    for field, expected in derived.items():
+        written = plan.get(field)
+        if written is not None and written != expected:
+            raise ProposeError(
+                "THIN_PROPOSE_PLAN_DIGEST",
+                f"table_plan.json {field} is {written}, but recipe.json derives {expected}; leave "
+                "the field out to have it derived, or correct it",
+            )
+    return {
+        "output_grain": plan["output_grain"],
+        "transformation_contract_version": plan["transformation_contract_version"],
+        "approved_backfill_policy": policy,
+        **derived,
+    }
+
+
+# --------------------------------------------------------------------------------------------
+# The journal
+# --------------------------------------------------------------------------------------------
+
+
+class Journal:
+    """The record of one bundle's authoring, in ``BUNDLE_DIR/.mr-data``.
+
+    It carries a nonce minted when it is created -- the idempotency keys are derived from it, so
+    two bundles with byte-identical documents can never replay each other's resources -- the
+    digest of every document pinned at the moment the first resource built from it completed, and
+    one entry per created or adopted resource: the request digest it was created from, the
+    idempotency key that created it, and the resource Studio answered with. A re-run replays every
+    completed resource from here without rebuilding it; a pinned document that changed is refused
+    with the document named.
+    """
+
+    def __init__(self, bundle: Path) -> None:
+        self._dir = bundle / JOURNAL_DIR
+        self._path = self._dir / JOURNAL_FILE
+        self.state: dict[str, Any] = {}
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def load_or_start(self, *, workspace_id: UUID) -> None:
+        if self._path.is_file():
+            self.state = read_journal(self._path)
+            if self.state.get("workspace_id") != str(workspace_id):
+                raise ProposeError(
+                    "THIN_PROPOSE_JOURNAL_SCOPE",
+                    "this bundle was proposed under a different workspace; a bundle belongs to the "
+                    "workspace that first proposed it",
+                )
+            return
+        nonce = secrets.token_hex(16)
+        self.state = {
+            "schema_version": JOURNAL_SCHEMA,
+            "workspace_id": str(workspace_id),
+            "nonce": nonce,
+            "identity": canonical_sha256({"workspace_id": str(workspace_id), "nonce": nonce}),
+            "documents": {},
+            "operations": {},
+            "resources": {},
+            "etags": {},
+            "ids": {},
+            "through": None,
+        }
+        self.save()
+
+    def assert_pinned_documents_unchanged(self, digests: Mapping[str, str]) -> None:
+        pinned = self.state.get("documents", {})
+        drifted = sorted(
+            name for name, digest in digests.items() if name in pinned and pinned[name] != digest
+        )
+        if drifted:
+            raise ProposeError(
+                "THIN_PROPOSE_BUNDLE_DRIFTED",
+                f"{', '.join(drifted)} changed after the resource built from it was created, so "
+                "the resource Studio holds no longer describes the document; restore the document "
+                "to resume, or start a new bundle that adopts the created resources by id",
+            )
+
+    def pin(self, names: Sequence[str], digests: Mapping[str, str]) -> None:
+        for name in names:
+            if name in digests:
+                self.state.setdefault("documents", {})[name] = digests[name]
+
+    def save(self) -> None:
+        """Write the journal whole, through a temp file and one rename, mode 0600."""
+
+        self._dir.mkdir(mode=0o700, exist_ok=True)
+        rendered = json.dumps(self.state, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        staged = self._path.with_name(self._path.name + ".partial")
+        descriptor = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(descriptor, rendered)
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        os.chmod(staged, 0o600)
+        os.replace(staged, self._path)
+
+    def record_id(self, key: str, value: Any) -> None:
+        self.state.setdefault("ids", {})[key] = value
+
+    def record_stage(self, stage: str) -> None:
+        """Record the furthest stage this bundle reached. A shorter re-run never winds it back."""
+
+        reached = self.state.get("through")
+        if reached is None or STAGES.index(stage) > STAGES.index(reached):
+            self.state["through"] = stage
+        self.save()
+
+
+def read_journal(path: Path) -> dict[str, Any]:
+    """One propose journal, read under the plain-file rule, refused unless this client wrote it."""
+
+    try:
+        raw = read_plain_file(path, max_bytes=MAX_JOURNAL_BYTES)
+        parsed = parse_json(raw)
+    except (PlainFileRefusal, OSError, CanonicalJSONError) as error:
+        raise ProposeError(
+            "THIN_PROPOSE_JOURNAL_UNREADABLE",
+            f"the propose journal at {path} could not be read; move it aside to start a fresh "
+            "bundle",
+        ) from error
+    if not isinstance(parsed, dict) or parsed.get("schema_version") != JOURNAL_SCHEMA:
+        raise ProposeError(
+            "THIN_PROPOSE_JOURNAL_UNREADABLE",
+            f"the file at {path} is not a propose journal this client wrote",
+        )
+    return parsed
+
+
+def journal_ids(bundle: Path | str) -> dict[str, Any]:
+    """The ids one bundle's journal recorded, for ``research-open --bundle`` to read.
+
+    A bundle with no journal has registered nothing yet, and the refusal names the command that
+    registers it.
+    """
+
+    directory = Path(str(bundle)).expanduser()
+    path = directory / JOURNAL_DIR / JOURNAL_FILE
+    if not path.is_file():
+        raise ProposeError(
+            "THIN_PROPOSE_JOURNAL_UNREADABLE",
+            f"--bundle names {directory}, which has no propose journal at "
+            f"{JOURNAL_DIR}/{JOURNAL_FILE}; run mr-data propose --through sources against it first",
+        )
+    ids = read_journal(path).get("ids")
+    return dict(ids) if isinstance(ids, dict) else {}
+
+
+# --------------------------------------------------------------------------------------------
+# One journaled mutation, and one adoption
+# --------------------------------------------------------------------------------------------
+
+
+def _idempotency_key(identity: str, operation: str, request_digest: str) -> str:
+    """A deterministic idempotency key for one request of one bundle.
+
+    Derived from the bundle's identity -- which carries the journal's nonce, so no other bundle
+    can derive it -- the operation, and the request's own digest, the way ``hosted_deploy``
+    folds the whole request into its deployment identity. A crash and resume re-sends the
+    identical request under the identical key and Studio replays its first result; a corrected
+    request after a refusal gets a key of its own.
+    """
+
+    digest = hashlib.sha256(f"{operation}:{identity}:{request_digest}".encode()).hexdigest()
+    return f"mr-data.propose.v1:{digest}"
+
+
+def _drifted_fields(journaled: Mapping[str, Any], fields: Mapping[str, str]) -> str:
+    recorded = journaled.get("request_fields")
+    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 _mutate(
+    journal: Journal,
+    client: StudioProposeClient,
+    *,
+    name: str,
+    path: str,
+    build: Callable[[], Mapping[str, Any]],
+    expected: int,
+    document: str | None,
+    method: str = "POST",
+    if_match: str | None = None,
+    lost_answer_recoverable: bool = False,
+    refusal_remedy: Callable[[ThinLaneError], str | None] | None = None,
+) -> dict[str, Any]:
+    """Create one resource, or replay the one this bundle already holds.
+
+    ``document`` names the bundle document the request is built from, or ``None`` for the two
+    requests built from Studio's own answers (the proposal, the approval). A completed operation
+    built from a document is REBUILT on replay and held to the request that created it: the pin
+    on the document catches a change once its stage completed, but a stage that did not complete
+    -- one source registered, the next refused -- has pinned nothing, and a replay that trusted
+    the journal's position would hand the first source's id to whichever entry now sits there.
+    A mismatch is the document drift it is, named by document and operation. The two requests
+    built from Studio's answers are replayed without rebuilding: this client's own version and
+    Studio's fleet selection legitimately move between runs and are nobody's drift.
+
+    A planned operation whose answer was lost is re-sent under its own key, so Studio replays the
+    first result rather than creating a second resource; if the request it rebuilds is no longer
+    the one that was sent, it is refused, because that first request may have been applied --
+    unless ``lost_answer_recoverable`` says the caller already learned the outcome from Studio, in
+    which case a changed re-send is safe and goes out under its own key.
+    """
+
+    operations = journal.state["operations"]
+    resources = journal.state["resources"]
+    existing = resources.get(name)
+    if isinstance(existing, dict) and document is None:
+        return existing
+    try:
+        body = dict(build())
+        request_digest = canonical_sha256(body)
+        fields = {field: canonical_sha256(value) for field, value in body.items()}
+    except CanonicalJSONError as error:
+        raise ProposeError(
+            "THIN_PROPOSE_DOCUMENT_INVALID",
+            f"the {name} request cannot be canonicalised at {error.path}: {error.detail}",
+        ) from error
+    journaled = operations.get(name)
+    if isinstance(existing, dict):
+        recorded = journaled.get("request_digest") if isinstance(journaled, dict) else None
+        if recorded != request_digest:
+            raise ProposeError(
+                "THIN_PROPOSE_BUNDLE_DRIFTED",
+                f"{document} changed after {name} was created from it "
+                f"({_drifted_fields(journaled or {}, fields)} no longer match), so the resource "
+                "Studio holds no longer describes the document; restore the document to resume, "
+                "or start a new bundle that adopts the created resources by id",
+            )
+        return existing
+    if (
+        isinstance(journaled, dict)
+        and journaled.get("request_digest") != request_digest
+        and not lost_answer_recoverable
+    ):
+        raise ProposeError(
+            "THIN_PROPOSE_RESUME_UNCERTAIN",
+            f"{name} was sent before and its answer was lost, and "
+            f"{_drifted_fields(journaled, fields)} here no longer matches what was sent; that "
+            "request may have been applied, so restore "
+            f"{document or 'the request'} to resume it, or start a new bundle",
+        )
+    idempotency_key = _idempotency_key(journal.state["identity"], name, request_digest)
+    operations[name] = {
+        "operation": name,
+        "document": document,
+        "request_digest": request_digest,
+        "request_fields": fields,
+        "idempotency_key": idempotency_key,
+        "state": "planned",
+    }
+    journal.save()
+    captured: dict[str, str] = {}
+    try:
+        result = client.create(
+            path,
+            body,
+            idempotency_key=idempotency_key,
+            expected=expected,
+            method=method,
+            if_match=if_match,
+            response_headers=captured,
+        )
+    except ThinLaneError as refusal:
+        if _nothing_was_applied(refusal):
+            # Studio answered and applied nothing, so the plan is withdrawn and the document that
+            # produced it stays editable: the corrected request goes out under its own key.
+            del operations[name]
+            journal.save()
+            remedy = refusal_remedy(refusal) if refusal_remedy is not None else None
+            if remedy is not None:
+                refusal.detail = f"{refusal.detail}; {remedy}"
+                refusal.args = (f"{refusal.code}: {refusal.detail}",)
+        raise
+    resources[name] = result
+    etag = captured.get("etag")
+    if isinstance(etag, str) and etag:
+        journal.state.setdefault("etags", {})[name] = etag
+    operations[name] = {**operations[name], "state": "completed"}
+    journal.save()
+    return result
+
+
+def _adopt(
+    journal: Journal,
+    client: StudioProposeClient,
+    *,
+    name: str,
+    path: str,
+    check: Callable[[Mapping[str, Any]], None],
+    missing: str | None = None,
+) -> dict[str, Any]:
+    """Read one resource that already exists and hold it the way a created one is held.
+
+    ``missing`` is the sentence a 404 becomes, in the document's words, when the id named does
+    not resolve -- an adopted question whose requirements were never written, say -- so the
+    refusal names what to author rather than a route.
+    """
+
+    resources = journal.state["resources"]
+    existing = resources.get(name)
+    if isinstance(existing, dict):
+        journaled = journal.state["operations"].get(name, {})
+        if journaled.get("state") == "adopted" and journaled.get("path") != path:
+            raise ProposeError(
+                "THIN_PROPOSE_BUNDLE_DRIFTED",
+                f"the id {name} adopts changed after it was adopted; restore it, or start a new "
+                "bundle",
+            )
+        return existing
+    captured: dict[str, str] = {}
+    try:
+        record = client.read(path, response_headers=captured)
+    except ThinLaneError as refusal:
+        if refusal.code == "THIN_NOT_FOUND" and missing is not None:
+            raise ProposeError("THIN_PROPOSE_ADOPT_SCOPE", missing) from refusal
+        raise
+    if record.get("workspace_id") != journal.state["workspace_id"]:
+        raise ProposeError(
+            "THIN_PROPOSE_ADOPT_SCOPE",
+            f"the resource {name} names belongs to another workspace than this bundle's",
+        )
+    check(record)
+    resources[name] = record
+    etag = captured.get("etag")
+    if isinstance(etag, str) and etag:
+        journal.state.setdefault("etags", {})[name] = etag
+    # The path the resource was adopted from is journaled beside it, so a later run that adopts a
+    # different id under the same name is a drift rather than a silent substitution.
+    journal.state["operations"][name] = {"operation": name, "state": "adopted", "path": path}
+    journal.save()
+    return record
+
+
+# --------------------------------------------------------------------------------------------
+# The bodies, with the contract applied here
+# --------------------------------------------------------------------------------------------
+
+
+def _uuid_response(record: Mapping[str, Any], field: str, name: str) -> str:
+    value = record.get(field)
+    if not isinstance(value, str) or _UUID_TEXT.fullmatch(value) is None:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID", f"Studio answered {name} without a usable {field}"
+        )
+    return value
+
+
+def _text_response(record: Mapping[str, Any], field: str, name: str) -> str:
+    value = record.get(field)
+    if not isinstance(value, str) or not value:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID", f"Studio answered {name} without a usable {field}"
+        )
+    return value
+
+
+def dataset_body(dataset: Mapping[str, Any], *, workspace_id: UUID) -> dict[str, Any]:
+    return {"workspace_id": str(workspace_id), **dataset}
+
+
+def question_body(
+    question: Mapping[str, Any], *, workspace_id: UUID, dataset_id: str
+) -> dict[str, Any]:
+    return {
+        "workspace_id": str(workspace_id),
+        "dataset_id": dataset_id,
+        "question": question["question"],
+    }
+
+
+def requirements_body(question: Mapping[str, Any], *, workspace_id: UUID) -> dict[str, Any]:
+    return {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        **question["requirements"],
+    }
+
+
+def source_body(entry: Mapping[str, Any], *, workspace_id: UUID, dataset_id: str) -> dict[str, Any]:
+    return {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "dataset_id": dataset_id,
+        **{key: value for key, value in entry.items() if key != "connector"},
+    }
+
+
+def connector_body(
+    entry: Mapping[str, Any], *, workspace_id: UUID, source_id: str
+) -> dict[str, Any]:
+    connector = entry["connector"]
+    body: dict[str, Any] = {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "source_id": source_id,
+        "adapter_id": connector["adapter_id"],
+        "credential_mode": "none",
+        "crawler_egress_policy_attestation": CONNECTOR_EGRESS_ATTESTATION[connector["adapter_id"]],
+    }
+    if "query" in connector:
+        body["query"] = connector["query"]
+    return body
+
+
+def table_plan_body(
+    content: Mapping[str, Any],
+    *,
+    workspace_id: UUID,
+    dataset_id: str,
+    question_id: str,
+    requirements_id: str,
+    source_ids: Sequence[str],
+) -> dict[str, Any]:
+    return {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "dataset_id": dataset_id,
+        "question_id": question_id,
+        "requirements_id": requirements_id,
+        "source_ids": list(source_ids),
+        **content,
+    }
+
+
+def bootstrap_evidence(
+    *, version: str, research_session_id: str | None, research_run_id: str | None
+) -> dict[str, Any]:
+    evidence: dict[str, Any] = {"origin": HOSTED_BOOTSTRAP_ORIGIN, "harness_version": version}
+    if research_session_id is not None:
+        evidence["research_session_id"] = research_session_id
+    if research_run_id is not None:
+        evidence["research_run_id"] = research_run_id
+    return evidence
+
+
+def connector_authority(*, source_id: str, configuration: Mapping[str, Any]) -> dict[str, Any]:
+    """One connector source-authority binding, its digest derived exactly as Studio derives it.
+
+    Built from the connector configuration Studio holds -- adapter, digest, attestation -- so an
+    adopted configuration binds the same way a registered one does. ``source_authority_digest``
+    is the bare SHA-256 over the canonical binding with that field removed, the identical rule
+    ``hosted_deploy._source_authorities`` uses and ``_assert_recipe_source_authority_current``
+    recomputes on Studio's side, so the binding is the one the hosted worker is handed and checks
+    the recipe against at build time.
+    """
+
+    authority: dict[str, Any] = {
+        "source_id": source_id,
+        "authority_kind": "connector",
+        "adapter_id": _text_response(configuration, "adapter_id", "the connector configuration"),
+        "connector_configuration_id": _uuid_response(
+            configuration, "connector_configuration_id", "the connector configuration"
+        ),
+        "connector_configuration_digest": _text_response(
+            configuration, "configuration_digest", "the connector configuration"
+        ),
+        "credential_mode": "none",
+        "crawler_egress_policy_attestation": _text_response(
+            configuration, "crawler_egress_policy_attestation", "the connector configuration"
+        ),
+    }
+    authority["source_authority_digest"] = canonical_sha256(dict(authority))
+    return authority
+
+
+def proposal_body(
+    *,
+    recipe: Mapping[str, Any],
+    canonical_bytes: bytes,
+    recipe_digest: str,
+    activation: Mapping[str, Any],
+    workspace_id: UUID,
+    dataset_id: str,
+    table_plan_id: str,
+    source_authority_bindings: Sequence[Mapping[str, Any]],
+    evidence: Mapping[str, Any],
+) -> dict[str, Any]:
+    """The ``TableRecipeProposalCommand``, every coordinate read straight off the recipe."""
+
+    inventory_digest = canonical_sha256(
+        [
+            {
+                "source_id": item["source_id"],
+                "source_authority_digest": item["source_authority_digest"],
+            }
+            for item in source_authority_bindings
+        ]
+    )
+    return {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "dataset_id": dataset_id,
+        "table_plan_id": table_plan_id,
+        "recipe_media_type": RECIPE_MEDIA_TYPE,
+        "recipe_schema_version": recipe["schema_version"],
+        "table_recipe_id": recipe["recipe_id"],
+        "recipe_version": 1,
+        "predecessor_recipe_digest": None,
+        "canonical_recipe_json": canonical_bytes.decode("utf-8"),
+        "recipe_digest": recipe_digest,
+        "source_authority_bindings": [dict(item) for item in source_authority_bindings],
+        "source_authority_bindings_digest": inventory_digest,
+        "bootstrap_evidence": dict(evidence),
+        "activation_intent": {
+            "table_name": activation["table_name"],
+            "schedule": dict(activation["schedule"]),
+        },
+    }
+
+
+def preflight_body(
+    proposal: Mapping[str, Any], *, workspace_id: UUID, recipe_proposal_id: str
+) -> dict[str, Any]:
+    return {
+        "workspace_id": str(workspace_id),
+        "dataset_id": proposal["dataset_id"],
+        "table_plan_id": proposal["table_plan_id"],
+        "table_recipe_id": proposal["table_recipe_id"],
+        "recipe_version": proposal["recipe_version"],
+        "recipe_digest": proposal["recipe_digest"],
+        "recipe_proposal_id": recipe_proposal_id,
+    }
+
+
+def approval_body(
+    *,
+    workspace_id: UUID,
+    recipe_proposal_id: str,
+    recipe_digest: str,
+    preflight: Mapping[str, Any],
+) -> dict[str, Any]:
+    return {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "workspace_id": str(workspace_id),
+        "recipe_proposal_id": recipe_proposal_id,
+        "recipe_digest": recipe_digest,
+        "worker_policy_preflight": dict(preflight),
+    }
+
+
+# --------------------------------------------------------------------------------------------
+# The command
+# --------------------------------------------------------------------------------------------
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioProposeClient:
+    return StudioProposeClient(_session(args))
+
+
+def _through(args: argparse.Namespace) -> str:
+    stage = getattr(args, "through", None) or "approval"
+    if stage not in STAGES:
+        allowed = ", ".join(STAGES)
+        raise ProposeError("THIN_PROPOSE_STAGE_INVALID", f"--through is one of: {allowed}")
+    return stage
+
+
+def _research_session(args: argparse.Namespace, *, stage: str) -> str | None:
+    named = getattr(args, "research_session", None)
+    if named is None:
+        return None
+    try:
+        session_id = str(UUID(str(named)))
+    except (ValueError, AttributeError) as error:
+        raise ProposeError(
+            "THIN_PROPOSE_REQUEST_INVALID", f"{named!r} is not a research session identifier"
+        ) from error
+    if STAGES.index(stage) < STAGES.index("proposal"):
+        raise ProposeError(
+            "THIN_PROPOSE_REQUEST_INVALID",
+            "--research-session is sealed into the proposal, and --through "
+            f"{stage} stops before one exists; drop the flag, or run through the proposal",
+        )
+    return session_id
+
+
+class _Bundle:
+    """Every document a run needs, read and checked before a credential is resolved."""
+
+    def __init__(self, directory: Path, *, stage: str) -> None:
+        self.directory = directory
+        self.stage = stage
+        self.digests: dict[str, str] = {}
+        raw: dict[str, Any] = {}
+        for step, names in DOCUMENTS.items():
+            if STAGES.index(step) > STAGES.index(stage):
+                continue
+            for name in names:
+                raw[name], self.digests[name] = _read_document(directory, name)
+        self.dataset = check_dataset(raw["dataset.json"])
+        self.question = check_question(raw["question.json"]) if "question.json" in raw else None
+        self.sources = check_sources(raw["sources.json"]) if "sources.json" in raw else None
+        self.plan = check_table_plan(raw["table_plan.json"]) if "table_plan.json" in raw else None
+        self.recipe: dict[str, Any] | None = None
+        self.canonical_recipe = b""
+        self.recipe_digest = ""
+        if "recipe.json" in raw:
+            self.recipe, self.canonical_recipe, self.recipe_digest = check_recipe(
+                raw["recipe.json"]
+            )
+        self.activation = (
+            check_activation(raw["activation.json"]) if "activation.json" in raw else None
+        )
+        self.plan_content = (
+            plan_content(self.plan, self.recipe)
+            if self.plan is not None
+            and "table_plan_id" not in self.plan
+            and self.recipe is not None
+            else None
+        )
+
+    def reaches(self, step: str) -> bool:
+        return STAGES.index(self.stage) >= STAGES.index(step)
+
+
+def propose(
+    args: argparse.Namespace,
+    *,
+    client: StudioProposeClient | None = None,
+) -> dict[str, Any]:
+    """``mr-data propose``: author one hosted recipe proposal from a bundle, and open its approval.
+
+    Everything a client can settle on its own -- the bundle directory, the stage, the research
+    coordinate, every document each reached stage needs and its shape, this client's own version
+    -- is settled before a credential is resolved, so a mistyped path or a malformed document costs
+    a sentence rather than a token and a 422 several routes in. The journal makes every stage
+    idempotent: a re-run replays what was created, and a pinned document that changed is refused
+    with the document named.
+    """
+
+    directory = _bundle_directory(getattr(args, "bundle_dir", None))
+    stage = _through(args)
+    research_session_id = _research_session(args, stage=stage)
+    announce = getattr(args, "json", False) is False
+    bundle = _Bundle(directory, stage=stage)
+    version = harness_version() if bundle.reaches("proposal") else None
+
+    selected = client or _client(args)
+    workspace_id = selected.session.workspace_id
+    journal = Journal(directory)
+    journal.load_or_start(workspace_id=workspace_id)
+    journal.assert_pinned_documents_unchanged(bundle.digests)
+
+    def note(line: str) -> None:
+        if announce:
+            print(line, flush=True)
+
+    # dataset -------------------------------------------------------------------------------
+    adopted_dataset = "dataset_id" in bundle.dataset
+    if adopted_dataset:
+        dataset = _adopt(
+            journal,
+            selected,
+            name="dataset",
+            path=GET_DATASET_PATH.format(dataset_id=bundle.dataset["dataset_id"]),
+            check=lambda record: None,
+            missing="dataset.json adopts a Dataset this workspace does not hold",
+        )
+    else:
+        dataset = _mutate(
+            journal,
+            selected,
+            name="dataset",
+            path=CREATE_DATASET_PATH,
+            build=lambda: dataset_body(bundle.dataset, workspace_id=workspace_id),
+            expected=201,
+            document="dataset.json",
+            refusal_remedy=_dataset_conflict_remedy,
+        )
+    dataset_id = _uuid_response(dataset, "dataset_id", "the dataset")
+    journal.record_id("dataset_id", dataset_id)
+    journal.pin(PINS["dataset"], bundle.digests)
+    journal.record_stage("dataset")
+    note(f"dataset {dataset_id} {'adopted' if adopted_dataset else 'registered'}")
+    if stage == "dataset":
+        return _stage_receipt(selected, journal, stage=stage)
+
+    # question + requirements ---------------------------------------------------------------
+    question_document = bundle.question
+    assert question_document is not None
+    if "question_id" in question_document:
+
+        def _same_dataset(record: Mapping[str, Any]) -> None:
+            if record.get("dataset_id") != dataset_id:
+                raise ProposeError(
+                    "THIN_PROPOSE_ADOPT_SCOPE",
+                    "question.json adopts a question that belongs to another Dataset than this "
+                    "bundle's",
+                )
+
+        question = _adopt(
+            journal,
+            selected,
+            name="question",
+            path=GET_QUESTION_PATH.format(question_id=question_document["question_id"]),
+            check=_same_dataset,
+            missing="question.json adopts a question this workspace does not hold",
+        )
+        question_id = _uuid_response(question, "question_id", "the question")
+        requirements = _adopt(
+            journal,
+            selected,
+            name="requirements",
+            path=GET_REQUIREMENTS_PATH.format(question_id=question_id),
+            check=lambda record: None,
+            missing=(
+                "question.json adopts a question whose requirements were never written; author "
+                "the question and its requirements in question.json instead, or write the "
+                "requirements for that question first"
+            ),
+        )
+    else:
+        if adopted_dataset and "question" not in journal.state["resources"]:
+            _refuse_a_question_the_dataset_already_holds(
+                selected, dataset_id=dataset_id, text=question_document["question"]
+            )
+        question = _mutate(
+            journal,
+            selected,
+            name="question",
+            path=CREATE_QUESTION_PATH,
+            build=lambda: question_body(
+                question_document, workspace_id=workspace_id, dataset_id=dataset_id
+            ),
+            expected=201,
+            document="question.json",
+        )
+        question_id = _uuid_response(question, "question_id", "the question")
+        requirements = _mutate(
+            journal,
+            selected,
+            name="requirements",
+            path=PUT_REQUIREMENTS_PATH.format(question_id=question_id),
+            build=lambda: requirements_body(question_document, workspace_id=workspace_id),
+            expected=200,
+            document="question.json",
+            method="PUT",
+            if_match="*",
+        )
+    requirements_id = _uuid_response(requirements, "requirements_id", "the requirements")
+    journal.record_id("question_id", question_id)
+    journal.record_id("requirements_id", requirements_id)
+    journal.pin(PINS["question"], bundle.digests)
+    journal.record_stage("question")
+    note(f"question {question_id} recorded, with its requirements")
+    if stage == "question":
+        return _stage_receipt(selected, journal, stage=stage)
+
+    # sources + connectors ------------------------------------------------------------------
+    entries = bundle.sources
+    assert entries is not None
+    _refuse_a_registered_source_the_bundle_no_longer_names(journal, entries)
+    if adopted_dataset:
+        _refuse_sources_the_dataset_already_holds(
+            selected, journal, dataset_id=dataset_id, entries=entries
+        )
+    source_ids: dict[str, str] = {}
+    configurations: dict[str, dict[str, Any]] = {}
+    for entry in entries:
+        name = entry["name"]
+        if "source_id" in entry:
+
+            def _in_dataset(record: Mapping[str, Any], *, name: str = name) -> None:
+                if record.get("dataset_id") != dataset_id:
+                    raise ProposeError(
+                        "THIN_PROPOSE_ADOPT_SCOPE",
+                        f"sources.json {name!r} adopts a source registered under another Dataset "
+                        "than this bundle's",
+                    )
+
+            source = _adopt(
+                journal,
+                selected,
+                name=f"source:{name}",
+                path=GET_SOURCE_PATH.format(source_id=entry["source_id"]),
+                check=_in_dataset,
+                missing=f"sources.json {name!r} adopts a source this workspace does not hold",
+            )
+            source_id = _uuid_response(source, "source_id", f"the source {name!r}")
+
+            def _for_source(
+                record: Mapping[str, Any], *, expected: str = source_id, name: str = name
+            ) -> None:
+                if record.get("source_id") != expected:
+                    raise ProposeError(
+                        "THIN_PROPOSE_ADOPT_SCOPE",
+                        f"sources.json {name!r} adopts a connector configuration registered for "
+                        "another source",
+                    )
+
+            configuration = _adopt(
+                journal,
+                selected,
+                name=f"connector:{name}",
+                path=GET_CONNECTOR_PATH.format(
+                    connector_configuration_id=entry["connector_configuration_id"]
+                ),
+                check=_for_source,
+                missing=(
+                    f"sources.json {name!r} adopts a connector configuration this workspace "
+                    "does not hold"
+                ),
+            )
+        else:
+            source = _mutate(
+                journal,
+                selected,
+                name=f"source:{name}",
+                path=REGISTER_SOURCE_PATH,
+                build=lambda entry=entry: source_body(
+                    entry, workspace_id=workspace_id, dataset_id=dataset_id
+                ),
+                expected=201,
+                document="sources.json",
+            )
+            source_id = _uuid_response(source, "source_id", f"the source {name!r}")
+            configuration = _mutate(
+                journal,
+                selected,
+                name=f"connector:{name}",
+                path=REGISTER_CONNECTOR_PATH,
+                build=lambda entry=entry, source_id=source_id: connector_body(
+                    entry, workspace_id=workspace_id, source_id=source_id
+                ),
+                expected=201,
+                document="sources.json",
+            )
+        source_ids[name] = source_id
+        configurations[source_id] = configuration
+        note(f"source {name!r} is {source_id}, with its connector")
+    journal.record_id("sources", source_ids)
+    journal.record_id("source_ids", list(source_ids.values()))
+    journal.pin(PINS["sources"], bundle.digests)
+    journal.record_stage("sources")
+    if stage == "sources":
+        return _stage_receipt(selected, journal, stage=stage)
+
+    # the recipe against the registered sources, and the session it was explored in ---------
+    recipe = bundle.recipe
+    assert recipe is not None
+    _check_recipe_sources(recipe, source_ids=source_ids, configurations=configurations)
+    research_run_id: str | None = None
+    if research_session_id is not None:
+        record = _lookup_session(
+            selected, research_session_id, dataset_id=dataset_id, question_id=question_id
+        )
+        research_run_id = _uuid_response(record, "run_id", "the research session")
+
+    # plan ----------------------------------------------------------------------------------
+    plan_document = bundle.plan
+    assert plan_document is not None
+    if "table_plan_id" in plan_document:
+
+        def _binds_this_bundle(record: Mapping[str, Any]) -> None:
+            if record.get("dataset_id") != dataset_id or record.get("question_id") != question_id:
+                raise ProposeError(
+                    "THIN_PROPOSE_ADOPT_SCOPE",
+                    "table_plan.json adopts a plan that binds another Dataset or question than "
+                    "this bundle's",
+                )
+            if record.get("requirements_id") != requirements_id:
+                raise ProposeError(
+                    "THIN_PROPOSE_ADOPT_SCOPE",
+                    "table_plan.json adopts a plan bound to other requirements than this "
+                    "bundle's question carries",
+                )
+            planned_sources = record.get("source_ids")
+            if not isinstance(planned_sources, list) or set(planned_sources) != set(
+                source_ids.values()
+            ):
+                raise ProposeError(
+                    "THIN_PROPOSE_ADOPT_SCOPE",
+                    "table_plan.json adopts a plan whose sources are not the sources this bundle "
+                    "registered or adopted",
+                )
+
+        plan = _adopt(
+            journal,
+            selected,
+            name="plan",
+            path=GET_TABLE_PLAN_PATH.format(table_plan_id=plan_document["table_plan_id"]),
+            check=_binds_this_bundle,
+            missing="table_plan.json adopts a plan this workspace does not hold",
+        )
+    else:
+        content = bundle.plan_content
+        assert content is not None
+        plan = _mutate(
+            journal,
+            selected,
+            name="plan",
+            path=CREATE_TABLE_PLAN_PATH,
+            build=lambda: table_plan_body(
+                content,
+                workspace_id=workspace_id,
+                dataset_id=dataset_id,
+                question_id=question_id,
+                requirements_id=requirements_id,
+                source_ids=list(source_ids.values()),
+            ),
+            expected=201,
+            # The plan's digests derive from the recipe, so a recipe that moved after the plan
+            # was created is a drift of this operation too, and the sentence names both.
+            document="table_plan.json or recipe.json",
+        )
+    table_plan_id = _uuid_response(plan, "table_plan_id", "the table plan")
+    journal.record_id("table_plan_id", table_plan_id)
+    journal.pin(PINS["plan"], bundle.digests)
+    journal.record_stage("plan")
+    note(f"table plan {table_plan_id} in place")
+    if stage == "plan":
+        return _stage_receipt(selected, journal, stage=stage)
+
+    # proposal ------------------------------------------------------------------------------
+    activation = bundle.activation
+    assert activation is not None and version is not None
+    _check_plan_describes_recipe(plan, recipe)
+    bindings = sorted(
+        (
+            connector_authority(source_id=source_id, configuration=configurations[source_id])
+            for source_id in source_ids.values()
+        ),
+        key=lambda item: item["source_id"],
+    )
+    command = proposal_body(
+        recipe=recipe,
+        canonical_bytes=bundle.canonical_recipe,
+        recipe_digest=bundle.recipe_digest,
+        activation=activation,
+        workspace_id=workspace_id,
+        dataset_id=dataset_id,
+        table_plan_id=table_plan_id,
+        source_authority_bindings=bindings,
+        evidence=bootstrap_evidence(
+            version=version,
+            research_session_id=research_session_id,
+            research_run_id=research_run_id,
+        ),
+    )
+    proposal = _mutate(
+        journal,
+        selected,
+        name="proposal",
+        path=CREATE_RECIPE_PROPOSAL_PATH,
+        build=lambda: command,
+        expected=201,
+        document=None,
+    )
+    recipe_proposal_id = _uuid_response(proposal, "recipe_proposal_id", "the recipe proposal")
+    recipe_digest = _text_response(proposal, "recipe_digest", "the recipe proposal")
+    if recipe_digest != bundle.recipe_digest and "recipe_digest" not in journal.state["ids"]:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID",
+            "Studio stored a recipe digest other than the one computed from recipe.json",
+        )
+    journal.record_id("recipe_proposal_id", recipe_proposal_id)
+    journal.record_id("recipe_digest", recipe_digest)
+    journal.pin(PINS["proposal"], bundle.digests)
+    journal.record_stage("proposal")
+    note(f"recipe proposal {recipe_proposal_id} holds recipe digest {recipe_digest}")
+    if stage == "proposal":
+        return _proposal_receipt(selected, journal, stage=stage)
+
+    # approval ------------------------------------------------------------------------------
+    # An approval this bundle already opened is replayed from the journal. Otherwise the proposal
+    # is read back first -- for the ETag the ask is pinned to, which the create never carries,
+    # and because the proposal is where Studio records an approval whose answer was lost: one it
+    # already holds is adopted rather than asked for again. The preflight is a stateless resolve
+    # that Studio's fleet can move between runs, so it is asked for only when the ask is still to
+    # be made, and a re-send after a lost answer is safe because the outcome was just read.
+    if not isinstance(journal.state["resources"].get("approval"), dict):
+        proposal_etag, held = _proposal_state(selected, journal, recipe_proposal_id, recipe_digest)
+        if held is not None:
+            _adopt_approval(journal, selected, held)
+        else:
+            preflight = selected.worker_policy_preflight(
+                preflight_body(
+                    command, workspace_id=workspace_id, recipe_proposal_id=recipe_proposal_id
+                )
+            )
+            _mutate(
+                journal,
+                selected,
+                name="approval",
+                path=REQUEST_RECIPE_APPROVAL_PATH.format(recipe_proposal_id=recipe_proposal_id),
+                build=lambda: approval_body(
+                    workspace_id=workspace_id,
+                    recipe_proposal_id=recipe_proposal_id,
+                    recipe_digest=recipe_digest,
+                    preflight=preflight,
+                ),
+                expected=201,
+                document=None,
+                if_match=proposal_etag,
+                lost_answer_recoverable=True,
+            )
+    approval = journal.state["resources"]["approval"]
+    approval_request_id = _uuid_response(approval, "approval_request_id", "the approval request")
+    journal.record_id("approval_request_id", approval_request_id)
+    journal.record_stage("approval")
+    note(f"approval request {approval_request_id} open")
+    return _proposal_receipt(selected, journal, stage="approval")
+
+
+def _dataset_conflict_remedy(refusal: ThinLaneError) -> str | None:
+    """What to do when Studio will not register a second Dataset of this name.
+
+    The commonest way to meet this is a bundle whose journal is gone: the Dataset was registered
+    by an earlier run and nothing remembers it. The remedy is the id, not a new name.
+    """
+
+    if getattr(refusal, "http_status", None) != 409:
+        return None
+    return (
+        "a Dataset of this name already exists in the workspace; if an earlier run of this bundle "
+        'registered it, adopt it by id in dataset.json ({"dataset_id": "..."}) -- '
+        "mr-data list names the workspace's datasets -- or choose another name"
+    )
+
+
+def _refuse_a_question_the_dataset_already_holds(
+    client: StudioProposeClient, *, dataset_id: str, text: str
+) -> None:
+    """Under an adopted Dataset, a question whose text the Dataset already holds is adopted, not
+    registered again.
+
+    This is the lost-journal case one step on: the Dataset was adopted by id, and the question
+    that went with it would be registered a second time in silence. The list is one page of the
+    Dataset's own questions -- the bound Studio's list route has -- which is every question a
+    bundle could have registered.
+    """
+
+    for question in client._call_list(
+        "/v3/questions", query={"dataset_id": dataset_id, "limit": 200}
+    ):
+        if question.get("text") == text and isinstance(question.get("question_id"), str):
+            raise ProposeError(
+                "THIN_PROPOSE_ADOPT_REQUIRED",
+                f"the adopted Dataset already holds this question as {question['question_id']}; "
+                'adopt it in question.json ({"question_id": "..."}) rather than registering it '
+                "again",
+            )
+
+
+def _refuse_sources_the_dataset_already_holds(
+    client: StudioProposeClient,
+    journal: Journal,
+    *,
+    dataset_id: str,
+    entries: Sequence[Mapping[str, Any]],
+) -> None:
+    """Under an adopted Dataset, a source whose name the Dataset already holds is adopted, not
+    registered again -- the same lost-journal case, for the sources."""
+
+    authored = {
+        entry["name"]
+        for entry in entries
+        if "source_id" not in entry and f"source:{entry['name']}" not in journal.state["resources"]
+    }
+    if not authored:
+        return
+    for source in client._call_list(REGISTER_SOURCE_PATH, query={"limit": 200}):
+        if source.get("dataset_id") != dataset_id or source.get("name") not in authored:
+            continue
+        source_id = source.get("source_id")
+        raise ProposeError(
+            "THIN_PROPOSE_ADOPT_REQUIRED",
+            f"the adopted Dataset already holds a source named {source.get('name')!r} as "
+            f'{source_id}; adopt it in sources.json ({{"name": ..., "source_id": '
+            f'"{source_id}", "connector_configuration_id": "..."}}) -- '
+            f"GET /v3/connector-configurations?source_id={source_id} names its configuration -- "
+            "rather than registering it again",
+        )
+
+
+def _refuse_a_registered_source_the_bundle_no_longer_names(
+    journal: Journal, entries: Sequence[Mapping[str, Any]]
+) -> None:
+    """A source this bundle registered and then stopped naming is a drift, not an orphan.
+
+    Sources are journaled by the name the author gave them, so reordering the list is harmless
+    and renaming an entry after its source was registered is not: the registered source would be
+    left behind and a second one registered under the new name. Naming the missing one is the
+    whole of the remedy.
+    """
+
+    named = {entry["name"] for entry in entries}
+    registered = sorted(
+        operation[len("source:") :]
+        for operation, journaled in journal.state["operations"].items()
+        if operation.startswith("source:") and journaled.get("state") in {"completed", "adopted"}
+    )
+    missing = [name for name in registered if name not in named]
+    if missing:
+        raise ProposeError(
+            "THIN_PROPOSE_BUNDLE_DRIFTED",
+            f"sources.json no longer names {', '.join(repr(name) for name in missing)}, which this "
+            "bundle already registered; restore the entry under that name, or start a new bundle",
+        )
+
+
+def _check_recipe_sources(
+    recipe: Mapping[str, Any],
+    *,
+    source_ids: Mapping[str, str],
+    configurations: Mapping[str, Mapping[str, Any]],
+) -> None:
+    """The recipe names exactly the registered sources, each under its connector's adapter."""
+
+    registered = set(source_ids.values())
+    named = {item["source_id"]: item for item in recipe["sources"]}
+    if set(named) != registered:
+        raise ProposeError(
+            "THIN_PROPOSE_SOURCE_INVENTORY",
+            "recipe.json sources must reference exactly the registered source ids "
+            f"({', '.join(sorted(registered))}); author recipe.json after "
+            "`mr-data propose --through sources` and reference the ids the journal recorded",
+        )
+    for source_id, source in named.items():
+        adapter_id = configurations[source_id].get("adapter_id")
+        if source.get("adapter_id") != adapter_id:
+            raise ProposeError(
+                "THIN_PROPOSE_SOURCE_INVENTORY",
+                f"recipe.json names source {source_id} under adapter {source.get('adapter_id')!r}, "
+                f"but its connector is registered as {adapter_id!r}",
+            )
+
+
+def _check_plan_describes_recipe(plan: Mapping[str, Any], recipe: Mapping[str, Any]) -> None:
+    """The plan Studio holds -- created earlier, or adopted -- still describes this recipe."""
+
+    expected = {
+        "plan_digest": execution_plan_digest(recipe),
+        "validation_policy_digest": validation_policy_digest(recipe),
+    }
+    stale = sorted(field for field, value in expected.items() if plan.get(field) != value)
+    if stale:
+        raise ProposeError(
+            "THIN_PROPOSE_PLAN_DIGEST",
+            f"the table plan's {', '.join(stale)} no longer describes recipe.json: the plan was "
+            "built from an earlier recipe; restore that recipe, or start a new bundle that adopts "
+            "the Dataset, question and sources by id and creates a plan for this one",
+        )
+
+
+def _lookup_session(
+    client: StudioProposeClient, session_id: str, *, dataset_id: str, question_id: str
+) -> dict[str, Any]:
+    """The research session named as evidence, held to what Studio will hold it to.
+
+    Read before the plan exists rather than at the proposal, so a session that explored another
+    Dataset, that failed, or that probed nothing is a sentence here and not a 409 after the plan
+    has been created -- every one of these is a check Studio makes on the proposal.
+    """
+
+    record = client.read(GET_SESSION_PATH.format(session_id=session_id))
+    if record.get("session_id") != session_id:
+        raise ProposeError(
+            "THIN_PROPOSE_REQUEST_INVALID",
+            "Studio answered about a different research session than the one named as evidence",
+        )
+    context = record.get("context")
+    if not isinstance(context, Mapping) or context.get("dataset_id") != dataset_id:
+        raise ProposeError(
+            "THIN_PROPOSE_RESEARCH_SESSION",
+            "--research-session names a session that explored another Dataset than this bundle's",
+        )
+    if context.get("question_id") != question_id:
+        raise ProposeError(
+            "THIN_PROPOSE_RESEARCH_SESSION",
+            "--research-session names a session that explored another question than this bundle's",
+        )
+    if record.get("state") == "failed":
+        raise ProposeError(
+            "THIN_PROPOSE_RESEARCH_SESSION",
+            "--research-session names a session that failed; its run holds no probe results",
+        )
+    submitted = record.get("probes_submitted")
+    if type(submitted) is not int or submitted < 1:
+        raise ProposeError(
+            "THIN_PROPOSE_RESEARCH_SESSION",
+            "--research-session names a session that submitted no probe; it explored nothing "
+            "this recipe could rest on",
+        )
+    return record
+
+
+def _proposal_state(
+    client: StudioProposeClient, journal: Journal, recipe_proposal_id: str, recipe_digest: str
+) -> tuple[str, dict[str, Any] | None]:
+    """The proposal's current ETag, and the approval Studio already holds for it, if any.
+
+    Read EVERY time the approval is still to be opened, never from the journal: the proposal's
+    version moves when an approval is requested, so an ETag journaled before a lost answer is
+    exactly the stale one a 412 would refuse forever. And the proposal is where Studio records the
+    approval a lost ``POST`` did open -- ``approval_request_id`` on the proposal -- so reading it
+    is how that outcome is learned rather than asked for twice.
+    """
+
+    captured: dict[str, str] = {}
+    record = client.recipe_proposal(recipe_proposal_id, response_headers=captured)
+    if record.get("recipe_proposal_id") != recipe_proposal_id:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID", "Studio answered about a different recipe proposal"
+        )
+    if record.get("recipe_digest") != recipe_digest:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID",
+            "the recipe proposal Studio holds no longer carries the recipe digest this bundle "
+            "proposed",
+        )
+    etag = captured.get("etag")
+    if not isinstance(etag, str) or not etag:
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID",
+            "Studio answered the proposal without an ETag, and the approval ask must be pinned "
+            "to the exact proposal version it was made against",
+        )
+    journal.state.setdefault("etags", {})["proposal"] = etag
+    journal.save()
+    held = record.get("approval_request_id")
+    if isinstance(held, str) and _UUID_TEXT.fullmatch(held) is not None:
+        return etag, client.read(GET_APPROVAL_PATH.format(approval_request_id=held))
+    return etag, None
+
+
+def _adopt_approval(
+    journal: Journal, client: StudioProposeClient, record: Mapping[str, Any]
+) -> None:
+    """Hold the approval Studio already opened for this proposal as this bundle's own."""
+
+    approval_request_id = _uuid_response(record, "approval_request_id", "the approval request")
+    journal.state["resources"]["approval"] = dict(record)
+    journal.state["operations"].pop("approval", None)
+    journal.state["operations"]["approval"] = {
+        "operation": "approval",
+        "state": "adopted",
+        "path": GET_APPROVAL_PATH.format(approval_request_id=approval_request_id),
+    }
+    journal.save()
+
+
+# --------------------------------------------------------------------------------------------
+# The receipts
+# --------------------------------------------------------------------------------------------
+
+
+def _common(client: StudioProposeClient, journal: Journal, *, stage: str) -> dict[str, Any]:
+    ids = dict(journal.state.get("ids", {}))
+    payload = {
+        "schema_version": PROPOSE_SCHEMA,
+        "lane": "hosted",
+        "bundle": str(journal.path.parent.parent),
+        "journal": str(journal.path),
+        "through": stage,
+        "workspace_id": journal.state["workspace_id"],
+        "ids": ids,
+    }
+    dataset_id = ids.get("dataset_id")
+    if isinstance(dataset_id, str):
+        payload["dataset_dashboard_url"] = dataset_dashboard_url(
+            client.session.cloud_url, dataset_id
+        )
+    return payload
+
+
+def _stage_receipt(client: StudioProposeClient, journal: Journal, *, stage: str) -> dict[str, Any]:
+    """The receipt for a ``--through`` stop before the proposal exists.
+
+    Its status is ``authoring_stage_complete`` for every one of the four early stages, and the
+    payload names which. After ``--through sources`` it carries the registered source ids under
+    ``ids.sources`` so the agent can write ``recipe.json`` against them; that is the whole reason
+    the stage exists.
+    """
+
+    payload = _common(client, journal, stage=stage)
+    payload["status"] = "authoring_stage_complete"
+    next_stage = STAGES[STAGES.index(stage) + 1]
+    payload["note"] = (
+        f"Stopped after the {stage} stage. Re-run mr-data propose to continue through the "
+        f"{next_stage} stage"
+        + (
+            "; the registered source ids are under ids.sources for recipe.json to reference"
+            if stage == "sources"
+            else ""
+        )
+        + "."
+    )
+    return payload
+
+
+def _proposal_receipt(
+    client: StudioProposeClient, journal: Journal, *, stage: str
+) -> dict[str, Any]:
+    """The receipt once the proposal exists: the proposal, its digest, and what settles it.
+
+    When the approval was opened too, the receipt reads the approval back and says which of four
+    things is true, because each is a different next step: the approval is still PENDING, and a
+    person settles it at the dashboard address (exit 2); it is APPROVED and no Build has started,
+    and ``mr-data build --hosted`` queues one; it is approved and the confirmation STARTED the
+    Build in the same act -- Studio #124 -- and the run is named here because ``mr-data build``
+    would refuse it rather than replay it; or it was declined (exit 2). Both commands carry
+    ``--hosted``, because on a full install the bare names are the local lane's. Nothing here
+    decides anything.
+    """
+
+    payload = _common(client, journal, stage=stage)
+    ids = journal.state.get("ids", {})
+    recipe_proposal_id = ids.get("recipe_proposal_id")
+    recipe_digest = ids.get("recipe_digest")
+    payload["recipe_proposal_id"] = recipe_proposal_id
+    payload["recipe_digest"] = recipe_digest
+    build_command = (
+        f"mr-data build --recipe-proposal {recipe_proposal_id} --recipe-digest {recipe_digest} "
+        "--hosted"
+    )
+    if stage == "proposal":
+        payload["status"] = "recipe_proposed"
+        payload["build_command"] = build_command
+        payload["note"] = (
+            "The recipe proposal exists and nothing has approved it. Re-run mr-data propose to "
+            "open its approval; then a person settles it and you build."
+        )
+        return payload
+    approval_request_id = str(ids.get("approval_request_id"))
+    payload["approval_request_id"] = approval_request_id
+    payload["dashboard_url"] = approval_dashboard_url(client.session.cloud_url, approval_request_id)
+    payload["never_decides"] = (
+        "this command opened an approval; it did not grant one. A Table recipe is confirmed by a "
+        "signed-in editor in the dashboard, which the command line cannot be."
+    )
+    approval = client.read(GET_APPROVAL_PATH.format(approval_request_id=approval_request_id))
+    approval_status = approval.get("status")
+    payload["approval_status"] = approval_status
+    if approval_status == "pending":
+        payload["status"] = "recipe_proposal_approval_requested"
+        payload["approve_command"] = (
+            f"mr-data recipe-approve --recipe {approval_request_id} "
+            '--reason "why you are asking" --hosted'
+        )
+        payload["build_command"] = build_command
+        payload["note"] = (
+            "The proposal is open and waiting on a person. Open the dashboard address above, or "
+            "run the recipe-approve command, so a human settles it; then build with the build "
+            "command -- unless their confirmation started the Build, which re-running this "
+            "command reports."
+        )
+        return payload
+    if approval_status != "approved":
+        payload["status"] = "recipe_proposal_not_approved"
+        payload["note"] = (
+            f"The approval settled as {approval_status}; nothing will build from this proposal. "
+            "Author the recipe again in a new bundle that adopts the Dataset, question and "
+            "sources by id."
+        )
+        return payload
+    started = client.approval_start(approval_request_id)
+    if started is None:
+        payload["status"] = "recipe_proposal_approved"
+        payload["build_command"] = build_command
+        payload["note"] = (
+            "A person approved the recipe and no Build has been started for it; queue the first "
+            "hosted Build with the build command. It replays to the same run if one is started "
+            "meanwhile."
+        )
+        return payload
+    run = started.get("run") if isinstance(started.get("run"), Mapping) else {}
+    run_id = run.get("run_id")
+    if not isinstance(run_id, str):
+        raise ProposeError(
+            "THIN_PROPOSE_RESPONSE_INVALID", "Studio named a started Build without a run"
+        )
+    payload["status"] = "recipe_build_queued"
+    payload["run_id"] = run_id
+    payload["run_dashboard_url"] = run_dashboard_url(client.session.cloud_url, run_id)
+    payload["watch_command"] = f"mr-data watch {run_id} --hosted"
+    payload["note"] = (
+        "The confirmation started the first hosted Build in the same act; there is nothing left "
+        "to queue, and mr-data build would refuse rather than repeat it. Follow this run."
+    )
+    return payload
+
+
+def propose_exit_code(payload: Mapping[str, Any]) -> int:
+    """``0`` when the requested work is done, ``2`` when a person still has to decide, or did not.
+
+    A ``--through`` stop before the approval, a proposal created without opening its approval, an
+    approved proposal, and a Build the approval already started all did exactly what was asked
+    and exit 0. An approval a human has not settled exits 2 and names the dashboard, the way
+    ``mr-data approve`` exits 2 while an ask is pending -- because a script gating on this must
+    not read "asked" as "approved" -- and so does one a human declined.
+    """
+
+    if payload.get("status") in {
+        "recipe_proposal_approval_requested",
+        "recipe_proposal_not_approved",
+    }:
+        return 2
+    return 0
+
+
+# --------------------------------------------------------------------------------------------
+# The command line, declared once for both parsers
+# --------------------------------------------------------------------------------------------
+
+COMMAND = "propose"
+COMMAND_HELP = "author one hosted recipe proposal from a bundle and open its approval"
+
+
+def declare_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add ``propose``'s arguments to ``parser``.
+
+    Called by both front doors -- the thin router's parser and ``cli``'s -- so the argument surface
+    is declared once and the two cannot disagree, the property ``note`` and the research commands
+    have by the same construction.
+    """
+
+    parser.add_argument(
+        "bundle_dir",
+        help="the directory holding the documents to author from; its .mr-data journal is written "
+        "here",
+    )
+    parser.add_argument(
+        "--through",
+        choices=STAGES,
+        help="stop after this stage instead of opening the approval; "
+        "--through sources registers the sources first so recipe.json can reference their ids",
+    )
+    parser.add_argument(
+        "--research-session",
+        dest="research_session",
+        metavar="UUID",
+        help="the research session this recipe was explored in; its id and run are sealed into "
+        "the hosted bootstrap evidence",
+    )
+
+
+__all__ = [
+    "COMMAND",
+    "COMMAND_HELP",
+    "CREATE_DATASET_PATH",
+    "CREATE_QUESTION_PATH",
+    "CREATE_RECIPE_PROPOSAL_PATH",
+    "CREATE_TABLE_PLAN_PATH",
+    "DEFAULT_SCHEDULE",
+    "GET_CONNECTOR_PATH",
+    "GET_DATASET_PATH",
+    "GET_QUESTION_PATH",
+    "GET_RECIPE_PROPOSAL_PATH",
+    "GET_REQUIREMENTS_PATH",
+    "GET_SOURCE_PATH",
+    "GET_TABLE_PLAN_PATH",
+    "HOSTED_BOOTSTRAP_ORIGIN",
+    "JOURNAL_DIR",
+    "JOURNAL_FILE",
+    "JOURNAL_SCHEMA",
+    "MAX_DOCUMENT_BYTES",
+    "MAX_JOURNAL_BYTES",
+    "PINS",
+    "PROPOSE_SCHEMA",
+    "PUT_REQUIREMENTS_PATH",
+    "RECIPE_MEDIA_TYPE",
+    "RECIPE_SCHEMA_VERSIONS",
+    "REGISTER_CONNECTOR_PATH",
+    "REGISTER_SOURCE_PATH",
+    "REQUEST_RECIPE_APPROVAL_PATH",
+    "STAGES",
+    "WORKER_POLICY_PREFLIGHT_PATH",
+    "Journal",
+    "ProposeError",
+    "StudioProposeClient",
+    "approval_body",
+    "backfill_policy_digest",
+    "bootstrap_evidence",
+    "check_activation",
+    "check_dataset",
+    "check_question",
+    "check_recipe",
+    "check_sources",
+    "check_table_plan",
+    "connector_authority",
+    "connector_body",
+    "dataset_body",
+    "declare_arguments",
+    "execution_plan_digest",
+    "harness_version",
+    "journal_ids",
+    "plan_content",
+    "preflight_body",
+    "proposal_body",
+    "propose",
+    "propose_exit_code",
+    "question_body",
+    "read_journal",
+    "requirements_body",
+    "source_body",
+    "table_plan_body",
+    "validation_policy_digest",
+]