mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/router.py

@@ -0,0 +1,924 @@
+"""``mr-data``'s front door: one binary, two install profiles, one command vocabulary.
+
+WHY THIS MODULE EXISTS. ADR 0021 makes the client thin -- pure Python, no sandbox, no process
+control -- and keeps the command names exactly as they are, so where a command runs stops being
+user-visible variance. Those two requirements meet here. ``cli`` is the local lane and cannot be
+imported at all without native wheels (it reaches ``hosted_worker``, which imports ``pyarrow`` and
+``cryptography`` at module scope), so the entry point cannot BE ``cli``: it has to be something
+that can decide, on a bare interpreter, whether the local lane is even installed.
+
+THE DECISION, in one paragraph. With the ``[local]`` extra installed, every invocation is handed
+to ``cli`` unchanged -- byte-identical help, byte-identical behaviour, no new code in the path --
+unless the caller writes ``--hosted``, which selects the hosted lane for the commands that have
+one. Without it, the hosted lane is the only lane there is: the hosted and portable commands run,
+and every other name refuses by name and says WHY -- which of three different situations it is
+in, and what would change it. What never happens is the third thing: a local command silently
+doing nothing, or a hosted command silently running locally.
+
+⚠ "INSTALLED" IS NOT THE ONLY QUESTION ANY MORE. The base wheel is `py3-none-any` and
+installs on Windows, where the local lane cannot run no matter what is installed -- it needs
+``fork`` and a kernel sandbox that does not exist there. So the routing decision asks the platform
+first (:func:`local_lane_platform_supported`) and the closure second, and the refusal says which
+of the two it was. That check is the run-time home of the rule ``scripts/hatch_build.py`` used to
+enforce by refusing to build a wheel at all.
+
+⚠ ``--hosted`` IS A LANE SELECTOR, NOT A NEW COMMAND. The vocabulary in :data:`VOCABULARY` is the
+same fifty-eight names ``cli`` parses, and ``tests/test_thin_client.py`` asserts that set equality
+against the live parser rather than trusting this file. A name added to one and not the other
+fails the suite.
+
+⚠ THE LANE TABLE IS NOT HERE. It is
+:mod:`mostlyright.data_harness.thin.vocabulary`, which carries a written reason beside every
+name. This module decides and refuses; that one says what the decision was and why, and is the
+single source both the refusals and ``docs/HOSTED-PARITY.md`` read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.thin.vocabulary import (
+    CLASSIFICATION,
+    HOSTED,
+    HOSTED_PENDING,
+    LANES,
+    LOCAL,
+    PORTABLE,
+    VOCABULARY,
+    WORKER,
+    names_in,
+    reason_for,
+)
+
+#: The flag that asks for the hosted lane on a machine that also has the local one.
+HOSTED_FLAG = "--hosted"
+
+#: The flag that insists on the local lane, so a script can fail loudly on a thin install rather
+#: than silently submitting work to the backend.
+LOCAL_FLAG = "--local"
+
+#: The third-party distributions the local lane cannot run without. Probed by name rather than
+#: imported: ``find_spec`` answers on a bare interpreter in microseconds, and importing any of
+#: them is precisely what the thin profile exists to avoid.
+LOCAL_LANE_DISTRIBUTIONS = ("pyarrow", "polars", "cryptography")
+
+#: Why an operating system can be unable to host the local lane at all, said once. The local lane
+#: runs every acquisition and every Reader behind a kernel boundary it builds with POSIX process
+#: control -- ``fork``, and then cgroups v2 or Seatbelt. Windows has none of the three, which is
+#: the whole reason ADR 0021 stopped treating per-OS sandbox work as a product requirement.
+LOCAL_LANE_PLATFORM_REASON = (
+    "the local execution lane needs POSIX process control and a kernel sandbox "
+    "(fork, and cgroups v2 or Seatbelt), which this operating system does not provide"
+)
+
+#: Where the old wheel-tag fence went. ``scripts/hatch_build.py`` used to keep the local lane off
+#: unsupported platforms by refusing to produce a wheel for them; the base wheel is now
+#: `py3-none-any` and installs everywhere, so the rule has to be checked where the fact
+#: is -- at run time, on the machine, before a local command is handed to ``cli``.
+#:
+#: ⚠ PROBED, NOT LISTED. An allow-list of OS/architecture tuples would refuse the local lane on
+#: platforms it works on perfectly well today (linux/aarch64 among them, which the old build fence
+#: excluded only because nobody minted wheels there). ``os.fork`` is the actual capability the
+#: lane is built on, so it is the thing asked about.
+LOCAL_LANE_UNSUPPORTED_PLATFORM_CODE = "THIN_LOCAL_LANE_UNSUPPORTED_PLATFORM"
+
+#: What to install to get the local lane back. One string, so the refusals cannot disagree.
+LOCAL_INSTALL_HINT = 'pip install "mostlyright-data[local]"'
+
+#: The typed code each lane refuses with, and nothing else decides it. Three codes rather than
+#: one, because the three answers are different answers: "this needs the other install", "this
+#: should be hosted and is not yet, for the reason below", and "this is not a command you run".
+REFUSAL_CODE = {
+    LOCAL: "THIN_COMMAND_IS_LOCAL",
+    HOSTED_PENDING: "THIN_COMMAND_HOSTED_PENDING",
+    WORKER: "THIN_COMMAND_IS_WORKER_INTERNAL",
+}
+
+#: The portable commands, and the ``ux.commands`` module each resolves to. Both are stdlib-only
+#: today, so the thin profile runs the SAME implementation the local profile runs rather than a
+#: second one written to look like it.
+PORTABLE_MODULES = {"auth": "auth", "login": "login", "whoami": "whoami"}
+
+#: One line per hosted command, for the help the thin profile prints. Short on purpose: the local
+#: profile's ``--help`` is ``cli``'s and is not restated here, so these cannot drift out of sync
+#: with prose they do not duplicate.
+#
+#: Written as pairs rather than as a literal mapping on purpose: a ``"status": "..."`` entry in a
+#: dict literal is indistinguishable, to the status-vocabulary walker in ``tests/test_ux_render``,
+#: from a payload declaring a status word -- and a help sentence is not a status.
+HOSTED_SUMMARY = dict(
+    (
+        ("build", "queue one hosted build and print where to watch it"),
+        ("run", "queue one hosted build and print where to watch it"),
+        ("watch", "stream one hosted run's live progress, resuming across stream cuts"),
+        ("status", "report Studio's own reading of one hosted run, with its receipts"),
+        ("deploy-dataset", "download one hosted run's dataset and verify its digest"),
+        ("show", "show what one hosted run holds"),
+        ("inspect", "show the sealed evidence for one hosted run"),
+        ("verify", "re-check one hosted run against the evidence Studio sealed"),
+        ("list", "list the hosted runs in this workspace"),
+        ("fleet", "say which hosted runs are waiting for a person"),
+        ("diff", "compare two hosted runs and say what changed"),
+        ("note", "write one cell of the decision record into a hosted run's own log"),
+        ("notebook", "bring back the notebook Studio rendered for one hosted run"),
+        ("view", "open the notebook Studio rendered for one hosted run"),
+        ("peek", "show the columns, types and first rows of one hosted table version"),
+        ("deploy-status", "report what Studio says about the run one deployment queued"),
+        ("acquire", "fetch one public address in Studio's clean room and print its bound Receipt"),
+        (
+            "acquire-cancel",
+            "cancel one active public acquisition and print Studio's cancellation receipt",
+        ),
+        ("approve", "ask for one approval, say where a person grants it, and read what they did"),
+        ("recipe-approve", "the same ask, about one Table recipe approval"),
+        ("propose", "author one hosted recipe proposal from a bundle and open its approval"),
+        ("research-open", "open one hosted research session and watch its worker warm up"),
+        ("research-probe", "ask a research session's worker one question and print its answer"),
+        ("research-status", "report Studio's own reading of one research session, or one probe"),
+        ("research-close", "close one research session; its worker exits"),
+    )
+)
+
+
+def local_lane_platform_supported() -> bool:
+    """Whether this operating system can host the local execution lane at all.
+
+    Distinct from :func:`local_lane_available`, and asked first, because the two answer different
+    questions and only one of them is fixed by installing something. On Windows the extra can be
+    installed -- pyarrow, polars and cryptography all publish Windows wheels -- and the lane still
+    cannot run, so "is it installed" is the wrong question to route on there.
+    """
+
+    return hasattr(os, "fork")
+
+
+def local_lane_available(
+    find_spec: Callable[[str], Any] | None = None,
+) -> bool:
+    """Whether this machine can run the local lane: the right OS, and the native closure."""
+
+    if not local_lane_platform_supported():
+        return False
+    resolve = find_spec or importlib.util.find_spec
+    for distribution in LOCAL_LANE_DISTRIBUTIONS:
+        try:
+            if resolve(distribution) is None:
+                return False
+        except (ImportError, ValueError):  # pragma: no cover - a broken path entry
+            return False
+    return True
+
+
+def selected_command(argv: Sequence[str]) -> str | None:
+    """The first token that names a command, ignoring the flags that may precede it."""
+
+    for token in argv:
+        if token == "--":
+            return None
+        if not token.startswith("-"):
+            return token
+    return None
+
+
+def _lane_flags(argv: Sequence[str]) -> tuple[bool, bool]:
+    hosted = False
+    local = False
+    for token in argv:
+        if token == "--":
+            break
+        if token == HOSTED_FLAG:
+            hosted = True
+        elif token == LOCAL_FLAG:
+            local = True
+    return hosted, local
+
+
+def _without_lane_flags(argv: Sequence[str]) -> list[str]:
+    return [token for token in argv if token not in {HOSTED_FLAG, LOCAL_FLAG}]
+
+
+#: The one sentence every translated positional gets. Written once so fifteen commands cannot
+#: describe the same substitution fifteen slightly different ways.
+_RUN_POSITIONAL = "the hosted run, by the identifier the submission printed"
+
+#: The sentences the accepted-but-inert arguments carry in ``--help``, so somebody reads them
+#: BEFORE running the command rather than in the receipt afterwards.
+_NO_EFFECT_FOLDER = "no effect here; a hosted run has no folder on this computer"
+_NO_EFFECT_SERVER = "no effect here; nothing is served from this computer"
+_NO_EFFECT_REPLAY = (
+    "no effect here; the independent hosted check already ran and each row carries its verdict"
+)
+_NO_EFFECT_DECODED = "no effect here; the hosted preview arrives already decoded"
+_NOTEBOOK_OUTPUT = "the folder to write into; an existing file is never overwritten"
+
+#: The one translation `approve` makes, and the sentences its accepted-but-inert flags carry.
+_APPROVAL_POSITIONAL = (
+    "the approval Studio holds, by its identifier; a hosted approval is a record on the backend "
+    "and not a Recipe file here"
+)
+_NO_EFFECT_APPROVAL_HUMAN = (
+    "no effect here; Studio records who decided and when, from the human session that decided"
+)
+_NO_EFFECT_APPROVAL_NAMED = "no effect here; the approval already has the identifier you named"
+_NO_EFFECT_APPROVAL_POLICY = "no effect here; a hosted approval is decided under the workspace's"
+_NO_EFFECT_APPROVAL_RECORD = (
+    "no effect here; the decision is Studio's immutable record and is read back from it"
+)
+_NO_EFFECT_STUDIO_CLEAN_ROOM = (
+    "no effect here; the clean room and the egress policy are Studio's, and the Receipt carries "
+    "their attestations"
+)
+
+
+def _hosted_parser() -> argparse.ArgumentParser:
+    """The hosted lane's own arguments, one subcommand per hosted name."""
+
+    parser = argparse.ArgumentParser(prog="mr-data", add_help=False)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def _add(name: str) -> argparse.ArgumentParser:
+        added = subparsers.add_parser(name, add_help=True, help=HOSTED_SUMMARY.get(name))
+        added.add_argument(
+            "--json",
+            action="store_true",
+            help="emit one machine-readable JSON object instead of human lines",
+        )
+        return added
+
+    for name in ("build", "run"):
+        submit = _add(name)
+        submit.add_argument(
+            "--recipe-proposal",
+            required=True,
+            help="the approved recipe proposal this build executes",
+        )
+        submit.add_argument(
+            "--recipe-digest",
+            required=True,
+            help="the recipe digest the proposal must still carry; bare lowercase hex",
+        )
+        submit.add_argument(
+            "--resource-class",
+            choices=("standard", "large"),
+            help="the capacity class to ask for; Studio refuses one it cannot satisfy",
+        )
+
+    watch = _add("watch")
+    watch.add_argument("run_id", help="the run to follow")
+    watch.add_argument(
+        "--from-seq",
+        type=int,
+        default=0,
+        help="replay from after this log position; ignored once a cursor is known",
+    )
+    watch.add_argument(
+        "--last-event-id", help="resume from this cursor, as a previous watch reported it"
+    )
+
+    status = _add("status")
+    status.add_argument("run_id", help="the run to report")
+    status.add_argument(
+        "--receipts",
+        action="store_true",
+        help="also read the execution summary and the sealed candidate evidence",
+    )
+
+    download = _add("deploy-dataset")
+    download.add_argument("run_id", help="the released run whose dataset to bring back")
+    download.add_argument("--output", help="the folder to write into; it is never overwritten")
+    download.add_argument(
+        "--kind",
+        action="append",
+        help="an artifact kind to fetch; repeatable, and defaults to the dataset itself",
+    )
+
+    # ------------------------------------------------------------------------------------
+    # The read, compare and view commands
+    # ------------------------------------------------------------------------------------
+    #
+    # Every argument the local command declares appears here under the SAME destination, so a
+    # script keeps working when the machine it runs on changes profile. Where the hosted lane
+    # cannot honour one it is still accepted, and `thin.parity._no_effect` reports it -- never
+    # `argparse` refusing it, which would be the breakage this phase exists to remove.
+    #
+    # The one translation, made in every command that needs it: the local positional names a
+    # folder and the hosted one names a run. It keeps the local destination (`run_dir`,
+    # `workspace`, `target`) so the two parsers stay comparable argument for argument.
+
+    show = _add("show")
+    show.add_argument("run_dir", help=_RUN_POSITIONAL)
+    show.add_argument(
+        "--card", action="store_true", help="print the plain-language summary and nothing else"
+    )
+    show.add_argument(
+        "--members", action="store_true", help="also list every artifact the run published"
+    )
+
+    inspected = _add("inspect")
+    inspected.add_argument("workspace", help=_RUN_POSITIONAL)
+
+    verified = _add("verify")
+    verified.add_argument("run_dir", help=_RUN_POSITIONAL)
+
+    listed = _add("list")
+    listed.add_argument("root", nargs="?", default=None, help=_NO_EFFECT_FOLDER)
+    listed.add_argument("--verify", action="store_true", help=_NO_EFFECT_REPLAY)
+    listed.add_argument("--depth", type=int, default=None, help=_NO_EFFECT_FOLDER)
+    listed.add_argument(
+        "--status",
+        dest="run_status",
+        help="list only the runs Studio holds in this state",
+    )
+    listed.add_argument("--limit", type=int, help="how many runs to ask for, from 1 to 200")
+
+    scanned = _add("fleet")
+    scanned.add_argument("root", nargs="?", default=None, help=_NO_EFFECT_FOLDER)
+    scanned.add_argument(
+        "--html", action="store_true", help="no effect here; the live page is the dashboard"
+    )
+    scanned.add_argument("--limit", type=int, help="how many runs to ask for, from 1 to 200")
+
+    compared = _add("diff")
+    compared.add_argument("left", help="the first run")
+    compared.add_argument("right", help="the second run")
+    compared.add_argument(
+        "--columns-only",
+        action="store_true",
+        help="list only the changes to the columns; the count and the answer still cover them all",
+    )
+
+    # ------------------------------------------------------------------------------------
+    # The command that writes prose
+    # ------------------------------------------------------------------------------------
+    #
+    # `note` makes no translation at all, because there is nothing to translate: the local lane's
+    # decision record is a research notebook in a folder, this one is a cell in the run's log, and
+    # the two share a discipline rather than an argument surface. Every flag here therefore means
+    # exactly what it says, and `flags_without_effect` comes back empty on every invocation.
+
+    noted = _add("note")
+    noted.add_argument("--run", required=True, help=_RUN_POSITIONAL)
+    noted.add_argument(
+        "--list",
+        action="store_true",
+        help="list the cells this run holds instead of writing one, superseded ones flagged",
+    )
+    noted.add_argument(
+        "--heading",
+        help="the cell's one outcome-led line; it is what the notebook shows",
+    )
+    noted.add_argument(
+        "--cell-id",
+        dest="cell_id",
+        help=(
+            "a stable identifier for this cell; writing it again revises the cell in place. "
+            "Derived from the heading when left out"
+        ),
+    )
+    noted.add_argument(
+        "--markdown-file",
+        dest="markdown_file",
+        metavar="FILE",
+        help="the cell body, as UTF-8 markdown; read from standard input when left out",
+    )
+    noted.add_argument(
+        "--checkpoint",
+        help=(
+            "the run-event this cell is about, as the sequence or the cursor mr-data watch "
+            "printed; the notebook orders cells by it"
+        ),
+    )
+    noted.add_argument(
+        "--revise",
+        metavar="CELL_ID",
+        help="the differently named cell this one supersedes; it stays in the log and is flagged",
+    )
+
+    written = _add("notebook")
+    written.add_argument("run_dir", help=_RUN_POSITIONAL)
+    written.add_argument("--output", help=_NOTEBOOK_OUTPUT)
+
+    opened = _add("view")
+    opened.add_argument("run", help=_RUN_POSITIONAL)
+    opened.add_argument("--output", help=_NOTEBOOK_OUTPUT)
+    opened.add_argument("--open", action="store_true", help="open the document once it is here")
+    opened.add_argument("--workspace", help=_NO_EFFECT_FOLDER)
+    opened.add_argument("--run-dir", dest="run_dir", help=_NO_EFFECT_FOLDER)
+    opened.add_argument("--research-dir", dest="research_dir", help=_NO_EFFECT_FOLDER)
+    opened.add_argument("--host", help=_NO_EFFECT_SERVER)
+    opened.add_argument("--port", type=int, help=_NO_EFFECT_SERVER)
+
+    looked = _add("peek")
+    looked.add_argument("target", help=_RUN_POSITIONAL)
+    looked.add_argument(
+        "--rows", type=int, default=5, help="how many of the preview's rows to show"
+    )
+    looked.add_argument("--format", dest="data_format", help=_NO_EFFECT_DECODED)
+    looked.add_argument("--reader", help=_NO_EFFECT_DECODED)
+    looked.add_argument("--reader-options", dest="reader_options", help=_NO_EFFECT_DECODED)
+    looked.add_argument(
+        "--allow-redirect-host",
+        dest="allow_redirect_hosts",
+        action="append",
+        help=_NO_EFFECT_DECODED,
+    )
+    looked.add_argument(
+        "--json-records-pointer", dest="json_records_pointer", help=_NO_EFFECT_DECODED
+    )
+    looked.add_argument(
+        "--json-expand", dest="json_expand", action="append", help=_NO_EFFECT_DECODED
+    )
+    looked.add_argument(
+        "--json-column", dest="json_column", action="append", help=_NO_EFFECT_DECODED
+    )
+    looked.add_argument(
+        "--json-optional-column",
+        dest="json_optional_column",
+        action="append",
+        help=_NO_EFFECT_DECODED,
+    )
+    looked.add_argument(
+        "--json-document-format", dest="json_document_format", help=_NO_EFFECT_DECODED
+    )
+
+    deployment = _add("deploy-status")
+    deployment.add_argument("run_dir", help=_RUN_POSITIONAL)
+    deployment.add_argument(
+        "--watch-seconds",
+        dest="watch_seconds",
+        type=int,
+        help="no effect here; mr-data watch streams a run rather than asking again on a timer",
+    )
+
+    # ------------------------------------------------------------------------------------
+    # The two commands that write: one acquisition, and one ask a human must still settle
+    # ------------------------------------------------------------------------------------
+    #
+    # Same rule as above -- every argument the local command declares appears here under the SAME
+    # destination -- with the one translation each command needs. `acquire` needs none at all: the
+    # hosted route is the route a full install already takes when it is given neither attestation,
+    # so the document, the output directory and the allowlist mean exactly what they mean locally.
+    # `approve` needs one: `--recipe` names the approval Studio holds rather than a Recipe file,
+    # because a hosted approval is a record on the backend and there is no file here.
+
+    acquired = _add("acquire")
+    acquired.add_argument(
+        "--acquisition",
+        required=True,
+        help="acquisition document: the adapter, the request, its governance, its limits",
+    )
+    acquired.add_argument(
+        "--output", required=True, help="an existing directory; nothing is written outside it"
+    )
+    acquired.add_argument(
+        "--attempt-id",
+        dest="attempt_id",
+        required=True,
+        help="the attempt this acquisition is recorded under",
+    )
+    acquired.add_argument(
+        "--allow-host",
+        dest="allow_host",
+        action="append",
+        metavar="HOST",
+        help=(
+            "one exact hostname this acquisition may reach; repeatable; "
+            "there is no default and no environment override"
+        ),
+    )
+    acquired.add_argument(
+        "--clean-room-attestation",
+        dest="clean_room_attestation",
+        metavar="DIGEST",
+        help=_NO_EFFECT_STUDIO_CLEAN_ROOM,
+    )
+    acquired.add_argument(
+        "--network-policy-attestation",
+        dest="network_policy_attestation",
+        metavar="DIGEST",
+        help=_NO_EFFECT_STUDIO_CLEAN_ROOM,
+    )
+    acquired.add_argument(
+        "--cadence-history",
+        dest="cadence_history",
+        metavar="FOLDER",
+        help="a probe run in Studio's clean room is recorded by Studio; this is refused by name",
+    )
+    acquired.add_argument(
+        "--cadence-authority",
+        dest="cadence_authority",
+        metavar="FILE",
+        help="the cadence authority document; refused with --cadence-history, for the same reason",
+    )
+
+    from mostlyright.data_harness.thin import acquire_cancel
+
+    acquire_cancel.declare_arguments(_add("acquire-cancel"))
+
+    for name in ("approve", "recipe-approve"):
+        asked = _add(name)
+        asked.add_argument("--recipe", required=True, help=_APPROVAL_POSITIONAL)
+        asked.add_argument(
+            "--decision",
+            choices=("approved", "rejected"),
+            default="approved",
+            help="the decision to ask a person for; approved when left out",
+        )
+        asked.add_argument(
+            "--reason", help="why you are asking, shown beside your principal in the queue"
+        )
+        asked.add_argument(
+            "--wait-seconds",
+            dest="wait_seconds",
+            type=int,
+            help="how long to wait for a person; 0 records the ask and returns",
+        )
+        asked.add_argument("--output", help=_NO_EFFECT_APPROVAL_RECORD)
+        asked.add_argument("--approval-id", dest="approval_id", help=_NO_EFFECT_APPROVAL_NAMED)
+        asked.add_argument("--approved-by", dest="approved_by", help=_NO_EFFECT_APPROVAL_HUMAN)
+        asked.add_argument("--approved-at", dest="approved_at", help=_NO_EFFECT_APPROVAL_HUMAN)
+        asked.add_argument(
+            "--approval-policy", dest="approval_policy", help=_NO_EFFECT_APPROVAL_POLICY
+        )
+        asked.add_argument(
+            "--approval-policy-digest",
+            dest="approval_policy_digest",
+            help=_NO_EFFECT_APPROVAL_POLICY,
+        )
+
+    # ------------------------------------------------------------------------------------
+    # The authoring front door, and the research session it is explored through
+    # ------------------------------------------------------------------------------------
+    #
+    # No translation and no inert flag, because there is no local twin to translate from: `propose`
+    # drives Studio's own authoring routes and a research session is a warm worker on the backend,
+    # and nothing on this computer resembles either. Each declares its arguments once, in its own
+    # module, and the local parser calls the same function, so the two front doors cannot disagree.
+    from mostlyright.data_harness.thin import propose as propose_module
+    from mostlyright.data_harness.thin import research
+
+    propose_module.declare_arguments(_add("propose"))
+    for name in research.COMMANDS:
+        research.declare_arguments(name, _add(name))
+    return parser
+
+
+def _handlers() -> dict[str, Callable[[argparse.Namespace], dict[str, Any]]]:
+    from mostlyright.data_harness.thin import (
+        acquire,
+        acquire_cancel,
+        approvals,
+        commands,
+        narrative,
+        parity,
+        propose,
+        research,
+    )
+
+    return {
+        "acquire": acquire.acquire,
+        "acquire-cancel": acquire_cancel.acquire_cancel,
+        "approve": approvals.approve,
+        "recipe-approve": approvals.recipe_approve,
+        "propose": propose.propose,
+        **research.HANDLERS,
+        "build": commands.submit,
+        "run": commands.submit,
+        "watch": commands.watch,
+        "status": commands.status,
+        "deploy-dataset": commands.download,
+        "show": parity.show,
+        "inspect": parity.inspect,
+        "verify": parity.verify,
+        "list": parity.listing,
+        "fleet": parity.fleet,
+        "diff": parity.diff,
+        "note": narrative.note,
+        "notebook": parity.notebook,
+        "view": parity.view,
+        "peek": parity.peek,
+        "deploy-status": parity.deployment_status,
+    }
+
+
+def _exit_codes() -> dict[str, Callable[[dict[str, Any]], int]]:
+    """The hosted commands whose answer is a gate a script acts on rather than a report.
+
+    Derived from the payload, never returned alongside it, for the reason
+    ``ux.commands.CommandSpec`` gives: an exit code that can disagree with the printed answer is
+    an exit code somebody will trust over the answer.
+    """
+
+    from mostlyright.data_harness.thin import acquire, approvals, parity, propose, research
+
+    return {
+        "verify": parity.verify_exit_code,
+        "acquire": acquire.acquire_exit_code,
+        "approve": approvals.approve_exit_code,
+        "recipe-approve": approvals.approve_exit_code,
+        "propose": propose.propose_exit_code,
+        **research.EXIT_CODES,
+    }
+
+
+def _emit(payload: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, allow_nan=False, sort_keys=True), flush=True)
+        return
+    from mostlyright.data_harness.ux.render import render_human
+
+    print(render_human(payload), flush=True)
+
+
+def _refuse(
+    code: str,
+    detail: str,
+    *,
+    as_json: bool,
+    retry_after_seconds: int | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> int:
+    """Report one refusal the way every other ``mr-data`` refusal is reported.
+
+    Both renderings go to stderr and both carry the remediation the error map already holds for
+    this code, exactly as ``cli._print_error`` does. A hosted refusal is not a different kind of
+    refusal, so it must not read like one -- and routing it through the same map is what makes the
+    `hosted lane` family paragraph reach a person rather than sit in a table.
+
+    ``retry_after_seconds`` is the window Studio stamped on a refusal it expects to be retried --
+    a workspace that already holds its bound of live research sessions answers that way -- and it
+    is carried under the same key ``cli`` gives it, so a script reads one number in both profiles
+    rather than parsing it out of the sentence.
+    """
+
+    from mostlyright.data_harness.ux.remediation import remediation_for
+    from mostlyright.data_harness.ux.render import render_error
+
+    remediation = remediation_for(code)
+    if as_json:
+        error: dict[str, Any] = {
+            "schema_version": "mr-data-error.v1",
+            "code": code,
+            "error": detail,
+            "headline": detail,
+            "remediation": list(remediation),
+        }
+        if retry_after_seconds is not None:
+            error["retry_after_seconds"] = retry_after_seconds
+        if extra:
+            error.update(extra)
+        print(
+            json.dumps(error, ensure_ascii=False, sort_keys=True),
+            file=sys.stderr,
+            flush=True,
+        )
+    else:
+        print(render_error(detail, code=code, remediation=remediation), file=sys.stderr, flush=True)
+    return 2
+
+
+def _refusal_detail(command: str, lane: str) -> str:
+    """One sentence naming the command, saying why it is where it is, and what to do next.
+
+    The reason comes out of the classification table rather than out of a template, because the
+    three lanes are three different situations and only one of them is answered by installing
+    something. ``mr-data init`` says install the extra; ``mr-data approve`` says what is missing
+    upstream and does not pretend an install would fix it; ``mr-data-producer``'s command-line
+    twin says it is not a command anybody runs.
+    """
+
+    reason = reason_for(command)
+    if lane == LOCAL:
+        if not local_lane_platform_supported():
+            # ⚠ NOT the install hint. Naming an install that cannot help is the specific dishonesty
+            # this branch exists to prevent: `pip install "...[local]"` SUCCEEDS on Windows and
+            # buys nothing, so a person who followed that advice would arrive back here having
+            # downloaded two hundred megabytes for no reason.
+            return (
+                f"{command!r} runs on this computer -- {reason} -- and "
+                f"{LOCAL_LANE_PLATFORM_REASON}. The hosted lane runs this work instead: "
+                "mr-data --help lists the commands that run here"
+            )
+        return f"{command!r} runs on this computer -- {reason}; {LOCAL_INSTALL_HINT}"
+    if lane == HOSTED_PENDING:
+        return (
+            f"{command!r} has no hosted lane yet -- {reason}. The local execution lane still runs "
+            f"it: {LOCAL_INSTALL_HINT}"
+        )
+    return (
+        f"{command!r} is a backend operator step, not part of the hosted command surface -- "
+        f"{reason}"
+    )
+
+
+def _thin_help() -> str:
+    """The help a thin install prints: every command name, and which of them run here."""
+
+    from mostlyright.data_harness import package_version
+
+    lines = [
+        f"mr-data {package_version()} -- hosted profile (pure Python, no local execution)",
+        "",
+        "usage: mr-data <command> [options]",
+        "",
+        "Commands that run here:",
+    ]
+    for name in names_in(HOSTED):
+        lines.append(f"  {name:<24}{HOSTED_SUMMARY.get(name, '')}")
+    for name in names_in(PORTABLE):
+        lines.append(f"  {name:<24}{CLASSIFICATION[name].reason}")
+    for lane, heading in (
+        (
+            HOSTED_PENDING,
+            "Commands that should be hosted and are not yet -- run mr-data <name> to be told why:",
+        ),
+        (
+            LOCAL,
+            "Commands that need the local execution lane, which "
+            + (
+                "is not installed:"
+                if local_lane_platform_supported()
+                else "this operating system cannot host:"
+            ),
+        ),
+        (WORKER, "Backend operator steps, which are never run from here:"),
+    ):
+        names = names_in(lane)
+        if not names:
+            continue
+        lines.extend(["", heading])
+        # Three to a row: the longest name is `agent-request-validate` at twenty-two characters,
+        # and four columns of that would wrap on an eighty-column terminal.
+        for index in range(0, len(names), 3):
+            row = names[index : index + 3]
+            lines.append(("  " + "  ".join(f"{name:<24}" for name in row)).rstrip())
+    if local_lane_platform_supported():
+        lines.extend(["", f"  install the local lane with: {LOCAL_INSTALL_HINT}", ""])
+    else:
+        lines.extend(["", f"  {LOCAL_LANE_PLATFORM_REASON}", ""])
+    return "\n".join(lines)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Route one invocation to the lane that can serve it, or refuse it by name."""
+
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    hosted_requested, local_requested = _lane_flags(arguments)
+    local_available = local_lane_available()
+    as_json = "--json" in arguments
+
+    if local_requested and not local_available:
+        if not local_lane_platform_supported():
+            return _refuse(
+                LOCAL_LANE_UNSUPPORTED_PLATFORM_CODE,
+                f"--local was asked for and {LOCAL_LANE_PLATFORM_REASON}",
+                as_json=as_json,
+            )
+        return _refuse(
+            "THIN_LOCAL_LANE_UNAVAILABLE",
+            f"--local was asked for and the local execution lane is not installed; "
+            f"{LOCAL_INSTALL_HINT}",
+            as_json=as_json,
+        )
+    if local_available and not hosted_requested:
+        # The ordinary case on a full install: nothing about this invocation changes.
+        from mostlyright.data_harness.cli import main as local_main
+
+        return int(local_main(_without_lane_flags(arguments) if local_requested else arguments))
+
+    command = selected_command(arguments)
+    if command is None:
+        if "--version" in arguments:
+            from mostlyright.data_harness import package_version
+
+            print(f"mr-data {package_version()}", flush=True)
+            return 0
+        print(_thin_help(), flush=True)
+        return 0 if {"-h", "--help"} & set(arguments) else 2
+
+    lane = VOCABULARY.get(command)
+    if lane is None:
+        return _refuse(
+            "THIN_UNKNOWN_COMMAND",
+            f"there is no mr-data command named {command!r}",
+            as_json=as_json,
+        )
+    if lane in REFUSAL_CODE:
+        if hosted_requested:
+            return _refuse(
+                "THIN_COMMAND_HAS_NO_HOSTED_LANE",
+                f"{command!r} has no hosted lane: {reason_for(command)}",
+                as_json=as_json,
+            )
+        return _refuse(REFUSAL_CODE[lane], _refusal_detail(command, lane), as_json=as_json)
+    if lane == PORTABLE:
+        return _portable(command, _without_lane_flags(arguments), as_json=as_json)
+    return _hosted(command, _without_lane_flags(arguments), as_json=as_json)
+
+
+def _portable(command: str, arguments: Sequence[str], *, as_json: bool) -> int:
+    """Run one command whose existing implementation is already pure Python."""
+
+    from mostlyright.data_harness.ux.commands import discovered_commands
+
+    spec = next(
+        (item for item in discovered_commands() if item.name == PORTABLE_MODULES[command]), None
+    )
+    if spec is None:  # pragma: no cover - the descriptor tuple is closed and checked by a test
+        return _refuse(
+            "THIN_COMMAND_UNAVAILABLE", f"{command!r} is not registered", as_json=as_json
+        )
+    parser = argparse.ArgumentParser(prog=f"mr-data {command}")
+    parser.add_argument("--json", action="store_true")
+    resolved = spec.resolve()
+    resolved.add_arguments(parser)
+    remaining = list(arguments)
+    remaining.remove(command)
+    parsed = parser.parse_args(remaining)
+    try:
+        payload = resolved.run(parsed)
+    except Exception as error:
+        code = getattr(error, "code", None)
+        detail = getattr(error, "detail", None) or str(error)
+        return _refuse(code or "THIN_COMMAND_FAILED", detail, as_json=as_json)
+    _emit(payload, as_json=as_json or bool(getattr(parsed, "json", False)))
+    return 0 if resolved.exit_code is None else int(resolved.exit_code(payload))
+
+
+def _hosted(command: str, arguments: Sequence[str], *, as_json: bool) -> int:
+    """Run one hosted command, rendering a typed refusal rather than a traceback."""
+
+    from mostlyright.data_harness.thin.acquire import AcquireRefusal
+    from mostlyright.data_harness.thin.acquire_cancel import CancellationRefusal
+
+    parsed = _hosted_parser().parse_args(list(arguments))
+    try:
+        payload = _handlers()[command](parsed)
+    except AcquireRefusal as refusal:
+        # ⚠ NOT `_refuse`. A Courier that reached the source and was told no, a document whose
+        # limits are over the hosted caps, an address nobody allowlisted -- these are the local
+        # lane's own `status: "refused"` receipts, with a headline, an operator action and exit 1.
+        # Rendering them as a client-side error would report a publisher's answer in the words
+        # this product uses for a broken client.
+        _emit(refusal.to_receipt(), as_json=as_json or parsed.json)
+        return 1
+    except CancellationRefusal as refusal:
+        coordinate: dict[str, Any] = {}
+        if refusal.workspace_id is not None and refusal.crawler_session_id is not None:
+            coordinate["active_public_acquisition"] = {
+                "workspace_id": refusal.workspace_id,
+                "crawler_session_id": refusal.crawler_session_id,
+            }
+        return _refuse(
+            refusal.code,
+            refusal.detail,
+            as_json=as_json or parsed.json,
+            retry_after_seconds=refusal.retry_after_seconds,
+            extra=coordinate,
+        )
+    except ThinLaneError as refusal:
+        return _refuse(
+            refusal.code,
+            refusal.detail,
+            as_json=as_json or parsed.json,
+            retry_after_seconds=getattr(refusal, "retry_after_seconds", None),
+        )
+    except Exception as error:
+        code = getattr(error, "code", None)
+        detail = getattr(error, "detail", None) or str(error)
+        return _refuse(code or "THIN_COMMAND_FAILED", detail, as_json=as_json or parsed.json)
+    _emit(payload, as_json=as_json or parsed.json)
+    exit_code = _exit_codes().get(command)
+    return 0 if exit_code is None else int(exit_code(payload))
+
+
+__all__ = [
+    "CLASSIFICATION",
+    "HOSTED",
+    "HOSTED_FLAG",
+    "HOSTED_PENDING",
+    "LANES",
+    "LOCAL",
+    "LOCAL_FLAG",
+    "LOCAL_INSTALL_HINT",
+    "LOCAL_LANE_DISTRIBUTIONS",
+    "LOCAL_LANE_PLATFORM_REASON",
+    "LOCAL_LANE_UNSUPPORTED_PLATFORM_CODE",
+    "PORTABLE",
+    "REFUSAL_CODE",
+    "VOCABULARY",
+    "WORKER",
+    "local_lane_available",
+    "local_lane_platform_supported",
+    "main",
+    "names_in",
+    "reason_for",
+    "selected_command",
+]