mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/remediation.py

@@ -0,0 +1,2195 @@
+"""Errors name their fix: the two-layer remediation map.
+
+A typed error code is what an engineer quotes in a bug report. On its own it is not an answer, and
+for the commonest failure of all -- pointing a command at a folder that is not there -- the honest
+engineering wording reads like a security incident. This module turns a code into the two or three
+plain sentences that say what happened and what to do next.
+
+There are two layers, because 1714 typed codes across 208 prefixes can reach a person at a
+workbench, and a hand-written sentence for each one would be neither affordable nor honest:
+
+* **Families.** Every code prefix is assigned to a family. A family is one paragraph: what this
+  class of failure is about, where to look, and what to do. Every prefix has one, so no code can
+  fail to say something useful.
+* **Curated codes.** The failures a person actually meets get their own exact sentences, and where
+  one command is the whole answer, the command itself.
+
+Those two counts are not a note somebody remembered to update; `tests/test_ux_remediation.py`
+recomputes them off the live source and fails when this paragraph drifts from it.
+
+Nothing here prints, and nothing here reads the filesystem. Where a sentence turns on what is on
+disk -- whether the path is there, whether it holds a Build, what kind of thing is in the way -- the
+fact is passed in by the caller that looked, and an entry with no fact says something kind-neutral
+rather than guessing one. :mod:`ux.path_kind` is imported for the one noun that decides which of
+those wordings applies; nothing here calls it. The text is layered on top of the typed error at the
+boundary where it is rendered; it never replaces it. The machine-readable error object is unchanged
+by anything in this file.
+
+`hosted_worker.py` is deliberately not excluded from the completeness gate: its codes are reachable
+through `mr-data export-hosted-candidate`, so they resolve through the `handoff` family.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+
+from mostlyright.data_harness.ux.path_kind import (
+    A_DEVICE,
+    A_FILE,
+    A_FOLDER,
+    A_LINK,
+    A_PIPE,
+    A_SOCKET,
+    NOTHING_THERE,
+    UNKNOWN_KIND,
+)
+
+# What a sentence says when the command had no single subject path to name.
+_PATH_FALLBACK = "that path"
+
+
+@dataclass(frozen=True)
+class Family:
+    """One plain paragraph covering a whole class of failure.
+
+    ``kinds_established`` is the same declaration :class:`Remediation` carries, for a paragraph
+    reached by a whole prefix rather than by one code. It is empty for almost every family, because
+    almost no family knows what is at a path.
+    """
+
+    lines: tuple[str, ...]
+    kinds_established: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Remediation:
+    """The exact answer for one code.
+
+    ``lines`` may contain ``{path}``; it is filled with the subject path when the command had one.
+    ``command`` is used when a single command is the whole answer, and is rendered last. It belongs
+    to ``lines``: an entry that answers differently because of what the caller found on disk names
+    no command, because the command was written for the finding the default wording describes.
+    ``when_path_exists`` is the alternative wording for the entries whose plain reading would
+    otherwise be a lie when the path is in fact there. ``when_nothing_built_yet`` sits between the
+    two: the folder is there, but it holds no Build, which is a different failure from a Build that
+    cannot be opened and names a completely different fix.
+
+    ``when_not_a_file`` is the fourth, and it is claimed the other way round from the three above:
+    the default is what an entry says about a *plain file*, so this wording is used unless the
+    caller looked and found one. It may contain ``{kind}`` as well as ``{path}``, filled with the
+    plain noun for what was actually there -- and with a kind-neutral word when the look failed or
+    raced, because an entry that has been given no observation may not assert one.
+
+    ``when_not_a_folder`` is the fifth, and it is the same shape as ``when_not_a_file`` about the
+    other noun. An entry whose default is written about a folder keeps that default only where the
+    caller observed one. This prevents a file, pipe, socket, or device from receiving folder-only
+    instructions.
+
+    ``kinds_established`` is the sixth field and it is not a wording: it is what the *raise site*
+    for this code had already found by the time it raised. Some codes are themselves the
+    observation -- ``OUTPUT_SYMLINK`` is raised only after a link was met on the way down, and
+    ``PEEK_TARGET_NOT_A_FILE`` only after a descriptor reported something that is not a regular
+    file -- and a sentence for one of those may name the kind its own refusal established without
+    the caller having to look again. It may name nothing else.
+    :data:`ux.path_kind.NOTHING_THERE` is one of the kinds it can declare, because saying that
+    nothing is at a path is a claim about what is at that path exactly as much as naming a noun is.
+    The default is empty, which is what makes an entry written tomorrow red rather than quietly
+    wrong: ``scripts/path_kind_gate.py`` renders every entry under every observation a caller can
+    make and refuses any noun that neither the observation nor this field supports.
+
+    ``command_needs_a_build`` is the seventh, and it is the same declaration for an instruction
+    rather than a noun. ``mr-data show`` opens a Build folder and reads its Receipt, so naming it at
+    the subject path asserts a Build is there; at a path that is merely taken it exits 1 and points
+    back at the refusal it was offered as the fix for. An entry that declares this keeps its command
+    only where the caller looked and found a Build.
+    """
+
+    lines: tuple[str, ...]
+    command: str | None = None
+    when_path_exists: tuple[str, ...] = ()
+    when_nothing_built_yet: tuple[str, ...] = ()
+    when_not_a_file: tuple[str, ...] = ()
+    when_not_a_folder: tuple[str, ...] = ()
+    kinds_established: tuple[str, ...] = ()
+    command_needs_a_build: bool = False
+
+
+# ------------------------------------------------------------------------------------------------
+# Layer 1: families
+# ------------------------------------------------------------------------------------------------
+
+FAMILIES: dict[str, Family] = {
+    "sources": Family(
+        (
+            "This is about finding and reading the files your Recipe names.",
+            "Check that every source the message names exists inside the input folder, is a plain "
+            "file rather than a link, and can be read.",
+            "Nothing was built, so nothing has to be undone.",
+        )
+    ),
+    "reading": Family(
+        (
+            "This is about opening the bytes of a file: its format, its text encoding, and the "
+            "size limits the harness applies to anything it opens.",
+            "The Reader that opened the file names what it could not accept.",
+            "Open the file yourself to confirm it is the format you think it is, and check its "
+            "size against the limits in docs/SOURCES-AND-ACQUISITION.md.",
+        ),
+        # Every code in this family is raised by a Reader that had already opened the bytes, which
+        # `ux.plain_file` licenses only on `S_ISREG`. Telling the reader to open it themselves is
+        # therefore an instruction that returns, which is the whole of what this declaration says.
+        kinds_established=(A_FILE,),
+    ),
+    "rights": Family(
+        (
+            "This is about whether a source may be used at all, and on what terms.",
+            "Every source carries a licence, a classification, and any obligations that come with "
+            "it. One that does not clear all three is refused before a byte of it reaches a Build.",
+            "The message names the source and the term it did not clear. Either supply the "
+            "evidence that clears it, or choose a different source.",
+        )
+    ),
+    "connectors": Family(
+        (
+            "This is about the connector that reaches a source: the packaged code that opens it, "
+            "the query it is given, and the Clean room it runs in.",
+            "A connector is pinned by version and fingerprint, is given no sign-in of its own, and "
+            "has to hand back the exact bytes it was asked for.",
+            "The message names the connector and the part of that it did not keep. Nothing was "
+            "built, so nothing has to be undone.",
+        )
+    ),
+    "cadence": Family(
+        (
+            "This is about the record of how often a source actually publishes: one folder of "
+            "probes kept on this computer, one entry per probe, never rewritten.",
+            "Each entry names the exact source, the settings it was probed under, and the entry "
+            "before it. A folder is one such set of settings, so a probe taken under different "
+            "ones belongs in a different folder rather than at the end of this one.",
+            "The message names what did not line up. Nothing was built and no earlier entry was "
+            "touched, so nothing has to be undone.",
+        )
+    ),
+    "capture": Family(
+        (
+            "This is about a recording of a live source, and the batches it was sealed into on "
+            "this computer.",
+            "The message names the file and the part of it that did not hold: a recorded message "
+            "that could not be read, a connection that left a hole, or a sealed batch that no "
+            "longer matches what was written down about it.",
+            "Nothing was built, so nothing has to be undone. Record again from the messages you "
+            "kept, into a folder that holds nothing else.",
+        )
+    ),
+    "ingestion": Family(
+        (
+            "This is about the durable, resumable copy of a source: the exact source version, "
+            "its ordered chunks, and the checkpoint that joins them.",
+            "Each chunk is checked against its recorded SHA-256 before the checkpoint advances, "
+            "and a resumed run must name the same source version and predecessor it saw before.",
+            "The message names the limit, file, digest, or fence that did not hold. Keep the "
+            "checkpoint and verified chunks, repair the named storage or source-version problem, "
+            "then resume; completed chunks do not need to be downloaded again.",
+        )
+    ),
+    "cleaning": Family(
+        (
+            "This is about one cleaning step: a rename, a type change, or a column the step needs.",
+            "The message names the column and the step that stopped.",
+            "Check the column exists under exactly that name, and that the type you asked for can "
+            "hold every value already in it.",
+        )
+    ),
+    "joins": Family(
+        (
+            "This is about joining two sources together.",
+            "Check the join keys exist on both sides, hold no empty values, and match the row "
+            "relationship the Recipe declares.",
+            "The join evidence in the Build folder lists the rows that did not match.",
+        )
+    ),
+    "quality": Family(
+        (
+            "This is about the checks a Build has to pass before it can be sealed.",
+            "The message names the check that failed.",
+            "Either fix the data the check is unhappy with, or change the checks the Recipe "
+            "requires and say in the Recipe why.",
+        )
+    ),
+    "recipes": Family(
+        (
+            "This is about a Recipe, its approval, or the settings that pin how it runs.",
+            "The message names the exact field path inside the file.",
+            "Open that file, correct that one field, and run the command again.",
+        ),
+        # An uncurated code with this prefix is a field inside a document that was already read
+        # whole, and `ux.plain_file` reads a document only off a descriptor that answered `S_ISREG`.
+        # The one code in this family raised before anything is read -- `RECIPE_OUTPUT_EXISTS`, on
+        # a path that is taken -- is curated and never reaches this paragraph.
+        kinds_established=(A_FILE,),
+    ),
+    "json": Family(
+        (
+            "This is about the exact text of a JSON file the harness was told to read.",
+            "JSON is read strictly here: UTF-8 with no byte-order mark, no key written twice "
+            "inside one object, whole numbers only, and no not-a-number values. A file other "
+            "tools accept can still be refused.",
+            "The line above says what was wrong, and where inside the file it is when it is not "
+            "the whole of it.",
+        )
+    ),
+    "authoring": Family(
+        (
+            "This is about the YAML file you are writing a Recipe in.",
+            "The line above says what stopped the reading, and where.",
+            "author reads names with values under them, lists, and plain values: text, whole "
+            "numbers, decimals, true, false, and null. Anything else is refused by name rather "
+            "than guessed at, because whatever comes out of that file is what you go on to "
+            "approve.",
+        )
+    ),
+    "workbench": Family(
+        (
+            "This is about where a Workbench folder got to: the step it is on, who ran it, and "
+            "what it recorded about the last one.",
+            "Run mr-data status on the folder to see where it stopped, then mr-data resume to "
+            "carry on from that point.",
+        )
+    ),
+    "viewer": Family(
+        (
+            "This is about the local notebook viewer and the folders it watches.",
+            "Workspace mode needs one explicit research folder and either a future Workbench path "
+            "or an existing Harness Workbench. Run-directory mode accepts a future path or an "
+            "existing verified Harness Build.",
+            "Use a real existing folder with --research-dir, and replace any invalid existing "
+            "research.ipynb before starting the viewer again.",
+        )
+    ),
+    # A damaged control tree needs a fresh Workbench; status and resume read the same damaged tree.
+    "workbench record": Family(
+        (
+            "This is about the sealed control tree of a Workbench folder: the four files the job "
+            "was described in, and the durable record that pins them.",
+            "Those files are sealed when the folder is made and are never edited in place, so a "
+            "folder whose control tree no longer matches its record is not carried on from. Every "
+            "command that opens this folder will say the same thing, including status and resume.",
+            "Make a fresh Workbench folder with mr-data init, at a path that does not exist yet, "
+            "from the same four files. A Build already sealed in the damaged folder is unaffected "
+            "and can still be read: point mr-data show at the result folder inside it.",
+        )
+    ),
+    # The sealed two-reviewer review, which had no paragraph of its own until every refusal in
+    # `review.py` was given a code. `REVIEW` already belongs to `workbench` and stays there: those
+    # codes are about where a Workbench folder got to, which `mr-data status` reads and answers.
+    # These are about the documents a review is made of and the envelope they are sealed into, and
+    # "run status, then resume" is no answer to a signature that does not verify.
+    "review": Family(
+        (
+            "This is about the sealed review of a Build: the assignment that says who reviews it, "
+            "the two signed reports, and the decision sealed from them.",
+            "A review is signed by the people the assignment enrolls and is never edited "
+            "afterwards, so a report or a decision that does not match its assignment is refused "
+            "rather than repaired. The message names the document and the field it stopped on.",
+            "The Build itself is untouched: nothing about it changes when a review is refused, and "
+            "mr-data review --local runs every check this machine can run on its own.",
+        )
+    ),
+    "output": Family(
+        (
+            "This is about the path you asked the harness to write to.",
+            "Nothing is ever overwritten. Pick a path that does not exist yet, and make sure the "
+            "folder above it is a real directory you can write to.",
+            "A sealed folder is read-only on purpose, so clearing an old one takes "
+            "chmod -R u+w .work first, then remove it.",
+        )
+    ),
+    "sealing": Family(
+        (
+            "This is about a sealed Build and its Receipt: the fingerprints, the files the Receipt "
+            "lists, and the exact replay of the run.",
+            "Run mr-data verify on the Build folder to re-check it, and mr-data show to read its "
+            "Receipt.",
+            "A mismatch here means the folder is not the Build its Receipt describes. Do not "
+            "trust it, and do not edit anything inside it.",
+        )
+    ),
+    "network": Family(
+        (
+            "This is about fetching bytes over the network: the address, the name lookup, the "
+            "connection, and the limits on both.",
+            "The Courier fetches only the addresses a Recipe names and the allowlist permits.",
+            "Check the address in the Recipe first, then check the host is reachable and answers "
+            "within those limits.",
+        )
+    ),
+    "platform": Family(
+        (
+            "This step needs filesystem features your operating system does not offer, so the "
+            "harness stops rather than doing something it cannot prove.",
+            "Run mr-data preflight to see which features are missing and which commands still "
+            "work here.",
+        )
+    ),
+    "hosted lane": Family(
+        (
+            "This is about work running on the Mostly Right backend rather than on this computer: "
+            "signing in, queueing a run, watching one, and bringing its dataset back.",
+            "Nothing on this computer was changed. A run that was already queued keeps running "
+            "whatever this command answered -- watching one and downloading from one are reads, "
+            "and a submission that was refused never reached the backend at all.",
+            "The message names what did not hold. A run identifier is on the dashboard address "
+            "the submission printed; a credential is renewed with mr-data login; and a watch that "
+            "ended early can be started again, because it resumes from where it stopped.",
+        )
+    ),
+    "hosted authoring": Family(
+        (
+            "This is about authoring one hosted recipe proposal from a bundle of documents: the "
+            "Dataset, question, sources, table plan and recipe that mr-data propose reads and the "
+            "journal it writes beside them.",
+            "The bundle's journal records every resource that WAS created, so a stage that already "
+            "ran is not run again -- restore the journal if it is gone rather than re-registering. "
+            "A refused document costs nothing on the backend and is corrected and re-run; a "
+            "document changed after the resource built from it exists is refused with the document "
+            "named, and the remedy is to restore it or start a new bundle that adopts the created "
+            "resources by id.",
+            "The message names the document and what did not hold. mr-data list names the "
+            "workspace's datasets to adopt; the receipt's approve and build commands are the exact "
+            "next lines, and a confirmation in the dashboard may start the build itself.",
+        )
+    ),
+    "hosted resources": Family(
+        (
+            "This hosted worker does not have a usable finite memory boundary for graph work.",
+            "Check the worker's memory cgroup and selected memory class. The message says whether "
+            "the boundary was missing, unlimited, malformed, or below the supported graph budget.",
+            "No Build or Draft was sealed or published. Correct the worker memory allocation, "
+            "then run the hosted attempt again.",
+        )
+    ),
+    "dataset handoff": Family(
+        (
+            "This is about bringing a Build the hosted run released back to this computer and "
+            "writing its dataset notebook here.",
+            "The message names the step that stopped. Nothing on this computer was changed by a "
+            "step that did not finish: the rows are checked against the fingerprints the release "
+            "sealed, and checked again here, before anything is written.",
+            "Nothing hosted is affected either -- the released Build stays exactly where it is, "
+            "so running this again once the step the message names is fixed is safe.",
+        )
+    ),
+    "handoff": Family(
+        (
+            "This is about packaging a Build for Studio, or about a job Studio handed back.",
+            "The message names the step that stopped. Nothing was published.",
+            "The Build on your machine is untouched; you can package it again once the step the "
+            "message names is fixed.",
+        )
+    ),
+    "login": Family(
+        (
+            "This is about signing in to the Mostly Right cloud and the device credential stored "
+            "on this machine.",
+            "The message names the step that stopped: starting sign-in, waiting for browser "
+            "approval, or storing the credential.",
+            "A stopped sign-in stores nothing. Run mr-data login again to retry.",
+        )
+    ),
+    # Catalog facts and provenance require remediation distinct from Recipe source files.
+    "source catalog": Family(
+        (
+            "This is about one entry in the Source Catalog: the facts a public source is "
+            "described by, and the exact provider record each of those facts was read out of.",
+            "A fact is kept only together with the record and the path inside it that stated the "
+            "fact, so an entry whose facts and their provenance disagree is refused rather than "
+            "half-written.",
+            "The message names the field and the path inside the provider's record. Correct that "
+            "one field in the entry being written; the catalog you already have is unchanged.",
+        )
+    ),
+    # Filling that catalog from a public provider, which is the only part of it that leaves this
+    # machine.
+    "catalog fill": Family(
+        (
+            "This is about filling the Source Catalog from a public provider: the address it is "
+            "asked at, the key where one is needed to reach it, and the answers that came back.",
+            "A key is read from a file you own, one printable line of it, and it is never written "
+            "into the catalog or into a message. An answer that echoes it back, or that cannot be "
+            "read through in full before it is kept, is refused and nothing from it is retained.",
+            "The message names the part that did not hold. Nothing was published, so the catalog "
+            "you already have is unchanged and a fill that had got part-way can be started again "
+            "from its last checkpoint.",
+        )
+    ),
+    # Searching what is already on this machine, and the private index a search reads.
+    "local search": Family(
+        (
+            "This is about searching what is already on this machine: the sealed public catalog, "
+            "the private index over the Builds you have, and one search read from both.",
+            "Each store is opened at exactly the fingerprint it was published under, and every "
+            "filter, ordering and result is checked against the entries it claims to be about, so "
+            "a store or an answer that does not match its own record is refused rather than "
+            "answered from.",
+            "The message names the argument, the limit, or the root that did not hold. Correct "
+            "that one argument, or build the index again over the Builds you mean to search over; "
+            "docs/LOCAL-SEARCH.md lists the roots and fingerprints each store takes.",
+        )
+    ),
+    # Turning one converged provider sweep into catalog entries. This is not the `authoring`
+    # paragraph above it: that one is about the YAML file a person writes a Recipe in, and it is
+    # false of every one of these -- nobody is writing YAML here, and the answer to a policy
+    # coordinate that does not match, a title longer than an entry may carry, or a shard that will
+    # not read back is not "check your indentation". An answer written about a different thing is
+    # the defect this module exists to prevent, so this class gets its own paragraph.
+    "catalog authoring": Family(
+        (
+            "This is about writing the entries of one public catalog: the reviewed policy that "
+            "decides what may be said about a source, the provider records it is said from, and "
+            "the parts the entries are written into.",
+            "Only what the provider actually declared becomes a fact, under one reviewed policy "
+            "named by its own fingerprint, so a record the policy cannot honestly describe is set "
+            "aside with its reason rather than guessed at. The parts are written once and never "
+            "rewritten, and the list of them is published last.",
+            "The message names the record or the part it stopped on. Nothing was published, so the "
+            "catalog you already have is unchanged, and a run that had got part-way carries on "
+            "from what it already wrote.",
+        )
+    ),
+    # The durable generation itself: which entry a provider record is, what has happened to it,
+    # what changed since last time, and the receipt that says a generation was published.
+    "catalog generation": Family(
+        (
+            "This is about one published generation of a public catalog: which entry each "
+            "provider record is, the history kept for it, what changed since the last sweep, and "
+            "the receipt that describes the whole of it.",
+            "A record keeps one identity for as long as the provider keeps it, its history is "
+            "only ever added to, and a generation is compared against the exact predecessor it "
+            "names. The receipt carries the earlier stages' own receipts rather than a summary of "
+            "them, and a generation is read back off disk before that receipt is written.",
+            "The message names the coordinate, the count, or the bound that did not hold. Nothing "
+            "was published, so the generation you already have is unchanged, and a publication "
+            "that had got part-way carries on without doing its work again.",
+        )
+    ),
+    # Installing a published generation on this computer, with nothing but digests to trust.
+    "catalog update": Family(
+        (
+            "This is about installing a published catalog release on this computer: the archive "
+            "it arrives as, the exact SHA-256 published next to it, and the generation already "
+            "installed that the new one must descend from.",
+            "Nothing in the archive is trusted until its bytes match the published SHA-256, and "
+            "the installed folder is read back and checked end to end before the recorded state "
+            "advances. A release that does not name the installed generation as its predecessor "
+            "is refused rather than installed over it.",
+            "The message names the archive, the digest, or the link that did not hold. The "
+            "generation you already have is untouched, so searches keep working while you sort "
+            "it out.",
+        )
+    ),
+    # The optional model those searches can be ordered by, kept on this machine and pinned.
+    "search model": Family(
+        (
+            "This is about the search model kept on this machine: the pinned files it is made of, "
+            "the optional runtime that loads them, and the one bounded process it is asked in.",
+            "The whole model folder is opened without following links and checked against its "
+            "PIN.json before anything is loaded, and every answer it gives is held to the shape, "
+            "the size and the time it was pinned to.",
+            "The message names the file or the limit that did not hold. Put that folder in place "
+            "again from the pinned coordinate, install the optional runtime it names, and give "
+            "the command its absolute path; docs/LOCAL-SEARCH.md says how. Searching by words "
+            "alone needs none of it.",
+        )
+    ),
+}
+
+
+# ------------------------------------------------------------------------------------------------
+# Layer 1: every code prefix, assigned
+# ------------------------------------------------------------------------------------------------
+#
+# The prefix list is mechanical (an `ast` walk over the raise sites); the assignment below is a
+# judgement, written out by hand. `tests/test_ux_remediation.py` fails when a new prefix appears
+# here without an assignment.
+
+PREFIX_FAMILY: dict[str, str] = {
+    "INGESTION": "ingestion",
+    "VIEWER": "viewer",
+    "VISUAL": "viewer",
+    # Finding and reading the files a plan names
+    "SOURCE": "sources",
+    "UNKNOWN": "sources",
+    "SAME": "sources",
+    "ROOT": "sources",
+    "MISSING": "sources",
+    "EVIDENCE": "sources",
+    "ENDPOINT": "sources",
+    "COUNT": "sources",
+    "UNSUPPORTED": "sources",
+    "HTTPS": "sources",
+    "SNAPSHOT": "sources",
+    "INPUT": "sources",
+    "DELAY": "sources",
+    "FITNESS": "sources",
+    "UNFIT": "sources",
+    "CATALOG": "sources",
+    "EMBEDDING": "sources",
+    "PROBE": "sources",
+    # The recorded publication-behaviour evidence, which is its own thing: not the source, not
+    # the connector that reached it, and not a Build.
+    "CADENCE": "cadence",
+    "RECOMMENDATION": "sources",
+    "REQUIREMENT": "sources",
+    "DISCOVERY": "sources",
+    # Whether a source may be used at all, and on what terms
+    "RIGHTS": "rights",
+    "LICENSE": "rights",
+    "CLASSIFICATION": "rights",
+    "OBLIGATION": "rights",
+    "CONDITIONAL": "rights",
+    "USE": "rights",
+    "DELETION": "rights",
+    "REMOVAL": "rights",
+    "RETENTION": "rights",
+    "TOMBSTONE": "rights",
+    "REJECTED": "rights",
+    # The packaged connector that reaches a source, and what it hands back
+    "ADAPTER": "connectors",
+    "STREAM": "connectors",
+    "SANDBOX": "connectors",
+    "QUERY": "connectors",
+    "SECRET": "connectors",
+    "TRUSTED": "connectors",
+    "AUTHENTICATED": "connectors",
+    "GOVERNED": "connectors",
+    "STORAGE": "connectors",
+    "ACQUIRED": "connectors",
+    "ACQUISITION": "connectors",
+    # `mr-data acquire`'s own refusals -- the document it was given, the allowlist it was given,
+    # and the hosted contract's caps. They are about reaching a source and the terms of doing so,
+    # which is what the connector family already answers for.
+    "ACQUIRE": "connectors",
+    "HOSTED": "connectors",
+    "PARSED": "connectors",
+    "RECORDED": "connectors",
+    "OBSERVATION": "connectors",
+    "EVENT": "connectors",
+    "WATERMARK": "connectors",
+    "VALUE": "connectors",
+    "RECEIPT": "connectors",
+    # The Receipt has to say which Reader opened the bytes, or say nothing at all; a half-stated
+    # decode identity is refused on the same side of the line as the rest of the Receipt's fields.
+    "DECODE": "connectors",
+    "TEMPORAL": "connectors",
+    "LIFECYCLE": "connectors",
+    # Opening the bytes
+    "DOCUMENT": "reading",
+    "PARSE": "reading",
+    "CSV": "reading",
+    "MEDIA": "reading",
+    "PEEK": "reading",
+    "GRIB": "reading",
+    "PLANNED": "reading",
+    "READER": "reading",
+    "SELECTOR": "reading",
+    "SIDECAR": "reading",
+    # Cleaning operations
+    "CAST": "cleaning",
+    "DECIMAL": "cleaning",
+    "CLEAN": "cleaning",
+    "RENAME": "cleaning",
+    "COLUMN": "cleaning",
+    "GRAIN": "cleaning",
+    "GRAPH": "recipes",
+    "OPERATION": "recipes",
+    "PREDICTION": "recipes",
+    "TARGET": "recipes",
+    # Joins
+    "JOIN": "joins",
+    # The checks a build must pass
+    "QUALITY": "quality",
+    "ROW": "quality",
+    "UNIQUE": "quality",
+    "VALIDATION": "quality",
+    "COVERAGE": "quality",
+    # Recipes, approvals, run settings, and the shape of the files they name
+    "RECIPE": "recipes",
+    # A declared unit and the grammar that resolves it. `UNIT_*` is raised where a contract reads
+    # the declaration; `UCUM_*` is raised inside the grammar itself and reaches a person through
+    # the same contract. Both are somebody writing a Recipe or a semantics document, so both
+    # answer where the rest of that writing does, and the ones a person actually meets are curated
+    # above so they can name `docs/UNITS.md` rather than a generic field correction.
+    "UNIT": "recipes",
+    "UCUM": "recipes",
+    "TYPE": "recipes",
+    "VERSION": "recipes",
+    "FIELDS": "recipes",
+    "IDENTIFIER": "recipes",
+    "INTEGER": "recipes",
+    "ENUM": "recipes",
+    "STRING": "recipes",
+    "SHA256": "recipes",
+    "RANGE": "recipes",
+    "UTC": "recipes",
+    "POSIX": "recipes",
+    "CONTROL": "recipes",
+    "NONCANONICAL": "recipes",
+    "EMPTY": "recipes",
+    "COLLECTION": "recipes",
+    "DUPLICATE": "recipes",
+    "REFERENCE": "recipes",
+    "CONTEXT": "recipes",
+    "ENGINE": "recipes",
+    "BACKEND": "recipes",
+    "TEXT": "recipes",
+    "UNICODE": "recipes",
+    "TIMESTAMP": "recipes",
+    "LIMIT": "recipes",
+    "SEMVER": "recipes",
+    "COMMIT": "recipes",
+    "DOTTED": "recipes",
+    "SAFE": "recipes",
+    "DATA": "recipes",
+    "BOOLEAN": "recipes",
+    # The exact text of a JSON file, whoever wrote it
+    "JSON": "json",
+    # Writing the entries of a public catalog. The one other thing spelled `AUTHOR_` in this tree
+    # is `AUTHOR_YAML_*`, which is a person writing a Recipe in YAML and is routed by the compound
+    # table below; everything else under this prefix is the catalog authoring stage.
+    "AUTHOR": "catalog authoring",
+    # Workbench folder state and the durable run. The split is by who can answer: `RESUME`,
+    # `REVIEW` and `PRODUCER` are about where the run got to, and `mr-data status` reads that and
+    # says so. `WORKSPACE`, `RUN` and the two `DEFINITION` prefixes are about the control tree
+    # itself -- and every command that opens the folder, `status` included, opens that tree first,
+    # so naming status as the fix for one of these names a loop.
+    "WORKSPACE": "workbench record",
+    "RUN": "workbench record",
+    "DEFINITION": "workbench record",
+    "DEFINITIONS": "workbench record",
+    "RESUME": "workbench",
+    "REVIEW": "workbench",
+    "PRODUCER": "workbench",
+    # The documents a sealed review is made of, and the envelope they are sealed into. Every one
+    # of these prefixes is raised in `review.py`, which is reached by `mr-data review`,
+    # `mr-data verify` and `mr-data sign-review`.
+    "ASSIGNMENT": "review",
+    "REPORT": "review",
+    "DECISION": "review",
+    "ENVELOPE": "review",
+    "LOCK": "review",
+    "KEY": "review",
+    # Paths written to
+    "OUTPUT": "output",
+    # Sealing and re-checking a build
+    "CANDIDATE": "sealing",
+    "PROFILE": "sealing",
+    "MANIFEST": "sealing",
+    "MEMBER": "sealing",
+    "REPLAY": "sealing",
+    "DIGEST": "sealing",
+    "DATASET": "sealing",
+    # Listing the builds under a folder. Both codes it raises today are curated; the family is here
+    # so a new one cannot arrive unassigned, and `sealing` is the right paragraph because reading a
+    # listing is reading sealed Builds -- with the class rule above keeping the tamper wording away
+    # from a folder that holds none.
+    "LIST": "sealing",
+    # Fetching over the network
+    "URL": "network",
+    "DNS": "network",
+    "EGRESS": "network",
+    "TLS": "network",
+    "HTTP": "network",
+    "PEER": "network",
+    "REDIRECT": "network",
+    "REQUEST": "network",
+    "RESPONSE": "network",
+    "RATE": "network",
+    "TIMEOUT": "network",
+    "TOTAL": "network",
+    "TRANSPORT": "network",
+    "CONCURRENCY": "network",
+    "CONTENT": "network",
+    "USER": "network",
+    "OBFUSCATED": "network",
+    "NON": "network",
+    "METADATA": "network",
+    "RESOLUTION": "network",
+    "BYTE": "network",
+    "LIMITER": "network",
+    "MULTIPART": "network",
+    "RETRIEVAL": "network",
+    "UNSOLICITED": "network",
+    # Operating-system support refusals
+    "PLATFORM": "platform",
+    # Packaging for Studio and the jobs it hands back
+    "ARTIFACT": "handoff",
+    "API": "handoff",
+    "STUDIO": "handoff",
+    "SIGNED": "handoff",
+    "SIGNING": "handoff",
+    "VERIFIER": "handoff",
+    "CRAWLER": "handoff",
+    "CREDENTIAL": "handoff",
+    "JOB": "handoff",
+    "DESCRIPTOR": "handoff",
+    "BOOTSTRAP": "handoff",
+    "WORKER": "handoff",
+    "WORKLOAD": "handoff",
+    # A research session's worker is a Builder-role attempt on a session-scoped run, so its
+    # refusals are the same subject as every other hosted attempt's: something about handing
+    # work to the backend did not hold. It sits here rather than under `sources` -- where
+    # `PROBE` sits, because a probe is about a source -- because a lease is about the worker.
+    "SESSION": "handoff",
+    "CAPABILITY": "handoff",
+    "PREDECESSOR": "handoff",
+    "PLAN": "handoff",
+    "DEPLOY": "handoff",
+    # Signing in to the cloud, and the device credential `mr-data login` stores locally.
+    "LOGIN": "login",
+    # The direct Cloud device-key client serves the same sign-in and credential lifecycle as the
+    # command's `LOGIN_*` outcomes. Its errors need the same human explanation, while keeping the
+    # Cloud-owned error names distinct on the wire.
+    "CLOUD": "login",
+    # A hosted run refused before any worker exists, because the workspace is over one of its
+    # standing allowances. It is raised where the job is taken up, beside the other worker codes.
+    "ADMISSION": "handoff",
+    # One entry in the Source Catalog. All five are raised while a v2 entry is being made: the
+    # harvester that stated a fact, the fact's own value and provenance, the order its provider
+    # paths are written in, the shape of one of those paths, and the whitespace inside one.
+    "COORDINATE": "source catalog",
+    "FACT": "source catalog",
+    "ORDER": "source catalog",
+    "PROVIDER": "source catalog",
+    "UNSAFE": "source catalog",
+    # Filling that catalog from a public provider. `DATAGOV` is the keyed metadata endpoint --
+    # the key file, the rate it allows, and what came back through it -- and `FILL` is the address
+    # the fill was pointed at. Neither is the `network` paragraph: that one is about the addresses
+    # a Recipe names and about a Courier that is never given a sign-in, and both halves are wrong
+    # here.
+    "DATAGOV": "catalog fill",
+    "FILL": "catalog fill",
+    # Searching the two stores on this machine, and publishing the private one. `LOCAL` covers the
+    # search itself and the record it keeps; `BUILD` and `INDEX` are raised while the private index
+    # is built over the Builds already sealed here.
+    "LOCAL": "local search",
+    "BUILD": "local search",
+    "INDEX": "local search",
+    # The optional model a search can be ordered by. It is not `local search`: that paragraph
+    # answers a filter or a fingerprint somebody passed, and none of these is about one -- a model
+    # folder that does not match its PIN.json is put in place again rather than corrected.
+    "NEURAL": "search model",
+    # Reading one page of a public provider's answer, and the harvester that knows how. `HARVEST`
+    # and `HARVESTER` are the parser and the registry it is looked up in, and `RECORD` is the one
+    # bare identifier check beside them; all three are reached only while a catalog is being
+    # filled, so they answer with the same paragraph the address and the key do.
+    "HARVEST": "catalog fill",
+    "HARVESTER": "catalog fill",
+    "RECORD": "catalog fill",
+    # The durable generation: which entry a provider record is, what changed since last time, and
+    # the receipt that describes a whole published generation.
+    "IDENTITY": "catalog generation",
+    "DELTA": "catalog generation",
+    "GENERATION": "catalog generation",
+    "PUBLISH": "catalog generation",
+    # The range-local parts one generation is published as, and read back from: its packs, their
+    # members, the postings and bounds over them, the head that names them and the work journal an
+    # interrupted publication leaves. Ninety-three codes, raised from three modules, every one of
+    # them about the durable generation this paragraph is written about -- including the ones
+    # raised while reading it back, because what a reader refuses there is the generation. The nine
+    # spelled `PACKED_SEARCH_` are the exception, and the compound table below routes them.
+    "PACKED": "catalog generation",
+    # A response over the byte budget kept across a redirect chain, raised beside the other
+    # retrieval limits.
+    "AGGREGATE": "network",
+    # Every refusal the thin hosted lane raises. The prefix is one word on purpose: the lane is one
+    # subject -- work that happens on the backend -- and splitting it by whether the credential,
+    # the submission, the stream or the download is what stopped would put four paragraphs in front
+    # of a reader who needs the one sentence the message already carries.
+    "THIN": "hosted lane",
+}
+
+
+# The same table one segment deeper, consulted first, for the few prefixes that are honestly two
+# different subjects. It exists for exactly one shape: a prefix whose codes were written by two
+# lanes about two things, where routing the whole prefix to either family would put a paragraph
+# about one in front of somebody looking at the other.
+#
+# `AUTHOR_YAML_*` is a person writing a Recipe in YAML; every other `AUTHOR_*` code is the catalog
+# authoring stage, and the plain answer for one is false of the other. `DIGEST` -- the bare code,
+# not a prefix -- is a fingerprint field inside a provider's page, and the `sealing` paragraph it
+# would otherwise reach is about a sealed Build and tells the reader to run `mr-data verify` on a
+# folder that has nothing to do with it. `RECORD_ID` is the same case one file over.
+#
+# `PACKED_SEARCH_*` is the third case: every other `PACKED_*` code is about the published
+# generation itself, and these nine are about one question asked of it -- the store it was asked
+# in, the budget it was given, and the order of the answer. Somebody whose search was refused for
+# a limit is not being told that nothing was published and their catalog is unchanged; they are
+# being told which argument, limit or root did not hold, which is the `local search` paragraph.
+COMPOUND_PREFIX_FAMILY: dict[str, str] = {
+    # Sealing a recording is not reaching a source: no connector runs, no Clean room opens, and
+    # the answer is about a file on this computer. The connector *configuration* stays with the
+    # connectors, because that is what it is about.
+    "STREAM_CAPTURE": "capture",
+    "STREAM_RECORDING": "capture",
+    "STREAM_MESSAGE": "capture",
+    "STREAM_EVENT": "capture",
+    # A rights-decision refusal is about deciding rights again, not about reading files.
+    "CATALOG_RIGHTS": "rights",
+    # An install refusal is about the release on this computer, not about the catalog's content.
+    "CATALOG_UPDATE": "catalog update",
+    "AUTHOR_YAML": "authoring",
+    "THIN_PROPOSE": "hosted authoring",
+    "DIGEST": "catalog fill",
+    "RECORD_ID": "catalog fill",
+    "PACKED_SEARCH": "local search",
+    # Worker memory provisioning is operational capacity, not a source connector.
+    "HOSTED_MEMORY": "hosted resources",
+    # Bringing a released Build back is the opposite direction from packaging one and sending it,
+    # which is what the deployment family's paragraph is about. Every code on the return trip
+    # answers through its own subject instead, so the ones with no sentence of their own still say
+    # something true.
+    "DEPLOY_DATASET": "dataset handoff",
+}
+
+
+def family_for(code: str) -> str:
+    """The family one code answers through: its first two segments, then its first.
+
+    Read in that order so a compound entry can correct a prefix rather than having to replace it,
+    which keeps the table above a list of subjects rather than a list of exceptions.
+    """
+
+    parts = code.split("_")
+    compound = "_".join(parts[:2])
+    if compound in COMPOUND_PREFIX_FAMILY:
+        return COMPOUND_PREFIX_FAMILY[compound]
+    return PREFIX_FAMILY.get(parts[0], "")
+
+
+# ------------------------------------------------------------------------------------------------
+# Layer 2: curated codes
+# ------------------------------------------------------------------------------------------------
+#
+# The order below is the order the recorded quirks were found by driving the example build.
+
+_PIN_DRIFT = (
+    "The run settings pin a Recipe fingerprint and an exact set of engine versions. One of them "
+    "no longer matches what is installed here.",
+    "Re-export the Recipe, read the fingerprint off the recipe-export receipt, and put it in "
+    "recipe-execution.json.",
+    "The message names the field that does not match.",
+)
+
+_OVERWRITE = (
+    "{path} already holds something, and builds are never overwritten.",
+    "Choose a name that is not in use, or look at what is already there.",
+)
+
+# The same refusal about a path that is taken by something that is not a Build. `OUTPUT_EXISTS` is
+# raised by every writer that will not overwrite a folder, and the caller that looks before it
+# speaks -- the command line's error boundary, and `mr-data preflight` -- reports what it found. A
+# Recipe file, an approval, a signed report or any ordinary file in the way is not a build, and
+# `mr-data show` on one answers with a path complaint harder to read than the refusal it was
+# offered as the fix for. So the noun moves and the command goes, on the evidence rather than on a
+# guess about which command was running.
+# Two sentences, neither of which points at a neighbouring line: this wording is printed by a
+# refusal, where what was being written is named above it, and by `mr-data preflight`, where the
+# advice block is printed before the checks it is about.
+# `ls -l` reports every path kind without opening a potentially blocking object.
+_OVERWRITE_NOT_A_BUILD = (
+    "{path} already holds something that is not a build, and nothing here is ever overwritten.",
+    "Choose a name that is not in use, or run ls -l on that path to see what is there.",
+)
+
+# These refusals concern files, not Build folders. No trailing command is safe for every file type.
+_RECIPE_OVERWRITE = (
+    "{path} already holds a file, and nothing written here is ever overwritten.",
+    "The line above says what was being written: a Recipe, or an approval of one.",
+    "Choose a name that is not in use, or open the file that is already there to see which it is.",
+)
+
+_PACKAGED_OVERWRITE = (
+    "{path} already holds a file, and nothing written here is ever overwritten.",
+    "The line above says what was being written: one Build, packaged for Studio.",
+    "Choose a name that is not in use, or open the file that is already there.",
+)
+
+
+# The same three refusals, about a taken path that is not a file at all.
+#
+# All three are raised on the one `FileExistsError` that `O_CREAT | O_EXCL | O_NOFOLLOW` gives back,
+# and that errno is what a folder, pipe, socket, device, or link can return. The wording must not
+# assert a file kind that was never observed or recommend opening a potentially blocking object.
+#
+# The repair is not a fourth sentence about pipes. The writer now looks, once, at the descriptor it
+# already holds, and what it saw fills `{kind}`; where it saw nothing the noun is kind-neutral and
+# nothing is claimed. `ls -l` is the named command because it is the one reading that answers on
+# every one of those kinds -- and on a link, where it also says where the link points -- without
+# opening anything.
+def _taken_by_something_else(*middle: str) -> tuple[str, ...]:
+    return (
+        "{path} already holds {kind}, and nothing written here is ever overwritten.",
+        *middle,
+        "Choose a name that is not in use, or run ls -l on that path to see what is there.",
+    )
+
+
+_RECIPE_OVERWRITE_KIND = _taken_by_something_else(
+    "The line above says what was being written: a Recipe, or an approval of one.",
+)
+
+_PACKAGED_OVERWRITE_KIND = _taken_by_something_else(
+    "The line above says what was being written: one Build, packaged for Studio.",
+)
+
+_SIGNED_REPORT_OVERWRITE_KIND = _taken_by_something_else()
+
+_PLATFORM = (
+    "This step needs filesystem features your operating system does not offer, so the harness "
+    "stops rather than doing something it cannot prove.",
+    "Everything that does not need those features still works.",
+)
+
+# ------------------------------------------------------------------------------------------------
+# The class rule: no answer about a Build may be given where there is no Build
+# ------------------------------------------------------------------------------------------------
+#
+# Curating one code at a time fixes one instance at a time. The `sealing` family is written about a
+# Build whose Receipt and bytes disagree, and its sentences -- "do not trust it", "do not edit
+# anything inside it" -- are a tamper diagnosis. Given a folder with nothing built in it, every one
+# of them is false, and false in the direction that frightens people. So the rule is stated once,
+# over the whole family, rather than one curated code at a time: when the caller looked and found no
+# Build, an uncurated sealing code does not fall through to that paragraph.
+#
+# Curated entries are not overridden. An entry is a sentence someone wrote for one exact failure,
+# and some of them -- a link on the way in, a race, an output path already in use -- are true
+# whether or not a Build is there. An entry that needs the alternative declares it, as
+# `CANDIDATE_ABSENT` and `CANDIDATE_ANCESTOR_INVALID` do.
+
+_ABOUT_AN_EXISTING_BUILD: frozenset[str] = frozenset({"sealing"})
+
+NOTHING_BUILT_YET: tuple[str, ...] = (
+    "{path} is there, but nothing has been built in it yet, so there is no Build to read or check.",
+    "Run mr-data list to see the builds you have, or mr-data build to make one.",
+    "If you were expecting a build there, check the path: it is usually the folder just above or "
+    "just below the one you named.",
+)
+
+
+CODES: dict[str, Remediation] = {
+    "TABLE_PREVIEW_INVALID": Remediation(
+        lines=(
+            "The sealed Table could not be rendered as a bounded preview.",
+            "Verify the Build and rebuild the Table from its pinned Recipe and inputs.",
+        )
+    ),
+    # A retired operation is the one refusal where "correct that one field and run it again" is
+    # not merely vague but impossible: no value the field can take makes the plan valid, and the
+    # nearest thing an author reaches for next -- lag, lead, rolling, window_target -- is refused
+    # by name a layer down. So this code answers for itself rather than through its family.
+    "OPERATION_RETIRED": Remediation(
+        lines=(
+            "That operation has been retired, so a new plan cannot name it. This is not a "
+            "spelling or a version you can correct: there is no value that field can take that "
+            "makes the plan valid.",
+            "Remove the node and the output column it produced, and point the plan's terminal at "
+            "the node it followed. Nothing replaces it, and a window, lag, lead, or rolling "
+            "operation is not a substitute -- those are refused by name as well. Neither is a "
+            "derive expression or an extra join that reproduces the same thing.",
+            "A Build already sealed with the operation, and a Recipe already approved with it, "
+            "are unaffected: those still verify and still run.",
+        )
+    ),
+    "UNIT_CODE": Remediation(
+        lines=(
+            "That is not a unit code. A unit is written in the accepted subset of the unit "
+            "standard -- `m`, `cm`, `ug/m3`, `km/h`, `Cel` -- rather than in words, and the "
+            "message names the part of what you wrote that put it outside that subset.",
+            "The whole accepted subset, what it refuses, and the fifteen older names that still "
+            "work are in docs/UNITS.md. Where a column carries no physical unit at all, a "
+            "semantics document declares `none` -- but a plan declares nothing, so leave the "
+            "column out of `column_units`, or leave `output_unit` off the expression.",
+        )
+    ),
+    "UNIT_DIMENSION_MISMATCH": Remediation(
+        lines=(
+            "Two values the plan brings together are declared in units that do not measure the "
+            "same kind of thing -- a length against a time, say. No conversion exists between "
+            "them, so this is a declaration to correct rather than arithmetic to add.",
+            "The message names both declarations. Check which of the two is wrong against the "
+            "source it came from, and correct it where it was declared -- on the `column_units` "
+            "of a source node, or on an expression's `output_unit`.",
+        )
+    ),
+    "UNIT_CONVERSION_MISSING": Remediation(
+        lines=(
+            "Two values the plan brings together measure the same thing in different units, and "
+            "nothing in the plan converts one to the other. Combining them would produce a value "
+            "that is part one unit and part another.",
+            "Add a derive node before the merge that converts one side, and declare the unit its "
+            "result is in. That declared conversion is checked against the arithmetic you wrote, "
+            "so a wrong factor is refused rather than trusted.",
+            "The derive has to write a new column: a derive that reuses the name it reads from is "
+            "refused when the plan runs. Project the original away and rename the new one, so the "
+            "two sides of the merge carry the same columns in the same order.",
+        )
+    ),
+    "UNIT_CONVERSION_FACTOR": Remediation(
+        lines=(
+            "The expression does not do what converting between those two units requires. The "
+            "message states the arithmetic the units imply and the arithmetic the expression "
+            "performs, in that order.",
+            "There are three ways out. Correct the expression; correct the declared unit if the "
+            "expression was right; or drop `output_unit` where the expression was never a "
+            "conversion at all, because an undeclared result claims nothing and is checked "
+            "against nothing.",
+            "A temperature conversion has two parts -- Celsius to Fahrenheit is a multiply by 9/5 "
+            "and an add of 32 -- and doing only the first is what this refusal usually means.",
+            "There is no decimal literal in a plan, so write the fraction as whole numbers with "
+            "the division last: `(x * 9 + 160) / 5` rather than `x * 9 / 5 + 32`. Every operation "
+            "takes operands of one exact numeric type and a quotient lands in the decimal type, so "
+            "a whole number added after a division is refused when the plan runs.",
+        )
+    ),
+    "UNIT_CONVERSION_UNVERIFIABLE": Remediation(
+        lines=(
+            "The unit declared for this expression cannot be checked against anything, and a "
+            "claim nobody can check is the thing these gates exist to stop. The message says "
+            "which of three reasons applies.",
+            "A unit is admitted only where something establishes it: the expression converts one "
+            "declared column and the arithmetic is exactly that conversion; or its operands "
+            "settle what it is in, every one read unscaled; or nothing it reads is declared. "
+            "Write the conversion as whole-number multiplies, divides and adds over one declared "
+            "column, and put any branching in another node.",
+            "Declaring the other columns it reads does not help on its own -- what is checked is "
+            "whether the arithmetic can be read, not who declared what.",
+            "Dropping `output_unit` is always available: the result then carries no unit claim, "
+            "and nothing downstream can rely on one.",
+        )
+    ),
+    "UNIT_UNSUPPORTED_IN_VERSION": Remediation(
+        lines=(
+            "This document is written at a semantics generation whose unit vocabulary is the "
+            "fifteen original names, and the unit named here is a code from the wider subset.",
+            "Either write the older name for the same unit, or move the document to "
+            "`table-semantics.v2`, which carries any code the grammar resolves. That is a "
+            "change to the document's `schema_version` rather than to the field this message "
+            "points at. Both generations are read forever; see docs/UNITS.md.",
+        )
+    ),
+    "CATALOG_UPDATE_CHAIN": Remediation(
+        lines=(
+            "The release you gave does not descend from the generation installed here.",
+            "If you skipped releases, install them in order. Only when you trust where this "
+            "release's digest came from, run the update again with --replace to accept it as "
+            "the new starting point.",
+        )
+    ),
+    "CATALOG_UPDATE_DIGEST": Remediation(
+        lines=(
+            "The archive's bytes do not match the SHA-256 you typed.",
+            "Copy the digest again from where the release was published, and download the "
+            "archive again if it still does not match.",
+        )
+    ),
+    "CATALOG_UPDATE_DIGEST_SPELLING": Remediation(
+        lines=(
+            "What you typed after --archive-sha256 is not the shape of a SHA-256.",
+            "Copy the digest again exactly as published: 64 hex characters, all lowercase, "
+            "with no prefix around them. The archive itself was not judged.",
+        )
+    ),
+    "CATALOG_UPDATE_INSTALL": Remediation(
+        lines=(
+            "The release could not be written into the catalog folder.",
+            "The message names the path in the way. Remove it only if it is an unfinished "
+            "leftover or not this release's bytes, check free space and permissions, and run "
+            "the update again; nothing recorded has changed.",
+        )
+    ),
+    "VISUAL_RUN_TERMINAL": Remediation(
+        lines=(
+            "That visual research run has already ended and cannot accept more events.",
+            "A completed run is read-only; use its existing Build. If it failed, start a new "
+            "research run before retrying the Build.",
+        )
+    ),
+    # Distinguish an absent Build from a present path that cannot be opened safely.
+    "CANDIDATE_ANCESTOR_INVALID": Remediation(
+        lines=(
+            "There is no build at {path}.",
+            "Run mr-data list to see the builds you have, or mr-data init to start one.",
+        ),
+        # The folder is there and holds nothing built. Diagnosing a link or a race here is the one
+        # way this map can be worse than silence: it would send someone looking for tampering when
+        # all they have done is not run the build yet.
+        when_nothing_built_yet=(
+            "{path} is there, but nothing has been built in it yet.",
+            # This branch knows only that the path exists, not that it is a Workbench folder.
+            "mr-data status says how far a workbench folder got, and mr-data run builds it.",
+            "mr-data list shows the builds you already have.",
+        ),
+        # Folder-only advice is withheld when the observed object has another concrete kind.
+        when_not_a_folder=(
+            "There is {kind} at {path}, and a build is read out of a folder.",
+            "Point the command at the Build folder itself, or at the workbench folder that holds "
+            "one.",
+            "mr-data list shows the builds you already have.",
+        ),
+        when_path_exists=(
+            "{path} is there, but the folders leading to it could not be opened safely.",
+            # This code establishes only a non-folder or a race; links have a distinct code.
+            "A step of that path is not a plain folder, or it changed while it was being opened.",
+            "Move the build to a plain, stable path and try again.",
+        ),
+    ),
+    "CANDIDATE_ANCESTOR_SYMLINK": Remediation(
+        lines=(
+            "A folder on the way to {path} is a link, and the harness will not follow one.",
+            "Use the real path, or move the build somewhere that has no links above it.",
+        ),
+        # `pipeline._open_candidate_run_chain` raises this only inside `if stat.S_ISLNK(...)`, on
+        # the component it names. The kind is the reason the refusal exists, so the sentence may
+        # say it without the boundary looking a second time and answering about a later moment.
+        kinds_established=(A_LINK,),
+    ),
+    # Raised only by the hosted producer, while turning the Build's own sealed column summary
+    # into the document the service's contract describes. Nothing the caller did on this machine
+    # causes it, and nothing they can do on this machine fixes it -- so the lines say what is
+    # known and point at the people who can act, rather than inventing a step.
+    "PROFILE_INVALID": Remediation(
+        lines=(
+            "The column summary sealed into this Build could not be turned into the one the "
+            "service reads.",
+            "The Build itself is fine. This is a mismatch between the harness and the service, "
+            "so report it rather than rebuilding.",
+        ),
+    ),
+    "CANDIDATE_ANCESTOR_RACE": Remediation(
+        lines=(
+            "The folders leading to {path} changed while they were being opened.",
+            "Something else is moving or replacing them. Stop that, then run the command again.",
+        ),
+    ),
+    # Only the Build-folder refusal may name a command that opens what is in the way, and only when
+    # the caller observed a Build there. `OUTPUT_EXISTS` is raised on a bare
+    # "this path is taken" test by every writer that will not overwrite a folder, so the path in
+    # the way is regularly a file; the alternative wording below is what a caller that looked gets.
+    "OUTPUT_EXISTS": Remediation(
+        lines=_OVERWRITE,
+        command="mr-data show {path}",
+        when_nothing_built_yet=_OVERWRITE_NOT_A_BUILD,
+        # `mr-data show` is valid only when the caller observed a Build at this path.
+        command_needs_a_build=True,
+    ),
+    "RECIPE_OUTPUT_EXISTS": Remediation(
+        lines=_RECIPE_OVERWRITE,
+        when_not_a_file=_RECIPE_OVERWRITE_KIND,
+    ),
+    "CANDIDATE_ENVELOPE_OUTPUT_EXISTS": Remediation(
+        lines=_PACKAGED_OVERWRITE,
+        when_not_a_file=_PACKAGED_OVERWRITE_KIND,
+    ),
+    "DEPLOY_REQUEST_INVALID": Remediation(
+        lines=(
+            "This Recipe cannot be sent to Studio in its current form.",
+            "Export the Recipe again with the current harness, then review the new Recipe before "
+            "approving it.",
+        ),
+    ),
+    "DEPLOY_WORKER_POLICY_MISMATCH": Remediation(
+        lines=(
+            "This Recipe would be checked under different rules after it is sent.",
+            "Nothing was approved or activated.",
+            "Export the Recipe again with the current harness. If the fingerprints still differ, "
+            "wait for the hosted service to be updated before trying again.",
+        ),
+    ),
+    # Bringing a released Build back. The whole family paragraph is about packaging one and
+    # sending it, which is the opposite direction, so the failures a person actually meets on the
+    # return trip answer for themselves.
+    "DEPLOY_DATASET_NOT_RELEASED": Remediation(
+        lines=(
+            "The run this deployment started has not released a Build yet.",
+            "Nothing is wrong: hosted work takes as long as it takes, and the rows stay "
+            "unavailable until it has passed its independent check.",
+            "Check where the run is up to, and run this again once it says the dataset is ready.",
+        ),
+    ),
+    "DEPLOY_DATASET_TARGET_OCCUPIED": Remediation(
+        lines=(
+            "Something is already in the folder the released Build has to go into, and it is "
+            "not the Build that was released.",
+            "Nothing was changed there.",
+            "Point this at an empty folder with --into, or move what is in the way first.",
+        ),
+    ),
+    "DEPLOY_DATASET_DOWNLOAD_INTEGRITY": Remediation(
+        lines=(
+            "The rows that came back do not match the fingerprint the release sealed, so none of "
+            "them were kept.",
+            "This is what the check is for; nothing was written and nothing was shown.",
+            "Run this again. If it keeps happening, the copy being served is not the copy that "
+            "was released, and that is worth reporting.",
+        ),
+    ),
+    "DEPLOY_DATASET_ARTIFACT_CONTRACT_INVALID": Remediation(
+        lines=(
+            "What came back does not meet the agreed shape for what it claims to be, so it was "
+            "refused rather than shown.",
+            "Nothing was written here.",
+            "This is a mismatch between what the cloud stored and what this version reads; it "
+            "will not fix itself by retrying, so report it with the run this came from.",
+        ),
+    ),
+    "DEPLOY_DATASET_LOCAL_CHECK_FAILED": Remediation(
+        lines=(
+            "The Build that came back did not pass the same checks a Build made on this machine "
+            "has to pass, so no notebook was written from it.",
+            "The rows are never shown on somebody else's word; they are re-checked here first, "
+            "and this is that check refusing.",
+            "Run this again into an empty folder. If it refuses again, report it with the run "
+            "this came from.",
+        ),
+    ),
+    "DEPLOY_DATASET_NARRATION_CONFLICT": Remediation(
+        lines=(
+            "The workbench window you pointed at is already showing a different piece of work.",
+            "The dataset was not written, so nothing there has changed.",
+            "Leave --research-dir off to write the dataset without telling a window about it, or "
+            "point it at a fresh workbench folder.",
+        ),
+    ),
+    "SIGNED_REPORT_OUTPUT_EXISTS": Remediation(
+        # The strongest claim of the three, and the one furthest from what was checked: a taken
+        # path that has never been opened is not a signed report, and a folder or a socket cannot
+        # be one at all. The claim is kept for the one case the writer confirms.
+        lines=(
+            "{path} already holds a signed report, and reports are never overwritten.",
+            "Choose a name that is not in use.",
+        ),
+        when_not_a_file=_SIGNED_REPORT_OVERWRITE_KIND,
+    ),
+    # The other half of writing a file: the target is free, but the folder above it is absent.
+    # This error names the command that establishes the missing precondition.
+    "OUTPUT_PARENT_ABSENT": Remediation(
+        lines=(
+            "The folder {path} would go into is not there. The line above names it.",
+            "Create it first, with mkdir -p, then run the command again.",
+            # Only the exclusive file writer raises this code; Build output creates missing parents.
+            "Nothing is made for you on the way to a file these commands write, because a typo in "
+            "a path would quietly build a folder tree nobody asked for.",
+        ),
+        # Both raise sites use `lstat`, so a dangling link does not masquerade as an absent parent.
+        kinds_established=(NOTHING_THERE,),
+    ),
+    # The third way a path can be unwritable, and the one nobody expects: a link somewhere above
+    # it. Sealing opens each folder on the way down without following anything, because a link that
+    # is repointed mid-build would move where a sealed Build lands. `/tmp` is such a link on macOS
+    # and is where a first build is most often written, so this one is met early and reads as
+    # arbitrary until the fix is named.
+    "OUTPUT_SYMLINK": Remediation(
+        lines=(
+            "One of the folders on the way to that path is a link, and a build never writes "
+            "through one. The line above names it.",
+            "A link can be repointed while a build is running, which would move where a sealed "
+            "Build lands, so the whole chain is opened without following anything.",
+            "Write to the path the link leads to instead: on this machine /tmp is usually a link "
+            "to /private/tmp, and naming the second one works.",
+        ),
+        # Raised only from inside `if stat.S_ISLNK(...)` in `pipeline._require_output_directory`
+        # and from the same test in `preflight._linked_ancestor`. The link is what the refusal is.
+        kinds_established=(A_LINK,),
+    ),
+    # Input and output roots apply the same no-follow rule to every ancestor.
+    "SOURCE_SYMLINK": Remediation(
+        lines=(
+            # "One of the folders on the way" would be false at the other raise site: the same code
+            # is raised on a *source file* that is a link, where nothing above it is one. A step is
+            # either, which is what both raise sites actually found.
+            "A step on the way to those bytes is a link, and a build never reads through one. The "
+            "line above names it.",
+            "A link can be repointed while a build is running, which would change which bytes a "
+            "sealed Build was made from, so every step down to a source is opened without "
+            "following anything.",
+            "Read from the path the link leads to instead: on this machine /tmp is usually a link "
+            "to /private/tmp, and naming the second one works. A source that is a link has to be "
+            "replaced by the file itself.",
+        ),
+        # Raised only from inside `if stat.S_ISLNK(...)` in `pipeline._require_source_directory`
+        # and `pipeline._require_source_file`, and from the same test in `preflight._first_link_in`.
+        kinds_established=(A_LINK,),
+    ),
+    # This code can describe a pipe, socket, device, or folder link, so it uses a kind-neutral noun.
+    # `pipeline._open_output_parent` raises the same code when the chain could not be opened at
+    # all, where nothing about the kind is known. So the noun comes from the caller that looked,
+    # and a caller that did not look says `something` rather than guessing a file.
+    #
+    # The sentence keeps every word it had except the noun, which is the point: at a plain file --
+    # the one case it was written for and the only one it was ever right about -- it renders exactly
+    # as before, and it is the four other kinds that stop being called a file.
+    "OUTPUT_PARENT_INVALID": Remediation(
+        lines=(
+            "Something on the way to {path} is {kind} rather than a folder. The line above names "
+            "it.",
+            "Choose an output path whose folders are all folders.",
+        ),
+    ),
+    # One errno answers both directions. `EACCES` reaches this map from `init` writing into a folder
+    # it may not write, and equally from `peek` opening a file it may not read and from `list`
+    # walking a folder it may not enter. The boundary cannot tell those apart -- it has an errno and
+    # a path, not an operation -- so the wording does not guess.
+    "PERMISSION_DENIED": Remediation(
+        lines=(
+            "The operating system refused the harness access to {path}, for reading or for "
+            "writing.",
+            "Check what that path allows and who owns it: ls -l on it, and on the folders above "
+            "it.",
+            "A sealed Build folder is read-only on purpose, so an old run cannot be changed or "
+            "cleared by accident. To clear one: chmod -R u+w .work first, then remove it.",
+        ),
+    ),
+    # The two lookup keys for a refusal the operating system raised on a file a command was told to
+    # read. Neither names {path}: the one path a command was pointed at is often not the file that
+    # was missing -- `approve --recipe <missing> --output <new>` fails on the recipe while its
+    # subject path is the output -- and a sentence that names the wrong file is worse than one that
+    # names none. The line above always names the right one.
+    "PATH_ABSENT": Remediation(
+        lines=(
+            # Not "a file this command had to read": the same errno can come from a folder that
+            # vanished under a write. The sentence covers both because the boundary cannot tell
+            # them apart, and the line above names the exact path either way.
+            "Something on that path did not lead to anything. The line above names it.",
+            "Check the spelling, and check you are in the folder you think you are in. Run ls -l "
+            "on it as well: a link that points at a name with nothing at it reads this way too.",
+            "mr-data peek shows what is in a file before you point a command at it.",
+        ),
+    ),
+    "PATH_NOT_A_FILE": Remediation(
+        lines=(
+            "The line above names a path this command had to read as a file, and it is not one.",
+            "A folder, or a name with a file part-way along it, both read this way.",
+            "Point the command at the file itself.",
+        ),
+    ),
+    # These typed path refusals must not fall through to raw numeric error text.
+    "PATH_LINK_LOOP": Remediation(
+        lines=(
+            "The line above names a link that leads back to itself, directly or through a second "
+            "link, so following it never arrives anywhere.",
+            "Check what it points at: ls -l on it, and on anything it names.",
+            "Point the command at the real file, or make the link point at one.",
+        ),
+    ),
+    "PATH_NAME_TOO_LONG": Remediation(
+        lines=(
+            "The line above names a path longer than this machine's filesystem will accept, in "
+            "one part of it or over the whole thing.",
+            "This is a limit of the disk this path is on, not of the harness.",
+            "Use a shorter name, or work from a folder closer to the top.",
+        ),
+    ),
+    # The net under the other five. It says less than they do on purpose: a sentence invented for a
+    # failure nobody has met would be a guess, and a guess in a remediation block is worse than an
+    # honest pointer at the exact wording. The first line is the one that makes the block useful.
+    "SYSTEM_REFUSED": Remediation(
+        lines=(
+            "The operating system stopped this step for a reason the harness has no plain sentence "
+            "for yet. Add --json to the same command to read the exact reason it gave.",
+            "The line above names what it was stopped on, where the system named one.",
+            "A disk that is full, a disk mounted read-only, and too many files open at once all "
+            "read this way; so does a path on a drive that has gone away.",
+        ),
+    ),
+    # The two answers a document read has that the boundary above does not. A folder and a missing
+    # path are answered there, in one place, for every command; these two are what is left over --
+    # something that is not a file and is not a folder either, and a document past the bound.
+    "DOCUMENT_TARGET_NOT_A_FILE": Remediation(
+        lines=(
+            "Something is at the path named above, but it is not a file: it is a pipe, a socket, "
+            "or a device.",
+            "This command reads a whole document and then checks it, and a pipe or a device holds "
+            "nothing until something writes to it, so there is no document there to read.",
+            "Write the document to a file first, and point the command at that file.",
+        ),
+        # `cli._read_json_document` reaches this only after `open_plain_file` refused on `S_ISREG`,
+        # and only after the folder case has been turned into `EISDIR` on the line above it.
+        kinds_established=(A_PIPE, A_SOCKET, A_DEVICE),
+    ),
+    # The third. `os.open` on a link that leads nowhere answers `ENOENT`, which the boundary reads
+    # as "That file or folder is not there" -- said about an entry `ls -l` shows sitting in the
+    # folder, with a fix about spelling. A link is a finding and it names its own fix.
+    "DOCUMENT_TARGET_DANGLING": Remediation(
+        lines=(
+            "A link is at the path named above, and it leads nowhere: the name it points at has "
+            "nothing at it.",
+            "Run ls -l on that path to see where the link points.",
+            "Repoint it at the Recipe, approval, or plan you meant, or point the command at that "
+            "file directly.",
+        ),
+        kinds_established=(A_LINK,),
+    ),
+    "DOCUMENT_TOO_LARGE": Remediation(
+        lines=(
+            "The line above names the file and the size limit it went past.",
+            "A Recipe, an approval, or a plan is a few kilobytes; a file this big is almost "
+            "always the wrong file, or data rather than a Recipe.",
+            "mr-data peek shows what is in a file before you point a command at it.",
+        ),
+    ),
+    # The one Recipe field whose legal values a person cannot guess and the message does not list.
+    # `recipes` answers "open that file and correct that one field", which is right and, for this
+    # field, not enough: the reader has a value they got from somewhere and no way to learn what
+    # was allowed instead. The three closed sets are short, so they are simply named.
+    "RECIPE_OUTPUT_SEMANTICS": Remediation(
+        lines=(
+            "That is not a value this field takes. The line above names the exact field.",
+            "A column type is one of: string, int64, float64, boolean, date, timestamp_utc. What "
+            "the column is for is one of: identifier, entity, category, measure, dimension, "
+            "target, other. A measure has to name a unit other than none.",
+            "mr-data peek reports a column's type in these same words, so a type read out of a "
+            "peek of your source is one this field takes.",
+        ),
+    ),
+    # All version-pin drift shares one product explanation.
+    "RECIPE_EXECUTION": Remediation(lines=_PIN_DRIFT),
+    "RECIPE_RUNTIME": Remediation(lines=_PIN_DRIFT),
+    "RECIPE_VALIDATION": Remediation(lines=_PIN_DRIFT),
+    # An unknown verb gets a task-grouped list, not a dump of every accepted word.
+    "CLI_USAGE": Remediation(
+        lines=(
+            "That is not a command. Run mr-data --help for the full list.",
+            "Look at data: peek, show, list, diff.",
+            "Build: init, plan, plan-check, run, build.",
+            "Recipes: author, approve, recipe-run.",
+            "Check: review --local, verify, preflight, inventory.",
+        ),
+    ),
+    # The other half of a usage failure: the word was a real command, but what followed it was
+    # not what that command takes. A grouped command list would answer a different question.
+    "CLI_ARGUMENTS": Remediation(
+        lines=(
+            "That is a real command, but something it needs is missing or does not belong.",
+            "The line above names the argument. Run the command with --help to see everything it "
+            "takes.",
+        ),
+    ),
+    # Sealing a decision, and signing a report, are done inside a session somebody else starts.
+    # `REVIEW` is the workbench family, whose paragraph is about where a Workbench folder got to --
+    # true of the other `REVIEW_` codes and not of this one, so this one is curated. The command it
+    # names is the reading that needs no session at all, which is what the reader almost always
+    # wanted.
+    "REVIEW_AUTHORITY_ABSENT": Remediation(
+        lines=(
+            "Sealing a review decision, and signing a review report, happen inside a review "
+            "session that the coordinator starts and hands to the command. This command was not "
+            "started from one, so there is no authority to seal or sign with.",
+            "Everything this machine can check on its own is one command away and needs no "
+            "session: mr-data review --local on the Build folder runs the checks and writes "
+            "nothing.",
+            "docs/REVIEW-LOOP.md says who starts the session and what it hands over.",
+        ),
+    ),
+    # Platform refusals identify the diagnostic command that reports available capabilities.
+    "CANDIDATE_PLATFORM_UNSUPPORTED": Remediation(lines=_PLATFORM, command="mr-data preflight"),
+    "SOURCE_PLATFORM_UNSUPPORTED": Remediation(lines=_PLATFORM, command="mr-data preflight"),
+    "WORKSPACE_PLATFORM_UNSUPPORTED": Remediation(lines=_PLATFORM, command="mr-data preflight"),
+    "PLATFORM_VERIFY_UNSUPPORTED": Remediation(
+        lines=(
+            *_PLATFORM,
+            "Re-checking a Build needs them, so this machine cannot re-check one.",
+        ),
+        command="mr-data preflight",
+    ),
+    "PLATFORM_OUTPUT_UNSUPPORTED": Remediation(
+        lines=(
+            *_PLATFORM,
+            "Writing this file needs them, so this machine cannot write it.",
+        ),
+        command="mr-data preflight",
+    ),
+    # peek is the first command anyone runs, so its refusals have to answer rather than just
+    # refuse. None of them uses {path}: peek names what it was pointed at in the line above, and
+    # its argument is not one of the subject paths the command line knows how to fill in.
+    "PEEK_TARGET": Remediation(
+        lines=(
+            "Nothing is at the path named above, so there is nothing to look at.",
+            "Check the spelling, and check you are in the folder you think you are in.",
+        ),
+        # `ux.plain_file` confirms both the failed open and a following `lstat` before declaring
+        # that nothing is present; a dangling link has its own refusal below.
+        kinds_established=(NOTHING_THERE,),
+    ),
+    # The other side of that split. The entry exists, it is a link, and the fix is about the link
+    # rather than about spelling -- which is why it is a separate code and not a fourth sentence
+    # under the one above.
+    "PEEK_TARGET_DANGLING": Remediation(
+        lines=(
+            "A link is at the path named above, and it leads nowhere: the name it points at has "
+            "nothing at it.",
+            "Run ls -l on that path to see where the link points.",
+            "Repoint it at the file you meant, or remove it and peek the file itself.",
+        ),
+        kinds_established=(A_LINK,),
+    ),
+    # A separate code because it is a separate finding, not a second wording of the one above. The
+    # two answers contradict each other -- one says nothing is there, the other says something is
+    # -- and telling somebody who typed the path they meant to check their spelling is advice
+    # aimed at a mistake they did not make. Same shape as OUTPUT_PARENT_ABSENT and
+    # OUTPUT_PARENT_INVALID, which are two codes for the same reason.
+    "PEEK_TARGET_NOT_A_FILE": Remediation(
+        lines=(
+            "Something is at the path named above, but it is not a file: it is a folder, a pipe, "
+            "a socket, or a device.",
+            "A peek reads bytes that are already there, and a pipe or a device has none until "
+            "something writes them, so there is nothing for it to look at.",
+            "Name a file inside the folder, or write the stream to a file first and peek that.",
+        ),
+        # `ux.plain_file.open_plain_file` opens the target and asks the descriptor, and raises
+        # `NOT_PLAIN` only when `S_ISREG` is false. Four kinds are left, and the sentence names
+        # exactly those four: this is elimination on an observation, not a guess about which.
+        kinds_established=(A_FOLDER, A_PIPE, A_SOCKET, A_DEVICE),
+    ),
+    "PEEK_FORMAT": Remediation(
+        lines=(
+            "peek reads csv, json, ndjson, and parquet files. The line above names what it was "
+            "given instead.",
+            "If the file really is one of those under a different name, say which one with "
+            "--format; the bytes are still checked against it.",
+        ),
+    ),
+    # Reached while building from a source, never while looking at one: peek shows these values as
+    # their exact text, because a peek seals nothing. A Build does, so it stops here.
+    "PARSE_VALUE": Remediation(
+        lines=(
+            "One value in that file is not a plain number, string, or true or false. Dates, "
+            "times, decimals, and not-a-number all read this way.",
+            "A Build seals what it reads, and it holds a value exactly or not at all, so it "
+            "stops here rather than rounding it or quietly turning it into text.",
+            "Use mr-data peek to see what is in there -- looking is not sealing, so peek shows "
+            "those values -- then write those columns as text in the source you build from.",
+        ),
+    ),
+    "PEEK_SIZE": Remediation(
+        lines=(
+            "That file is larger than anything this harness opens in one piece.",
+            "Take a smaller extract of it and look at that instead.",
+        ),
+    ),
+    "PEEK_SAMPLE": Remediation(
+        lines=(
+            "The number of rows to show is outside what peek will do.",
+            "Ask for a whole number from 0 to 100. Zero shows the columns and no rows at all.",
+        ),
+    ),
+    # Reading a build back. A folder with nothing in it is by far the commonest way to meet these,
+    # and the reader's own refusal for a missing sealed tree reads like a break-in rather than the
+    # typo it nearly always is.
+    "CANDIDATE_ABSENT": Remediation(
+        lines=(
+            "There is no build at {path}.",
+            "Run mr-data list to see the builds you have, or mr-data build to make one.",
+        ),
+        # Declared rather than inherited from the class rule above, because this is the code the
+        # signpost raises: the folder being there is the ordinary case, not the exception.
+        when_nothing_built_yet=NOTHING_BUILT_YET,
+    ),
+    # A folder that exists but was never set up. Every Workbench command reaches this, and until
+    # the refusal was typed it surfaced as the operating system's own complaint about the control
+    # directory inside the folder -- a name nobody types, carrying no code and no fix.
+    "WORKSPACE_ABSENT": Remediation(
+        lines=(
+            "{path} is not a Workbench folder: nothing has been set up in it.",
+            "mr-data init makes one, at a path that does not exist yet, out of your question, "
+            "requirements, sources, and plan files.",
+            "If you meant a folder you have already built in, mr-data list shows the builds you "
+            "have.",
+        ),
+    ),
+    # A folder a build is holding right now. Curated rather than left to the workbench family,
+    # because that family's answer is "run mr-data status, then mr-data resume" -- and status waits
+    # on the very lock this refusal is about, so the family would name a fix that hangs.
+    "WORKSPACE_BUSY": Remediation(
+        lines=(
+            "A build is running in that folder, and only one command at a time may hold it.",
+            "Wait for it to finish, then run this again.",
+            "mr-data list says which folder is busy and carries on rather than waiting on it.",
+        ),
+    ),
+    "LIST_ROOT_ABSENT": Remediation(
+        lines=(
+            # `is_dir` does not establish absence; it only establishes that listing cannot proceed.
+            "A listing reads a folder, and the line above says what is at the path you named.",
+            "Point mr-data list at a folder that exists, or run mr-data build to make your first "
+            "build.",
+        ),
+    ),
+    "LIST_DEPTH": Remediation(
+        lines=(
+            "How far down to look is outside what list will do.",
+            "Ask for a whole number from 0 to 32. Six is the default, and it reaches a build six "
+            "folders below the one you named.",
+        ),
+    ),
+    # Trying a plan. Both of these are about the throwaway folder the try is built into, and both
+    # are answered the same way: they are about where temporary folders are made on this machine,
+    # which is a setting rather than anything wrong with the plan.
+    "PLAN_CHECK_TEMP_OVERLAP": Remediation(
+        lines=(
+            "A build never reads from the folder it writes into, and the temporary folder this "
+            "machine hands out sits inside the input folder you named.",
+            "Set TMPDIR to a folder outside your input folder and try again.",
+            "Nothing was built, so nothing has to be undone.",
+        ),
+    ),
+    "PLAN_CHECK_TEMP_NOT_PRIVATE": Remediation(
+        lines=(
+            "The temporary folder this machine handed out can be read by other people on it, and a "
+            "whole build was about to be written inside it.",
+            "That usually means TMPDIR points somewhere shared. Set it to a folder only you can "
+            "read and try again.",
+            "Nothing was built, so nothing has to be undone.",
+        ),
+    ),
+    # The four files a job is described in, handed to `init` on the command line. Their prefix sits
+    # in the `workbench` family, which answers "run mr-data status on the folder, then mr-data
+    # resume" -- and after one of these there is no folder to run status on, because `init` refuses
+    # before it makes one. Following that advice earns a second refusal. Same shape of defect as the
+    # sealing family's, at a different family: an answer written about an existing thing, given
+    # about a thing that does not exist.
+    "DEFINITION_INVALID": Remediation(
+        lines=(
+            "One of the files describing this job is not valid JSON. The line above says which "
+            "one, where it is, and where the reading stopped.",
+            "Nothing was created. There is no folder to look at and nothing to carry on from, so "
+            "fix that one file and run the same init again.",
+            "The four are your question, what the answer has to hold, the sources to consider, "
+            "and the plan.",
+        ),
+    ),
+    # The same two words, about the other end of the folder's life. `DEFINITION_INVALID` above is
+    # `init` refusing one of the four files it was handed, before any folder exists. These two are
+    # a folder that already exists whose sealed copies of those files no longer match the record
+    # taken when it was made -- the state, not the input -- and the fix is not the same sentence.
+    "DEFINITIONS_INVALID": Remediation(
+        lines=(
+            "The sealed copies of the four files this job was described in are no longer as they "
+            "were when {path} was made. The line above says which part did not hold.",
+            "Nothing in a Workbench folder is repaired in place, so there is no command that mends "
+            "this one, and every command that opens it -- status and resume included -- will say "
+            "exactly this.",
+            "Make a fresh Workbench folder with mr-data init, at a path that does not exist yet, "
+            "from the same four files. A Build already sealed in this one is untouched: point "
+            "mr-data show at the result folder inside it.",
+        ),
+    ),
+    "DEFINITION_DIGEST_MISMATCH": Remediation(
+        lines=(
+            "One of the four files this job was described in has changed inside {path} since the "
+            "folder was made. The line above names which one.",
+            "Those copies are sealed on purpose: what a build re-runs from has to be what the run "
+            "was recorded against. A folder whose copies moved is not carried on from, and status "
+            "and resume both stop here too.",
+            "Make a fresh Workbench folder with mr-data init, at a path that does not exist yet, "
+            "from the four files as you mean them now. A Build already sealed in this one is "
+            "untouched: point mr-data show at the result folder inside it.",
+        ),
+    ),
+    # `mr-data preflight --workload` reads one document and reports on the job it describes. Its
+    # prefix sits in the `handoff` family, which answers about packaging a Build for Studio -- a
+    # paragraph with nothing true to say about a path that is not a plan. Same shape of defect as
+    # `DEFINITION_INVALID`'s above: an answer written about one thing, given about another.
+    "WORKLOAD_UNREADABLE": Remediation(
+        lines=(
+            "The workload named could not be read. The line above says where it is and what "
+            "stopped the read.",
+            "It has to be a workbench folder, a plan, or a recipe: a plain file this account can "
+            "read, or a folder mr-data init made.",
+            "Nothing was measured, nothing was uploaded, and nothing has to be undone.",
+        ),
+    ),
+    "WORKLOAD_INVALID": Remediation(
+        lines=(
+            "That document was read, and it is not a plan or a recipe this build understands. The "
+            "line above carries the contract's own reason.",
+            "Point --workload at a plan, at a recipe, or at the workbench folder that holds one.",
+            "Nothing was measured, nothing was uploaded, and nothing has to be undone.",
+        ),
+    ),
+    "DEFINITION_UNREADABLE": Remediation(
+        lines=(
+            "One of the files describing this job could not be read. The line above says which one "
+            "and where it is.",
+            "Check it is there, that it is a plain file rather than a folder or a link, and that "
+            "you are allowed to read it.",
+            "Nothing was created, so there is nothing to undo.",
+        ),
+    ),
+    "DEFINITION_TOO_LARGE": Remediation(
+        lines=(
+            "One of the files describing this job is larger than the harness will read. The line "
+            "above says which one and where it is.",
+            "These four are short: a question, what the answer has to hold, the sources to "
+            "consider, and a plan. One that is large is usually the data itself, passed by "
+            "mistake.",
+            "Nothing was created, so there is nothing to undo.",
+        ),
+    ),
+    # The refusal `DEFINITION_UNREADABLE` above has no words for. Its advice -- check it is there,
+    # check it is a plain file rather than a folder, check you may read it -- is all true of a pipe
+    # nobody is writing to, so following it finds nothing wrong and the same command refuses again.
+    # Same sentence as `DOCUMENT_TARGET_NOT_A_FILE`, about the four files `init` is handed rather
+    # than the one document a later command reads.
+    "DEFINITION_TARGET_NOT_A_FILE": Remediation(
+        lines=(
+            "Something is at the path named above, but it is not a file: it is a pipe, a socket, "
+            "or a device.",
+            "Each of the four files describing a job is read whole and then checked, and a pipe or "
+            "a device holds nothing until something writes to it, so there is no description there "
+            "to read.",
+            "Write it to a file first, point mr-data init at that file, and run the same command "
+            "again. Nothing was created, so there is nothing to undo.",
+        ),
+        # The same elimination as `PEEK_TARGET_NOT_A_FILE`, one kind shorter: a folder at one of
+        # these four paths is answered by the command line's own boundary as `EISDIR` before it
+        # reaches here.
+        kinds_established=(A_PIPE, A_SOCKET, A_DEVICE),
+    ),
+    # The same finding at the four files `init` is handed. It reached `DEFINITION_UNREADABLE`,
+    # whose advice is three things to confirm and none of them is the link.
+    "DEFINITION_TARGET_DANGLING": Remediation(
+        lines=(
+            "A link is at the path named above, and it leads nowhere: the name it points at has "
+            "nothing at it.",
+            "Run ls -l on that path to see where the link points.",
+            "Repoint it at the file describing that part of the job, or point mr-data init at "
+            "that file directly. Nothing was created, so there is nothing to undo.",
+        ),
+        kinds_established=(A_LINK,),
+    ),
+    # A dangling authoring link has no readable target, so it needs link-specific advice.
+    "VIEWER_DATASET_SIDECAR_UNAVAILABLE": Remediation(
+        lines=(
+            "The viewer has no table notebook to show for the Build at {path}, so the page keeps "
+            "serving the research notebook and nothing else.",
+            "Either there is none there, or the one there is not the notebook this Build derives. "
+            "The viewer writes one only when there is none and never replaces one, so anything you "
+            "added to a table notebook is still exactly as you left it.",
+            "Make it again from the Build when you want the table notebook on the page. That "
+            "writes the whole notebook, so copy anything you appended to it out first.",
+        ),
+        command="mr-data notebook {path} --json",
+        command_needs_a_build=True,
+        when_nothing_built_yet=(
+            "The viewer is watching {path} for a table notebook, and no build has finished "
+            "there for one to be made from.",
+            "That is the ordinary state before a build completes. The research notebook keeps "
+            "streaming on the page while you wait.",
+            "If a build did complete here, read the receipt it printed: it says whether the "
+            "table notebook was written and where.",
+        ),
+    ),
+    "VIEWER_WATCHER_FAILED": Remediation(
+        lines=(
+            "The viewer stopped watching for notebook changes. The last good notebook is still on "
+            "the page, and nothing new will appear on it.",
+            "Stop this viewer with Ctrl-C and start another one with the same command you started "
+            "this one with, then open the address it prints. The page you have now is stale.",
+            "Nothing on disk was changed by this. The viewer only reads.",
+        ),
+    ),
+    "LOGIN_CONFIG_INVALID": Remediation(
+        lines=(
+            "The address this command was pointed at is not a usable one.",
+            "Check MOSTLYRIGHT_CLOUD_URL: it has to be a plain https address with nothing else "
+            "in it -- no user name, no trailing slash, no fragment.",
+        ),
+    ),
+    "LOGIN_TRANSPORT_FAILED": Remediation(
+        lines=(
+            "The cloud could not be reached, or answered in a way this command does not "
+            "understand.",
+            "Check the network and MOSTLYRIGHT_CLOUD_URL, then run mr-data login again.",
+        ),
+    ),
+    "LOGIN_ACCESS_DENIED": Remediation(
+        lines=(
+            "Sign-in was denied in the browser, so nothing was stored.",
+            "Run mr-data login again if you meant to approve it.",
+        ),
+    ),
+    "LOGIN_EXPIRED": Remediation(
+        lines=(
+            "The sign-in code expired before it was approved, so nothing was stored.",
+            "Run mr-data login again and approve the new code promptly.",
+        ),
+    ),
+    "LOGIN_MINT_FAILED": Remediation(
+        lines=(
+            "Sign-in was approved, but the cloud could not issue a device credential afterwards.",
+            "The approval this ran through is already spent. Run mr-data login again to get a "
+            "new one.",
+        ),
+    ),
+    "LOGIN_CREDENTIALS_EXIST": Remediation(
+        lines=(
+            "A credential is already stored at the path named above, and it was left unchanged.",
+            "Run mr-data whoami to inspect its identity. If you intend to replace it, run "
+            "mr-data login --force.",
+        ),
+    ),
+    "LOGIN_CREDENTIALS_UNREADABLE": Remediation(
+        lines=(
+            "The stored credential at the path named above exists but cannot be read as the file "
+            "the harness writes.",
+            "Inspect that file and its permissions. If it is not a credential you need to keep, "
+            "remove it and run mr-data login to create a new one.",
+        ),
+    ),
+    "AUTHOR_YAML_DANGLING": Remediation(
+        lines=(
+            "A link is at the path named above, and it leads nowhere: the name it points at has "
+            "nothing at it.",
+            "Run ls -l on that path to see where the link points.",
+            "Repoint it at the file you are writing the Recipe in, or remove it and write the "
+            "Recipe at that name.",
+        ),
+        kinds_established=(A_LINK,),
+    ),
+    # The one code whose prefix family answers the wrong question. `DATA_FORMAT` is a field-shape
+    # refusal and belongs with the Recipe fields; this one is a rights refusal wearing the same
+    # prefix, and "open that file and correct that one field" is not what to do about it.
+    "DATA_CLASSIFICATION_REJECTED": Remediation(
+        lines=(
+            "That source was looked at and refused, so nothing may be built from it.",
+            "This is about the terms the source comes with, not about its bytes being broken. The "
+            "message names what was found.",
+            "Either supply the evidence that clears it, or choose a different source.",
+        ),
+    ),
+    # Reading a JSON file. Every command that takes a --recipe, an --approval, a plan, or run
+    # settings goes through the same strict reading, so these are met early and often -- and the
+    # strictness is the part that surprises people, because the file usually opens fine everywhere
+    # else. Each entry says what the rule is as well as what broke it.
+    "JSON_SYNTAX": Remediation(
+        lines=(
+            "That file is not JSON at all. The line above gives the line and column where the "
+            "reading stopped.",
+            "A trailing comma, a missing quote, and a missing closing brace account for nearly "
+            "all of these.",
+            "Fix it there and run the same command again. Nothing was read past that point, so "
+            "nothing has to be undone.",
+        ),
+    ),
+    "JSON_DUPLICATE_KEY": Remediation(
+        lines=(
+            "That file writes the same key twice inside one object, and the harness will not "
+            "choose between them for you.",
+            "Most tools keep the last one silently. Which was meant is a question only you can "
+            "answer, so it is asked rather than guessed.",
+            "Delete the one you did not mean and run the command again.",
+        ),
+    ),
+    "JSON_NONINTEGER_NUMBER": Remediation(
+        lines=(
+            "That file holds a number with a decimal point in it.",
+            "Everything the harness fingerprints has to be written the same way every time, and a "
+            "decimal cannot be, so numbers in these files are whole numbers only.",
+            "Write it as a whole number, or as text when the exact digits matter.",
+        ),
+    ),
+    "JSON_NONFINITE": Remediation(
+        lines=(
+            "That file holds NaN or Infinity. Neither is JSON, and neither has one exact spelling "
+            "to fingerprint.",
+            "Write the value as text, or leave it out and say so with null.",
+        ),
+    ),
+    "JSON_BOM": Remediation(
+        lines=(
+            "That file starts with a byte-order mark -- invisible bytes some editors put at the "
+            "front of a file -- and JSON does not allow one.",
+            "Save it as UTF-8 without a byte-order mark. In most editors that is a separate "
+            "choice sitting next to plain UTF-8.",
+        ),
+    ),
+    "JSON_UTF8": Remediation(
+        lines=(
+            "That file is not UTF-8 text. The line above gives the byte where the reading stopped.",
+            "A file saved as Latin-1 or Windows-1252 reads this way as soon as it holds an "
+            "accented letter. Save it again as UTF-8.",
+        ),
+    ),
+    "JSON_NONCANONICAL": Remediation(
+        lines=(
+            "That file is valid JSON, but it is not written the one exact way the harness "
+            "fingerprints: keys in order, no spare spaces, no line breaks.",
+            "This is only asked of a file the harness wrote itself, so a file that fails here has "
+            "been rewritten since -- usually by an editor that tidied it on save.",
+            "Use the original, or make it again with the command that wrote it.",
+        ),
+    ),
+    # These refusals describe invalid command arguments rather than stored or provider data.
+    "FILL_ENDPOINT": Remediation(
+        lines=(
+            "The address a fill is pointed at has to name one public host, and that one names "
+            "none.",
+            "Give the whole address, scheme and host together, rather than a bare path or a host "
+            "with nothing in front of it.",
+            "It has to be one public metadata address reached over https, and the protocol you "
+            "passed has to be the one it speaks; docs/LOCAL-SEARCH.md lists the three.",
+        ),
+    ),
+    "DATAGOV_SORT": Remediation(
+        lines=(
+            "The order a sweep pages in is part of its cursor contract, and that one is not an "
+            "order this contract can page.",
+            "Data.gov answers an order it does not recognise by quietly sorting by relevance "
+            "instead, so an unrecognised name would page a different catalogue than the receipt "
+            "claims. That is why the name is closed rather than passed through.",
+            "Pass last_harvested_date or relevance. Prefer relevance for a sweep that has to "
+            "converge: last_harvested_date is rewritten every time the provider re-harvests a "
+            "dataset, so a record can move ahead of a cursor that already passed it.",
+        ),
+    ),
+    "DATAGOV_CONFLICT_BOUND": Remediation(
+        lines=(
+            "The number of double-published identifiers a sweep may admit has to be a count, and "
+            "that one is not.",
+            "Pass a whole number that is zero or more. Zero admits none, which is what a sweep "
+            "does when the flag is left off entirely.",
+        ),
+    ),
+    "LOCAL_SEARCH_FILTER_PAIR": Remediation(
+        lines=(
+            "That filter is two halves of one thing, and only one half was given.",
+            "A time filter takes its start and its end; a Recipe filter takes the Recipe's name, "
+            "its version and its fingerprint; an exact-fingerprint filter takes the kind and the "
+            "fingerprint. The line above names which of the three stopped.",
+            "Pass the other half, or leave that whole filter out and search without it.",
+        ),
+    ),
+    # Not a mistake anybody made, and the wording says so. This is the last look a search takes at
+    # its own answer before handing it over: a private score, or a locator that may move, would
+    # leave this machine if it went out. Telling the reader to check what they passed would send
+    # them after a fault that is not theirs.
+    "LOCAL_SEARCH_OUTPUT_BOUNDARY": Remediation(
+        lines=(
+            "The answer this search had built was held back rather than shown: it carried a "
+            "private score or a locator that can move, and neither may leave the machine that "
+            "made it.",
+            "Nothing about your question caused this, and nothing was written. Both stores it "
+            "read are exactly as they were.",
+            "This is a fault in the harness rather than in what you asked for. Quote the code "
+            "above when you report it.",
+        ),
+    ),
+    "NEURAL_MODEL_ROOT_REQUIRED": Remediation(
+        lines=(
+            "This command was asked to work through the search model, and no model folder was "
+            "named.",
+            "Give the folder that was put in place on this machine, by its absolute path.",
+            "Searching by words alone needs no model folder at all, and is what this harness does "
+            "unless it is asked otherwise; docs/LOCAL-SEARCH.md says how the folder is put in "
+            "place when you do want one.",
+        ),
+    ),
+    "NEURAL_MODEL_ROOT_UNEXPECTED": Remediation(
+        lines=(
+            "This command was asked to work by words alone, and a model folder was named as well.",
+            "Nothing would read that folder, so it is refused rather than accepted and quietly "
+            "ignored: an argument that has no effect is worse than one that is turned down.",
+            "Leave the model folder out, or ask for the model to be used.",
+        ),
+    ),
+    "NEURAL_MODEL_ROOT_ABSOLUTE": Remediation(
+        lines=(
+            "The model folder has to be named by its absolute path, and that one is relative.",
+            "What a search is ordered by is pinned to one exact folder, and a relative path names "
+            "a different folder from every different place you run the command.",
+            "Give the path from the top: on this machine it starts with a /.",
+        ),
+    ),
+    "DATAGOV_KEY_FILE": Remediation(
+        lines=(
+            "The key file this fill was pointed at could not be read as a key.",
+            "It has to be a plain file reached without following a link, holding one printable "
+            "line and nothing else: no quotes around it, no name in front of it, and no second "
+            "line.",
+            "Write the key into a file only you can read, and point the command at that file. The "
+            "key itself is never printed, so no message about it will ever quote one back at you.",
+        ),
+    ),
+}
+
+
+# Codes the command-line boundary uses itself, rather than through one of the typed error classes
+# the completeness gate walks for. Two kinds, and they are checked in two different ways because
+# they live in two different places.
+#
+# `CLI_USAGE` and `CLI_ARGUMENTS` are raised in `cli.py`, and are asserted to appear literally
+# there. The rest are lookup keys for a refusal that carries an errno and no typed code: they are
+# never printed as codes, because they are not ones a person could quote back at the source, and
+# they exist so that an untyped refusal a person can hit still gets plain sentences. They are
+# carried on `ux.headline.SYSTEM_REFUSALS` beside the sentence each answers, and
+# `tests/test_ux_remediation.py` asserts this set holds exactly the codes that table names -- an
+# equality between two modules rather than a string search, so a sentence added there with no
+# answer here fails, and an answer here that nothing looks up fails too.
+SYNTHETIC_CODES: frozenset[str] = frozenset(
+    {
+        "CLI_USAGE",
+        "CLI_ARGUMENTS",
+        "PATH_ABSENT",
+        "PATH_LINK_LOOP",
+        "PATH_NAME_TOO_LONG",
+        "PATH_NOT_A_FILE",
+        "PERMISSION_DENIED",
+        "SYSTEM_REFUSED",
+    }
+)
+
+
+# Source areas whose errors no workbench command can put in front of a person. The completeness
+# gate skips a code only when every file that raises it is in here, and a separate test asserts
+# each entry still names a path that exists -- so a deleted module cannot leave a stale excuse
+# behind. Paths are relative to `src/mostlyright/data_harness`.
+NOT_WORKBENCH_REACHABLE: frozenset[str] = frozenset(
+    {
+        # World B. Imported only by `repair/`, which has no command of its own, so nothing here
+        # can reach a person through `mr-data`.
+        "preparation",
+        # World B's fix-it coordinator, and the reason `preparation` above is unreachable. Nothing
+        # imports it: `cli.py` names `ImmutableRepairCoordinator` once, as a string inside the
+        # workflow description `mr-data workflow` prints, which is a label rather than a call. A
+        # fix-it cycle is driven from Studio, so its refusals are read there and never here.
+        "repair",
+        # The clean room's child process. Its stderr is read by the Builder daemon and written to
+        # the daemon's log; a person at a workbench never sees it.
+        "acquisition/sandbox.py",
+        # Graph-kernel errors are converted to BuildError before the command boundary. Registry
+        # errors are converted to ContractError while parsing. Their internal classes never reach
+        # a workbench directly, so the public wrapper codes are the ones curated above.
+        "plan_graph.py",
+        "operation_registry.py",
+        # Local acquisition-bundle errors are caught by deploy.py and converted into one
+        # DeployRefused sentence carrying the original evidence code in brackets. Their internal
+        # class never crosses the command boundary directly.
+        "deployment_evidence.py",
+        # Empirical cadence is a pure cross-system contract foundation. No mr-data command calls
+        # it in this release; Studio persistence and scheduling remain follow-up work. Register
+        # its typed refusals with the command boundary when a command actually consumes them.
+        "sources/cadence.py",
+        # Visual-run storage and query refusals are handled by the local viewer's HTTP envelope;
+        # they are not emitted through the mr-data command error boundary this map governs.
+        "visual_run",
+    }
+)
+
+
+def remediation_for(
+    code: str | None,
+    *,
+    path: str | None = None,
+    path_exists: bool | None = None,
+    build_present: bool | None = None,
+    path_kind: str | None = None,
+) -> tuple[str, ...]:
+    """Plain sentences for one typed code, or an empty tuple when there is nothing honest to say.
+
+    A curated code answers for itself; anything else answers through its prefix family; an
+    unrecognised prefix answers with nothing rather than raising. ``path`` is the subject path the
+    command was given; ``path_exists``, ``build_present`` and ``path_kind`` are what the caller
+    found when it looked -- supplied so an entry can avoid claiming a path is missing when it is
+    not, avoid diagnosing a broken build where nothing has been built, and avoid calling a folder,
+    a pipe or a socket a file. ``path_kind`` is one of the nouns in :mod:`ux.path_kind`, and
+    ``None`` when the caller could not tell.
+    """
+
+    if not code:
+        return ()
+    family_name = family_for(code)
+    entry = CODES.get(code)
+    if entry is not None:
+        source, command = _wording(
+            entry,
+            path_exists=path_exists,
+            build_present=build_present,
+            path_kind=path_kind,
+        )
+        lines = [_fill(line, path, path_kind) for line in source]
+        if command is not None:
+            lines.append(f"Run: {_fill(command, path, path_kind)}")
+        return tuple(lines)
+    # The class rule. An uncurated code answers through its family, and a family written about an
+    # existing Build has nothing true to say about a folder that holds none -- so it does not get
+    # to answer. This sits above the family lookup rather than inside one more curated entry,
+    # because the defect it fixes is the fallthrough itself.
+    if path_exists and build_present is False and family_name in _ABOUT_AN_EXISTING_BUILD:
+        return tuple(_fill(line, path) for line in NOTHING_BUILT_YET)
+    family = FAMILIES.get(family_name)
+    if family is None:
+        return ()
+    return family.lines
+
+
+def _wording(
+    entry: Remediation,
+    *,
+    path_exists: bool | None,
+    build_present: bool | None,
+    path_kind: str | None,
+) -> tuple[tuple[str, ...], str | None]:
+    """Which of one entry's four wordings fits what the caller found on disk, and its command.
+
+    The kind is asked first, and it is the one test written as a refusal rather than as a
+    confirmation: an entry that has written a wording for "not a file" keeps its default only where
+    the caller looked and saw a plain file. Absence of evidence therefore falls to the kind-neutral
+    wording rather than to the file assertion, which is the whole repair -- a wording that asserts a
+    kind is reached only from an observation of that kind.
+
+    The rest is narrowest first. "The folder is there but empty of builds" is a strictly more
+    specific finding than "the folder is there", so it claims the answer before the general
+    path-exists wording gets to diagnose something the caller has no evidence for.
+
+    The command belongs to the wording it was written for, which is why it is returned from here
+    rather than appended afterwards. An alternative wording is chosen precisely because the
+    default's premise does not hold, and the command was written against that premise: `mr-data
+    show` opens a Build, so a path that is taken by something that is not one has nothing for it
+    to open. A block that ends in a command that fails is the defect this map exists to prevent.
+
+    ``command_needs_a_build`` drops Build-only commands unless a Build was observed. The folder
+    check precedes the file check because ``when_not_a_file`` displaces a file assertion, while
+    ``when_not_a_folder`` is selected only after another concrete kind was observed.
+    """
+
+    command = entry.command
+    if entry.command_needs_a_build and build_present is not True:
+        command = None
+    if entry.when_not_a_folder and path_kind not in (None, A_FOLDER):
+        return entry.when_not_a_folder, None
+    if entry.when_not_a_file and path_kind != A_FILE:
+        return entry.when_not_a_file, None
+    if not path_exists:
+        return entry.lines, command
+    if build_present is False and entry.when_nothing_built_yet:
+        return entry.when_nothing_built_yet, None
+    if entry.when_path_exists:
+        return entry.when_path_exists, None
+    return entry.lines, command
+
+
+def _fill(line: str, path: str | None, kind: str | None = None) -> str:
+    return line.replace("{path}", path or _PATH_FALLBACK).replace("{kind}", kind or UNKNOWN_KIND)
+
+
+# Every fact about what is on disk that a wording here can turn on -- read off :func:`_wording`,
+# which is the one function that chooses between wordings, rather than written down beside it.
+#
+# Every observed fact that selects wording is a keyword argument of `_wording`; deriving this set
+# from the signature prevents a second manually maintained list from drifting.
+OBSERVATIONS: frozenset[str] = frozenset(
+    name
+    for name, parameter in inspect.signature(_wording).parameters.items()
+    if parameter.kind is inspect.Parameter.KEYWORD_ONLY
+)