mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/parity.py

@@ -0,0 +1,1070 @@
+"""The read, compare and view commands, answered from Studio instead of from a folder.
+
+WHAT THIS MODULE IS FOR. ADR 0021 requires every lane to be reachable through hosted dispatch
+with the same vocabulary and the same receipts, so that *where* a command runs stops being
+something a person has to know. :mod:`mostlyright.data_harness.thin.commands` does that for the
+five commands that submit, follow and fetch a run. These ten are the other half of a working day:
+looking at what you have, checking it, comparing two of them, and reading the notebook.
+
+THE ONE TRANSLATION, STATED ONCE. Every command here takes a run identifier where its local twin
+takes a folder. That is the whole difference in the vocabulary, and it is not a new flag or a new
+name -- a hosted build has no folder, and the run identifier is what the submission printed and
+what the dashboard address contains. Everything else is held identical on purpose: the same
+status words, so ``mr-data show --json`` answers with ``build_shown`` in both profiles; the same
+payload keys wherever the fact exists on both sides; and the same numbered-key convention, where
+a fact about the data goes in a value and never in a key.
+
+WHERE A FLAG CANNOT MEAN WHAT IT MEANS LOCALLY. It is accepted and reported, never refused. A
+flag that errors is a script that breaks on a machine that installed a different extra, which is
+exactly the variance this phase exists to remove. Each such flag lands in ``flags_without_effect``
+with the sentence saying why -- ``mr-data list --depth 3 --hosted`` runs, lists the workspace's
+runs, and says that folder depth described nothing here.
+
+WHAT THESE COMMANDS NEVER DO. They never mutate. Every route below is a GET, so an interrupted
+``show`` and an interrupted ``verify`` leave a workspace exactly as they found it, and none of
+them can be the reason a run changed state.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+from mostlyright.data_harness.thin.commands import (
+    artifact_records,
+    media_type_essence,
+    optional_receipt,
+    run_receipt,
+    suffix_for,
+)
+from mostlyright.data_harness.thin.download import download_signed_artifact
+from mostlyright.data_harness.thin.runs import StudioRunClient
+from mostlyright.data_harness.thin.session import (
+    StudioSession,
+    open_studio_session,
+    run_dashboard_url,
+)
+from mostlyright.data_harness.thin.stream import TERMINAL_RUN_STATUSES
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+
+SHOW_SCHEMA = f"{THIN_SCHEMA_PREFIX}-build-shown.v1"
+LIST_SCHEMA = f"{THIN_SCHEMA_PREFIX}-builds-listed.v1"
+INSPECT_SCHEMA = f"{THIN_SCHEMA_PREFIX}-build-inspected.v1"
+VERIFY_SCHEMA = f"{THIN_SCHEMA_PREFIX}-build-verified.v1"
+DIFF_SCHEMA = f"{THIN_SCHEMA_PREFIX}-build-comparison.v1"
+FLEET_SCHEMA = f"{THIN_SCHEMA_PREFIX}-fleet.v1"
+NOTEBOOK_SCHEMA = f"{THIN_SCHEMA_PREFIX}-notebook.v1"
+PEEK_SCHEMA = f"{THIN_SCHEMA_PREFIX}-peek.v1"
+DEPLOYMENT_STATUS_SCHEMA = f"{THIN_SCHEMA_PREFIX}-deployment-run-status.v1"
+
+#: Where a hosted notebook lands when the caller did not choose. A folder rather than a file,
+#: because one run renders two documents and writing either over the other would be a lie about
+#: which one is there.
+DEFAULT_NOTEBOOK_OUTPUT = "hosted-notebook"
+
+# --------------------------------------------------------------------------------------------
+# Words this lane must not invent
+# --------------------------------------------------------------------------------------------
+#
+# Both blocks below restate strings the local lane already owns, because the modules that hold
+# them (`ux.readers`, `fleet`) cannot be imported on a thin install -- they reach the engine. A
+# restated string is a string that can drift, so `tests/test_thin_parity.py` asserts each one is
+# byte-identical to its original, which runs on a full install and can import both.
+
+#: ``ux.readers.LISTED_ONLY`` / ``VERIFIED``. A hosted listing is Studio's own reading of its own
+#: runs, so it is never "listed, not verified" in the local sense -- but it is also not a replay,
+#: and saying "verified" about bytes nobody re-hashed here would be the claim `--verify` exists to
+#: avoid making. The listing says what it is: Studio's verdict, read.
+LISTED_ONLY = "listed, not verified"
+VERIFIED = "verified"
+NOT_ALL_VERIFIED = "not all verified"
+NOTHING_TO_VERIFY = "nothing to verify"
+
+#: ``fleet._WAITING``, ``fleet._FIXES_REASON``, and the two failure sentences beside them.
+FLEET_WAITING = "waiting for a person to look at it"
+FLEET_FIXES = "reviewed: the review asked for fixes"
+FLEET_FAILED = "stopped: the build failed"
+
+#: Studio's Run status -> the plain state word ``fleet`` prints for a local run. Every one of the
+#: thirteen is named: a state with no word here would print a state word this product does not
+#: use, and a fleet view that shows one row in Studio's vocabulary and the rest in ours is worse
+#: than one that shows all thirteen in either.
+FLEET_STATE: dict[str, str] = {
+    "queued": "not started",
+    "producer_retry_pending": "not started",
+    "running": "building",
+    "awaiting_candidate_selection": "built",
+    "verifying": "built",
+    "verifier_retry_pending": "built",
+    "releasable": "reviewed",
+    "released": "reviewed",
+    "repair_required": "stopped",
+    "human_direction_required": "stopped",
+    "failed": "stopped",
+    "cancelled": "stopped",
+    "abandoned": "stopped",
+}
+
+#: The states that are waiting on a person, and the sentence each one gets. A state absent here
+#: needs nobody: it is either moving on its own or finished.
+FLEET_NEEDS_A_PERSON: dict[str, str] = {
+    "releasable": FLEET_WAITING,
+    "repair_required": FLEET_FIXES,
+    "human_direction_required": FLEET_WAITING,
+    "failed": FLEET_FAILED,
+}
+
+
+# --------------------------------------------------------------------------------------------
+# Shared plumbing
+# --------------------------------------------------------------------------------------------
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioRunClient:
+    return StudioRunClient(_session(args))
+
+
+def _run_id(value: Any) -> str:
+    """Refuse anything that is not a run identifier before it reaches a URL path.
+
+    Checked before a credential is resolved and a token minted, which is the ordering
+    :mod:`thin.commands` already establishes: a typo should cost a sentence, not a round trip.
+    The sentence names the substitution, because a folder path is exactly what somebody moving
+    from the local lane will type here first.
+    """
+
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"{value!r} is not a run identifier; the hosted lane names a run by the identifier "
+            f"the submission printed, not by a folder",
+        ) from error
+
+
+def _no_effect(
+    args: argparse.Namespace, declared: Sequence[tuple[str, str, str]]
+) -> dict[str, str]:
+    """The flags this invocation passed that the hosted lane cannot honour, and why.
+
+    ``declared`` is one entry per flag: the ``argparse`` destination, the flag as a person typed
+    it, and the sentence. Only flags actually given are reported -- a caller who did not pass
+    ``--depth`` is not told that ``--depth`` would have done nothing.
+    """
+
+    reported: dict[str, str] = {}
+    for destination, flag, sentence in declared:
+        value = getattr(args, destination, None)
+        if _was_given(value):
+            reported[flag] = sentence
+    return reported
+
+
+def _was_given(value: Any) -> bool:
+    """Whether this argument was actually passed, told apart from its default.
+
+    ⚠ Written out rather than as ``value not in (None, False, ())``, which is the obvious version
+    and is wrong: ``0 == False`` in Python, so ``--depth 0`` and ``--port 0`` would be read as
+    absent and silently not reported. An argument somebody typed must be answered for whatever
+    number they typed.
+    """
+
+    if value is None or value is False:
+        return False
+    return not (isinstance(value, (str, tuple, list, dict)) and len(value) == 0)
+
+
+def _released_version(client: StudioRunClient, run: Mapping[str, Any]) -> tuple[str, str] | None:
+    """The table version this run released, as ``(table_id, table_version_id)``.
+
+    A Run carries the table it builds but not the version it produced -- the version is created by
+    the release, after the run's own record is written -- so it is found by asking the table for
+    its versions and taking the one this run made. ``None`` whenever the run has not released
+    anything, which is the ordinary state of most runs and never an error.
+    """
+
+    table_id = run.get("table_id")
+    run_id = run.get("run_id")
+    if not isinstance(table_id, str) or not isinstance(run_id, str):
+        return None
+    versions = optional_receipt("table_versions", lambda: client.table_versions(table_id), {})
+    if not isinstance(versions, list):
+        return None
+    for version in versions:
+        if isinstance(version, Mapping) and version.get("run_id") == run_id:
+            identifier = version.get("table_version_id")
+            if isinstance(identifier, str):
+                return table_id, identifier
+    return None
+
+
+def _evidence_receipt(evidence: Mapping[str, Any]) -> dict[str, Any]:
+    """The evidence coordinates a person reads, exactly as Studio reported them."""
+
+    return {
+        key: evidence[key]
+        for key in (
+            "candidate_digest",
+            "execution_scope_digest",
+            "release_policy_digest",
+            "validation_policy_digest",
+            "verification_report_id",
+            "admission",
+        )
+        if key in evidence
+    }
+
+
+def _artifact_receipt(artifact: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        key: artifact[key]
+        for key in (
+            "artifact_id",
+            "kind",
+            "purpose",
+            "media_type",
+            "size_bytes",
+            "content_digest",
+            "classification",
+        )
+        if key in artifact
+    }
+
+
+def _numbered(prefix: str, items: Sequence[Any]) -> dict[str, Any]:
+    """``{"build 1": ..., "build 2": ...}``, zero-padded so twelve sorts after nine.
+
+    The convention ``ux.readers`` and ``ux.diffing`` already use, restated here rather than
+    imported for the same reason the words above are: those modules reach the engine.
+    """
+
+    width = len(str(max(len(items), 1)))
+    return {f"{prefix} {index:0{width}d}": item for index, item in enumerate(items, start=1)}
+
+
+def _hosted_head(session: StudioSession, run_id: str) -> dict[str, Any]:
+    """The three facts every answer in this module opens with."""
+
+    return {
+        "lane": "hosted",
+        "run_id": run_id,
+        "dashboard_url": run_dashboard_url(session.cloud_url, run_id),
+    }
+
+
+def _require_evidence(client: StudioRunClient, run_id: str, run: Mapping[str, Any]) -> Any:
+    """Read one run's sealed evidence, saying what state it is in when there is none yet.
+
+    A 404 here is the ordinary state of every run that has not produced a result, and reporting it
+    as "not found" would tell somebody their run does not exist when what happened is that it is
+    still going.
+    """
+
+    try:
+        return client.candidate_evidence(run_id)
+    except ThinLaneError as refusal:
+        if refusal.code != "THIN_NOT_FOUND":
+            raise
+        state = run.get("status")
+        raise ThinLaneError(
+            "THIN_NO_SEALED_RESULT",
+            f"this run has sealed nothing to read yet; Studio has it as {state!r}"
+            + ("" if state in TERMINAL_RUN_STATUSES else ", and it is still going"),
+        ) from refusal
+
+
+# --------------------------------------------------------------------------------------------
+# Reading one run back
+# --------------------------------------------------------------------------------------------
+
+
+def show(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data show``: what one hosted run holds.
+
+    The local command answers from a Receipt on disk. This answers from the three records Studio
+    holds about the same build -- the run, its sealed evidence, and, once it released one, the
+    table version and the bounded preview beside it -- and puts them under the keys the local
+    payload already uses, so a script that reads ``candidate_digest`` reads it in both profiles.
+    """
+
+    run_id = _run_id(args.run_dir)
+    selected = client or _client(args)
+    run = selected.get_run(run_id)
+    evidence = _require_evidence(selected, run_id, run)
+    unavailable: dict[str, str] = {}
+    payload: dict[str, Any] = {
+        "schema_version": SHOW_SCHEMA,
+        "status": "build_shown",
+        **_hosted_head(selected.session, run_id),
+        "run": run_receipt(run),
+        **_evidence_receipt(evidence),
+    }
+    released = _released_version(selected, run)
+    if released is not None:
+        table_id, version_id = released
+        payload["table_id"] = table_id
+        payload["table_version_id"] = version_id
+        preview = optional_receipt(
+            "preview",
+            lambda: selected.table_version_preview(table_id, version_id),
+            unavailable,
+        )
+        if isinstance(preview, Mapping):
+            payload["row_count"] = preview.get("total_row_count")
+            payload["columns"] = _column_names(preview)
+            payload["schema"] = _schema_payload(preview)
+    if getattr(args, "members", False):
+        payload["members"] = _numbered(
+            "member", [_artifact_receipt(item) for item in artifact_records(evidence)]
+        )
+    payload["card"] = _card(run, evidence, payload)
+    if getattr(args, "card", False):
+        return {
+            "schema_version": SHOW_SCHEMA,
+            "status": "build_shown",
+            **_hosted_head(selected.session, run_id),
+            "card": payload["card"],
+        }
+    payload["receipts_unavailable"] = unavailable
+    return payload
+
+
+def _card(run: Mapping[str, Any], evidence: Mapping[str, Any], payload: Mapping[str, Any]) -> str:
+    """The plain-language summary, built only from facts already in the payload.
+
+    Nothing here is computed, rounded or inferred. Every clause is present exactly when the fact
+    behind it is, so a card that says less is a build Studio said less about.
+    """
+
+    parts = [f"Studio has this run as {run.get('status', 'a state it did not name')}."]
+    rows = payload.get("row_count")
+    columns = payload.get("columns")
+    if isinstance(rows, int) and isinstance(columns, list):
+        parts.append(f"The released version holds {rows} rows across {len(columns)} columns.")
+    digest = evidence.get("candidate_digest")
+    if isinstance(digest, str):
+        parts.append(f"Its fingerprint is {digest}.")
+    return " ".join(parts)
+
+
+def _column_names(preview: Mapping[str, Any]) -> list[str]:
+    columns = preview.get("columns")
+    if not isinstance(columns, list):
+        return []
+    names = []
+    for column in columns:
+        if isinstance(column, Mapping) and isinstance(column.get("name"), str):
+            names.append(column["name"])
+        elif isinstance(column, str):
+            names.append(column)
+    return names
+
+
+def _schema_payload(preview: Mapping[str, Any]) -> dict[str, Any]:
+    """One numbered entry per column, carrying its real name as a value.
+
+    The same rule ``ux.readers._schema_payload`` follows: a column called ``max_temp_c`` used as a
+    key would be shown to a person as ``Max temp c``, a name the data does not have.
+    """
+
+    columns = preview.get("columns")
+    if not isinstance(columns, list):
+        return {}
+    entries = []
+    for column in columns:
+        if isinstance(column, Mapping):
+            entries.append({"name": column.get("name"), "type": column.get("type")})
+        else:
+            entries.append({"name": column, "type": None})
+    return _numbered("column", entries)
+
+
+def inspect(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data inspect``: the sealed evidence Studio holds for one hosted run.
+
+    Where ``show`` answers "what is in it", this answers "what was proved about it": the sealed
+    evidence, the execution history, the redacted model-call evidence, and every artifact the run
+    published. The evidence itself must be there -- there is nothing to inspect without it -- and
+    the two records beside it are optional in the way ``status --receipts`` already makes them:
+    one that could not be read says WHY under ``receipts_unavailable`` rather than being absent,
+    because "there is nothing" and "you may not see it" are different sentences.
+    """
+
+    run_id = _run_id(args.workspace)
+    selected = client or _client(args)
+    run = selected.get_run(run_id)
+    evidence = _require_evidence(selected, run_id, run)
+    unavailable: dict[str, str] = {}
+    summary = optional_receipt(
+        "execution_summary", lambda: selected.execution_summary(run_id), unavailable
+    )
+    agent = optional_receipt(
+        "agent_evidence", lambda: selected.run_agent_evidence(run_id), unavailable
+    )
+    return {
+        "schema_version": INSPECT_SCHEMA,
+        "status": "candidate_inspected",
+        **_hosted_head(selected.session, run_id),
+        "run": run_receipt(run),
+        **_evidence_receipt(evidence),
+        "execution_summary": summary,
+        "agent_evidence": _numbered("call", list(agent)) if isinstance(agent, list) else None,
+        "members": _numbered(
+            "member", [_artifact_receipt(item) for item in artifact_records(evidence)]
+        ),
+        "receipts_unavailable": unavailable,
+    }
+
+
+def verify(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data verify``: re-check one hosted run against the evidence Studio sealed.
+
+    ⚠ WHAT "VERIFY" HONESTLY MEANS HERE. The local command replays a build's bytes on this
+    computer. A hosted build's bytes are not here, and downloading gigabytes to re-hash them is
+    not what somebody typing ``verify`` is asking for. What this reads instead is the independent
+    check Studio already ran -- a different worker, a different attempt, the same recipe -- and
+    the findings it opened. That is a stronger check than a local replay, not a weaker one, and
+    the payload says which of the two it is rather than letting the word carry the difference.
+
+    The verdict comes from the findings, never from the run's state word: a released run with an
+    open blocking finding is not a verified build, and the exit code follows the verdict.
+    """
+
+    run_id = _run_id(args.run_dir)
+    selected = client or _client(args)
+    run = selected.get_run(run_id)
+    evidence = _require_evidence(selected, run_id, run)
+    findings = selected.run_findings(run_id)
+    blocking = [
+        finding
+        for finding in findings
+        if finding.get("blocks_release") is True and finding.get("status") != "closed"
+    ]
+    return {
+        "schema_version": VERIFY_SCHEMA,
+        "status": "fixes_required" if blocking else "candidate_verified",
+        **_hosted_head(selected.session, run_id),
+        "run": run_receipt(run),
+        **_evidence_receipt(evidence),
+        "checked_by": "the independent hosted check, read back; the bytes were not replayed here",
+        "finding count": len(findings),
+        "blocking count": len(blocking),
+        "findings": _numbered("finding", [_finding_receipt(item) for item in findings]),
+    }
+
+
+def verify_exit_code(payload: Mapping[str, Any]) -> int:
+    """``2`` when a finding blocks release, so a script can gate on the verdict.
+
+    The same convention the local review verdict follows: an answer is an answer whatever it says,
+    but "fixes are required" is not a passing check and must not exit as one.
+    """
+
+    return 2 if payload.get("status") == "fixes_required" else 0
+
+
+def _finding_receipt(finding: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        key: finding[key]
+        for key in (
+            "finding_id",
+            "check_id",
+            "category",
+            "code",
+            "severity",
+            "summary",
+            "status",
+            "blocks_release",
+            "opened_at",
+            "closed_at",
+        )
+        if key in finding
+    }
+
+
+# --------------------------------------------------------------------------------------------
+# Reading many runs back
+# --------------------------------------------------------------------------------------------
+
+
+def listing(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data list``: the hosted runs in this workspace.
+
+    The local command walks a folder; this asks Studio, which scopes the answer to the workspace
+    the credential names. ``root`` and ``--depth`` describe a folder and are reported as having
+    described nothing; ``--verify`` is reported too, and the reason is worth reading -- there is
+    nothing here to replay, because the independent check already ran on the backend and its
+    verdict is in each row.
+    """
+
+    selected = client or _client(args)
+    runs = selected.list_runs(
+        status=getattr(args, "run_status", None), limit=getattr(args, "limit", None)
+    )
+    entries = [_listing_entry(run) for run in runs]
+    return {
+        "schema_version": LIST_SCHEMA,
+        "status": "builds_listed",
+        "lane": "hosted",
+        "workspace_id": str(selected.session.workspace_id),
+        "verification": _listing_verification(entries),
+        "note": _listing_note(entries),
+        "builds": _numbered("build", entries),
+        "flags_without_effect": _no_effect(
+            args,
+            (
+                ("root", "root", "a hosted listing is the workspace's runs, not a folder's"),
+                ("depth", "--depth", "there are no folders here to look down through"),
+                (
+                    "verify",
+                    "--verify",
+                    "there is nothing here to replay; the independent hosted check already ran, "
+                    "and each row carries its verdict",
+                ),
+            ),
+        ),
+    }
+
+
+def _listing_entry(run: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "run_id": run.get("run_id"),
+        "run_status": run.get("status"),
+        "kind": run.get("kind"),
+        "recipe_digest": run.get("recipe_digest"),
+        "created_at": run.get("created_at"),
+        "completed_at": run.get("completed_at"),
+        "verification": VERIFIED if run.get("status") == "released" else LISTED_ONLY,
+    }
+
+
+def _listing_verification(entries: Sequence[Mapping[str, Any]]) -> str:
+    """What the listing as a whole may claim, taken from the rows and never from a flag."""
+
+    if not entries:
+        return NOTHING_TO_VERIFY
+    if all(entry["verification"] == VERIFIED for entry in entries):
+        return VERIFIED
+    return NOT_ALL_VERIFIED
+
+
+def _listing_note(entries: Sequence[Mapping[str, Any]]) -> str:
+    if not entries:
+        return "No runs in this workspace yet. Run mr-data build --hosted to queue one."
+    released = sum(1 for entry in entries if entry["verification"] == VERIFIED)
+    return (
+        f"{len(entries)} runs, of which {released} released a version the independent hosted "
+        "check passed. Run mr-data show on one of their identifiers for the full answer."
+    )
+
+
+def fleet(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data fleet``: which hosted runs are waiting for a person.
+
+    Same rows, same four keys, same words as the local scan -- ``name``, ``state``,
+    ``needs_person``, ``reasons`` -- with the run identifier as the name, because that is what a
+    hosted run is called. ``--html`` is reported as having no effect and the dashboard address is
+    given instead: a page rendered here would be a second, staler answer beside the live one.
+    """
+
+    selected = client or _client(args)
+    runs = selected.list_runs(limit=getattr(args, "limit", None))
+    rows = [_fleet_row(run) for run in runs]
+    return {
+        "schema_version": FLEET_SCHEMA,
+        "status": "fleet_scanned",
+        "lane": "hosted",
+        "workspace_id": str(selected.session.workspace_id),
+        "waiting": sum(1 for row in rows if row["needs_person"]),
+        "runs": rows,
+        "flags_without_effect": _no_effect(
+            args,
+            (
+                ("root", "root", "a hosted fleet is the workspace's runs, not a folder's"),
+                (
+                    "html",
+                    "--html",
+                    "the live page for these runs is the dashboard; a page rendered here would be "
+                    "a second answer that is already out of date",
+                ),
+            ),
+        ),
+    }
+
+
+def _fleet_row(run: Mapping[str, Any]) -> dict[str, Any]:
+    state = run.get("status")
+    reason = FLEET_NEEDS_A_PERSON.get(str(state))
+    return {
+        "name": run.get("run_id"),
+        "state": FLEET_STATE.get(str(state), "state not recorded"),
+        "needs_person": reason is not None,
+        "reasons": [reason] if reason is not None else [],
+    }
+
+
+def diff(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data diff``: compare two hosted runs and say what changed.
+
+    Finding a difference is an answer, not a failure, so this exits 0 either way and the verdict
+    is the status word -- ``builds_identical`` or ``builds_differ`` -- exactly as the local
+    command's help promises. Identity is the sealed fingerprint and nothing else: two runs of the
+    same recipe at different times are the same data when their fingerprints agree.
+    """
+
+    left_id = _run_id(args.left)
+    right_id = _run_id(args.right)
+    selected = client or _client(args)
+    left = _side(selected, left_id)
+    right = _side(selected, right_id)
+    changes = _changes(left, right)
+    columns_only = bool(getattr(args, "columns_only", False))
+    shown = (
+        [change for change in changes if change["is column change"]] if columns_only else changes
+    )
+    identical = left["candidate_digest"] == right["candidate_digest"]
+    payload: dict[str, Any] = {
+        "schema_version": DIFF_SCHEMA,
+        "status": "builds_identical" if identical else "builds_differ",
+        "lane": "hosted",
+        "summary": _comparison_summary(identical, changes, shown),
+        # The full count, always. A narrowed view narrows what is listed, never what is true.
+        "change count": len(changes),
+        "changes": _numbered("change", shown),
+        "first build": left,
+        "second build": right,
+    }
+    if len(shown) != len(changes):
+        payload["columns only"] = True
+    return payload
+
+
+def _side(client: StudioRunClient, run_id: str) -> dict[str, Any]:
+    """One side of the comparison, refused unless it carries the fingerprint identity rests on.
+
+    Absent everywhere else in this module -- ``show`` reports a run Studio said less about -- and
+    mandatory here, because a comparison whose identity field is missing on both sides would
+    answer "the same" about two builds nobody compared.
+    """
+
+    run = client.get_run(run_id)
+    evidence = _require_evidence(client, run_id, run)
+    if not isinstance(evidence.get("candidate_digest"), str):
+        raise ThinLaneError(
+            "THIN_NO_FINGERPRINT",
+            f"Studio's evidence for {run_id} carries no fingerprint, so this run cannot be "
+            "compared with another",
+        )
+    side: dict[str, Any] = {
+        "run_id": run_id,
+        "run_status": run.get("status"),
+        "recipe_digest": run.get("recipe_digest"),
+        "recipe_version": run.get("recipe_version"),
+        "candidate_digest": evidence.get("candidate_digest"),
+        "row_count": None,
+        "columns": [],
+    }
+    released = _released_version(client, run)
+    if released is not None:
+        table_id, version_id = released
+        preview = optional_receipt(
+            "preview", lambda: client.table_version_preview(table_id, version_id), {}
+        )
+        if isinstance(preview, Mapping):
+            side["row_count"] = preview.get("total_row_count")
+            side["columns"] = _column_names(preview)
+    return side
+
+
+def _changes(left: Mapping[str, Any], right: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Every difference between two sides, columns first and then the counts.
+
+    Column order is the second build's, so a listing reads in the order the newer data has.
+    """
+
+    changes: list[dict[str, Any]] = []
+    before = list(left["columns"])
+    after = list(right["columns"])
+    for name in after:
+        if name not in before:
+            changes.append({"what": "column added", "name": name, "is column change": True})
+    for name in before:
+        if name not in after:
+            changes.append({"what": "column removed", "name": name, "is column change": True})
+    if left["row_count"] != right["row_count"]:
+        changes.append(
+            {
+                "what": "row count moved",
+                "before": left["row_count"],
+                "after": right["row_count"],
+                "is column change": False,
+            }
+        )
+    if left["candidate_digest"] != right["candidate_digest"]:
+        changes.append(
+            {
+                "what": "the data is different",
+                "before": left["candidate_digest"],
+                "after": right["candidate_digest"],
+                "is column change": False,
+            }
+        )
+    return changes
+
+
+def _comparison_summary(
+    identical: bool, changes: Sequence[Mapping[str, Any]], shown: Sequence[Mapping[str, Any]]
+) -> str:
+    if identical:
+        return "Those two runs hold the same data, in the same shape."
+    counted = len(changes)
+    sentence = f"Those two runs are not the same: {counted} " + (
+        "difference." if counted == 1 else "differences."
+    )
+    if len(shown) != counted:
+        sentence += f" Only the {len(shown)} about columns are listed."
+    return sentence
+
+
+# --------------------------------------------------------------------------------------------
+# The notebook, rendered where the run ran
+# --------------------------------------------------------------------------------------------
+
+
+def notebook(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data notebook``: bring back the notebook Studio rendered for one hosted run.
+
+    ADR 0021 moves this rendering to the backend, and that is the point rather than a compromise:
+    Studio renders the notebook from the run's own append-only event log and from nothing else, so
+    the notebook, the live stream and the sealed evidence read the same record and cannot disagree.
+    A notebook rendered here from downloaded bytes would be a second answer with no such guarantee.
+
+    Both documents are fetched by default -- the ``.ipynb`` somebody opens in Jupyter and the
+    standalone HTML somebody opens in a browser -- and both are digest-verified before they are
+    written, through the same ``O_EXCL`` write ``deploy-dataset`` uses.
+    """
+
+    return _fetch_notebook(args, client, wanted=("ipynb", "html"), open_html=False)
+
+
+def view(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data view``: open the notebook Studio rendered for one hosted run.
+
+    The local command starts a viewer server on this computer and points a browser at it. There is
+    nothing here to serve, so this brings back the standalone HTML rendering -- whose charts are
+    inline, with no external asset, precisely so it stands alone -- and opens it when ``--open``
+    is given, exactly as the local command's flag means. Every argument about the local server is
+    reported as having no effect.
+    """
+
+    payload = _fetch_notebook(
+        args, client, wanted=("html",), open_html=bool(getattr(args, "open", False))
+    )
+    payload["flags_without_effect"] = _no_effect(
+        args,
+        (
+            ("workspace", "--workspace", "a hosted run has no workbench folder here"),
+            ("run_dir", "--run-dir", "a hosted run has no build folder here"),
+            ("research_dir", "--research-dir", "the research notebook is rendered on the backend"),
+            # ⚠ NOT "the document is a file". The path-kind gate reads every sentence this
+            # package can print and refuses one that names a kind nothing looked at -- and
+            # nothing here looked at anything on disk. What is true and says as much is that the
+            # document was brought back rather than served.
+            (
+                "host",
+                "--host",
+                "nothing is served from this computer; the document is brought here",
+            ),
+            (
+                "port",
+                "--port",
+                "nothing is served from this computer; the document is brought here",
+            ),
+        ),
+    )
+    return payload
+
+
+def _fetch_notebook(
+    args: argparse.Namespace,
+    client: StudioRunClient | None,
+    *,
+    wanted: Sequence[str],
+    open_html: bool,
+) -> dict[str, Any]:
+    run_id = _run_id(getattr(args, "run", None) or getattr(args, "run_dir", None))
+    selected = client or _client(args)
+    try:
+        rendered = selected.run_notebook(run_id)
+    except ThinLaneError as refusal:
+        if refusal.code != "THIN_NOT_FOUND":
+            raise
+        raise ThinLaneError(
+            "THIN_NOTEBOOK_NOT_RENDERED",
+            "this run has no notebook yet; Studio renders one when the run finishes, and the "
+            "live view until then is mr-data watch",
+        ) from refusal
+    documents = rendered.get("documents")
+    if not isinstance(documents, Mapping):
+        raise ThinLaneError("THIN_RESPONSE_INVALID", "Studio described no notebook documents")
+    output = Path(getattr(args, "output", None) or DEFAULT_NOTEBOOK_OUTPUT).expanduser()
+    written: dict[str, Any] = {}
+    for name in wanted:
+        document = documents.get(name)
+        if not isinstance(document, Mapping):
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", f"Studio described no {name} notebook document"
+            )
+        destination = output / f"{run_id}{_notebooksuffix_for(name, document)}"
+        artifact = download_signed_artifact(
+            _notebook_session(document), destination, transport=selected.transport
+        )
+        written[name] = {
+            "path": str(artifact.path),
+            "media_type": artifact.media_type,
+            "size_bytes": artifact.size_bytes,
+            "content_digest": artifact.content_digest,
+        }
+    payload: dict[str, Any] = {
+        "schema_version": NOTEBOOK_SCHEMA,
+        "status": "notebook_ready",
+        **_hosted_head(selected.session, run_id),
+        "rendered_at": rendered.get("rendered_at"),
+        "run_status": rendered.get("run_status"),
+        "source_log_digest": rendered.get("source_log_digest"),
+        "source_event_count": rendered.get("source_event_count"),
+        "source_truncated": rendered.get("source_truncated"),
+        "output": str(output),
+        "documents": written,
+    }
+    if rendered.get("source_truncated") is True:
+        # Not a footnote. A notebook that covers part of a run is a notebook that can be read as
+        # covering all of it, and the one place somebody is guaranteed to look is the top.
+        payload["note"] = (
+            "This run's history was longer than the renderer reads, so the notebook covers only "
+            "its first events. The document says so in its own text as well."
+        )
+    if open_html and "html" in written:
+        payload["opened"] = _open_document(Path(written["html"]["path"]))
+    return payload
+
+
+def _notebooksuffix_for(name: str, document: Mapping[str, Any]) -> str:
+    """``.ipynb`` for the notebook, and the project's own table for everything else.
+
+    The HTML arm compares the PARSED media type, not the header Studio sent. Studio serves the
+    rendered page as ``text/html; charset=utf-8``, and an equality test against ``text/html``
+    missed it silently: the one document a person opens in a browser was written as ``.bin``.
+    """
+
+    if name == "ipynb":
+        return ".ipynb"
+    if media_type_essence(document.get("media_type")) == "text/html":
+        return ".html"
+    return suffix_for(document.get("media_type"))
+
+
+def _notebook_session(document: Mapping[str, Any]) -> dict[str, Any]:
+    """One notebook document, in the shape the signed-download verifier already checks.
+
+    The notebook resource carries its digest and size beside the URL rather than inside a signed
+    session object, so they are moved onto the shape :func:`download_signed_artifact` verifies
+    rather than a second verifier being written. Both facts stay mandatory: a document with no
+    digest is refused here, before a byte is fetched.
+    """
+
+    download = document.get("download")
+    if not isinstance(download, Mapping):
+        raise ThinLaneError("THIN_RESPONSE_INVALID", "a notebook document carried no download")
+    return {
+        "signed_url": download.get("url", ""),
+        "expected_content_digest": document.get("content_digest"),
+        "expected_size_bytes": document.get("size_bytes"),
+        "media_type": document.get("media_type"),
+    }
+
+
+def _open_document(path: Path, opener: Callable[[str], bool] | None = None) -> bool:
+    """Open one written document in whatever this desktop opens HTML with.
+
+    ``webbrowser`` is standard library and never a hard failure: a machine with no browser -- a
+    build agent, a container, somebody over SSH -- gets the file it asked for and a receipt saying
+    it was not opened, rather than a refusal about a document that is already on disk.
+    """
+
+    import webbrowser
+
+    selected = opener or webbrowser.open
+    try:
+        return bool(selected(path.resolve().as_uri()))
+    except Exception:  # pragma: no cover - a desktop that answers by raising
+        return False
+
+
+# --------------------------------------------------------------------------------------------
+# Looking at the data, and at a deployment's run
+# --------------------------------------------------------------------------------------------
+
+
+def peek(args: argparse.Namespace, *, client: StudioRunClient | None = None) -> dict[str, Any]:
+    """``mr-data peek``: the columns, types and first rows of one hosted table version.
+
+    The local command opens a file or an address on this computer. Hosted, the thing to look at is
+    the bounded preview Studio published beside the released version, named by the run that
+    released it. Every argument about opening bytes here -- the format, the Reader, the JSON
+    shaping -- is reported as having no effect, because the preview arrives already decoded by the
+    Reader the recipe pinned.
+
+    ``--rows`` narrows what is shown and cannot widen it: the preview's size was decided by the
+    release, and a client asking for more rows than were published would be asking Studio to
+    re-read the table.
+    """
+
+    run_id = _run_id(args.target)
+    selected = client or _client(args)
+    run = selected.get_run(run_id)
+    released = _released_version(selected, run)
+    if released is None:
+        raise ThinLaneError(
+            "THIN_NO_RELEASED_VERSION",
+            "this run has released no version to look at; a hosted preview is published by the "
+            "release, and Studio has this run as " + str(run.get("status")),
+        )
+    table_id, version_id = released
+    preview = selected.table_version_preview(table_id, version_id)
+    rows = preview.get("rows")
+    rows = rows if isinstance(rows, list) else []
+    wanted = getattr(args, "rows", None)
+    shown = rows[: int(wanted)] if isinstance(wanted, int) else rows
+    payload: dict[str, Any] = {
+        "schema_version": PEEK_SCHEMA,
+        "status": "peeked",
+        **_hosted_head(selected.session, run_id),
+        "source": f"{table_id}/{version_id}",
+        "origin": "hosted",
+        "table_id": table_id,
+        "table_version_id": version_id,
+        "row_count": preview.get("total_row_count"),
+        "columns": _column_names(preview),
+        "schema": _schema_payload(preview),
+        "sample": _numbered("row", shown),
+        "input_sha256": preview.get("source_parquet_digest"),
+        "candidate_digest": preview.get("candidate_digest"),
+        "flags_without_effect": _no_effect(
+            args,
+            (
+                (
+                    "data_format",
+                    "--format",
+                    "the preview arrives decoded; there are no bytes here to name a format for",
+                ),
+                ("reader", "--reader", "the Reader was pinned by the recipe that built this"),
+                (
+                    "reader_options",
+                    "--reader-options",
+                    "the Reader was pinned by the recipe that built this",
+                ),
+                (
+                    "allow_redirect_hosts",
+                    "--allow-redirect-host",
+                    "nothing is fetched from a third-party address here",
+                ),
+                (
+                    "json_records_pointer",
+                    "--json-records-pointer",
+                    "the preview is already rows and columns",
+                ),
+                ("json_expand", "--json-expand", "the preview is already rows and columns"),
+                ("json_column", "--json-column", "the preview is already rows and columns"),
+                (
+                    "json_optional_column",
+                    "--json-optional-column",
+                    "the preview is already rows and columns",
+                ),
+                (
+                    "json_document_format",
+                    "--json-document-format",
+                    "the preview is already rows and columns",
+                ),
+            ),
+        ),
+    }
+    if preview.get("truncated") is True or len(shown) != len(rows):
+        payload["note"] = (
+            f"Showing {len(shown)} of the {len(rows)} rows this version published a preview for, "
+            f"out of {preview.get('total_row_count')} in the table."
+        )
+    return payload
+
+
+def deployment_status(
+    args: argparse.Namespace, *, client: StudioRunClient | None = None
+) -> dict[str, Any]:
+    """``mr-data deploy-status``: what Studio says about the run one deployment queued.
+
+    The local command finds the run identifier in the deployment journal this computer wrote. A
+    hosted profile never wrote one, so the identifier is named directly -- and everything after
+    that is the same reading of the same record, under the same status word.
+    """
+
+    run_id = _run_id(args.run_dir)
+    selected = client or _client(args)
+    run = selected.get_run(run_id)
+    state = str(run.get("status"))
+    return {
+        "schema_version": DEPLOYMENT_STATUS_SCHEMA,
+        "status": "run_status_reported",
+        **_hosted_head(selected.session, run_id),
+        "run_status": state,
+        "terminal": state in TERMINAL_RUN_STATUSES,
+        "workspace_id": str(selected.session.workspace_id),
+        "run": run_receipt(run),
+        "flags_without_effect": _no_effect(
+            args,
+            (
+                (
+                    "watch_seconds",
+                    "--watch-seconds",
+                    "this profile follows a run with mr-data watch, which streams it rather than "
+                    "asking again on a timer",
+                ),
+            ),
+        ),
+    }
+
+
+__all__ = [
+    "DEFAULT_NOTEBOOK_OUTPUT",
+    "DEPLOYMENT_STATUS_SCHEMA",
+    "DIFF_SCHEMA",
+    "FLEET_NEEDS_A_PERSON",
+    "FLEET_SCHEMA",
+    "FLEET_STATE",
+    "INSPECT_SCHEMA",
+    "LIST_SCHEMA",
+    "NOTEBOOK_SCHEMA",
+    "PEEK_SCHEMA",
+    "SHOW_SCHEMA",
+    "VERIFY_SCHEMA",
+    "deployment_status",
+    "diff",
+    "fleet",
+    "inspect",
+    "listing",
+    "notebook",
+    "peek",
+    "show",
+    "verify",
+    "verify_exit_code",
+    "view",
+]