mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/headline.py

@@ -0,0 +1,671 @@
+"""The plain first line: what a person reads instead of the raise-site message.
+
+A typed error is raised deep inside the harness, in the engineering wording the module around it
+uses -- ``candidate run ancestor chain cannot be opened safely``. That wording is right where it is
+written: it is precise, it is the same word the function names use, and it is what an engineer wants
+in a bug report. It is wrong the moment it is the first line a person reads out of a terminal.
+
+The one-direction rule resolves that by translating at the boundary rather than by renaming the
+insides. This module is that translation. It answers one question -- *does this message use an
+internal word?* -- and, when it does, hands back a plain sentence for the same failure instead.
+
+Three things keep the translation honest:
+
+* **Nothing is hidden.** The machine-readable object under ``--json`` still carries the raise-site
+  message verbatim, the typed code is still printed, and the plain block says where the exact
+  wording is. A person who wants the engineering sentence is one flag away from it.
+* **A clean message is left alone.** Most refusals already name a column, a field path, or a check
+  and read perfectly well. Substituting those would lose detail and buy nothing, so a message with
+  no internal word comes through untouched.
+* **The detail survives.** Where a message ends in a name -- a path, a member, a field -- that tail
+  is carried onto the plain sentence, because *which* file changed is the actionable half.
+
+The term list here is the same list ``scripts/vocabulary_sweep.py`` reads out of
+``scripts/vocabulary-sweep.d/_terms.json``; ``tests/test_ux_headline.py`` asserts the two are equal,
+so the boundary enforces exactly the words the gate bans and no others.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import re
+from typing import NamedTuple
+
+from mostlyright.data_harness.canonical import CanonicalJSONError
+from mostlyright.data_harness.ux.path_kind import A_FOLDER, A_LINK
+from mostlyright.data_harness.ux.remediation import COMPOUND_PREFIX_FAMILY, PREFIX_FAMILY
+
+# --------------------------------------------------------------------------------------------
+# The banned words
+# --------------------------------------------------------------------------------------------
+#
+# Written one word per literal rather than as phrases. Every literal below has no whitespace in it,
+# which is exactly the shape the vocabulary sweep treats as a name rather than as wording -- so the
+# list that enforces the rule is not itself reported as a breach of it. That is a consequence of the
+# sweep's stated rule, not an exclusion argued for this file.
+
+INTERNAL_TERMS: tuple[tuple[str, ...], ...] = (
+    ("candidate",),
+    ("sealed", "candidate"),
+    ("frozen", "recipe"),
+    ("crawler",),
+    ("trusted", "retriever"),
+    ("sandbox",),
+    ("normalizer",),
+    ("normalizer", "child"),
+    ("format", "family"),
+    ("parser",),
+    ("reader", "registry"),
+    ("promotion", "gate"),
+    ("golden", "fixture"),
+    ("decode", "fingerprint"),
+    ("acquisition", "receipt"),
+    ("producer",),
+    ("verifier",),
+    ("byte-range", "acquisition"),
+    ("strict", "206"),
+    ("Content-Range", "validation"),
+    ("watermark",),
+    ("cycle", "cursor"),
+    ("two-phase", "cycle", "pinning"),
+    ("immutable", "version", "store"),
+    ("latest", "pointer"),
+    ("drift", "finding"),
+    ("repair", "task"),
+    ("workspace", "plan"),
+)
+
+
+def _compile(words: tuple[str, ...]) -> re.Pattern[str]:
+    """Word-boundary anchored, case-insensitive, tolerant of a trailing plural.
+
+    The same construction ``scripts/vocabulary_sweep.py`` uses, so a word the gate would report on
+    a page is the same word this boundary refuses to print.
+    """
+
+    body = r"\s+".join(re.escape(word) for word in words)
+    return re.compile(rf"\b{body}s?\b", re.IGNORECASE)
+
+
+_PATTERNS: tuple[re.Pattern[str], ...] = tuple(_compile(words) for words in INTERNAL_TERMS)
+
+# Characters that cannot appear in an ordinary English word. A token carrying one is a name -- a
+# path, a flag, a field path, a placeholder -- and a name is never wording, so `candidate` inside
+# `.work/run/candidate/manifest.json` is not a word anyone chose to write in a sentence.
+_NAME_CHARACTERS = frozenset("\\_=$[]{}<>|@")
+_DOTTED_NAME = re.compile(r"[A-Za-z0-9]\.[A-Za-z0-9]")
+# A slash on its own is not enough. `candidate/run child namespace` and `assignment/candidate` are
+# two words with a slash between them -- wording, and exactly the wording this boundary exists to
+# replace. A slash means "path" only when the token also looks like one: rooted, or carrying a
+# suffix or another name character.
+_ROOTED_PATH = re.compile(r"^(?:[.~]{0,2}/|[A-Za-z]:[\\/])")
+
+# What a removed name is replaced with before matching. It has to be something no term pattern can
+# join across, or blanking `sealed <name> candidate` would manufacture the phrase `sealed candidate`
+# that nobody wrote.
+_NAME_PLACEHOLDER = "..."
+
+
+def _is_name(token: str) -> bool:
+    """Whether one whitespace-delimited token is a name rather than a word."""
+
+    if _NAME_CHARACTERS & set(token) or _DOTTED_NAME.search(token) is not None:
+        return True
+    return "/" in token and _ROOTED_PATH.match(token) is not None
+
+
+def carries_internal_wording(text: str) -> bool:
+    """Whether the prose in ``text`` uses one of the internal words, ignoring names inside it."""
+
+    prose = " ".join(_NAME_PLACEHOLDER if _is_name(token) else token for token in text.split())
+    return any(pattern.search(prose) for pattern in _PATTERNS)
+
+
+# --------------------------------------------------------------------------------------------
+# The plain sentences
+# --------------------------------------------------------------------------------------------
+#
+# Every entry is a sentence body with no closing full stop, because the renderer adds one when the
+# failure had no detail to name and a colon when it did. Written for the reader of a terminal: what
+# stopped, in the words the rest of the product uses.
+
+_LAST_RESORT = "That command stopped before it finished"
+
+# One per family in `remediation.FAMILIES`. The safety net: a code nobody has curated still reads
+# plainly, because its prefix has a family and every family has a sentence.
+FAMILY_HEADLINES: dict[str, str] = {
+    "ingestion": "A resumable source copy could not safely advance",
+    "hosted lane": (
+        "That work on the Mostly Right backend could not be started, watched, or fetched"
+    ),
+    "sources": "A source this Recipe names could not be used",
+    "rights": "That source may not be used on these terms",
+    "connectors": "The connector that reaches that source could not be used",
+    "cadence": "The record of how often that source publishes could not be added to",
+    "capture": "A recording of a live source could not be sealed or read back",
+    "reading": "That file could not be opened",
+    "cleaning": "A cleaning step could not be carried out",
+    "joins": "The join between two sources did not hold",
+    "quality": "A check this Build has to pass did not pass",
+    "recipes": "A Recipe, its approval, or its run settings is not valid",
+    "json": "That file is not JSON the harness can read",
+    "authoring": "That YAML file could not be read as a Recipe",
+    "workbench": "This Workbench folder is not in a state this command can use",
+    "workbench record": "The sealed control tree of this Workbench folder could not be read",
+    "review": "The sealed review of this Build could not be made or read",
+    "output": "That path could not be written to",
+    "sealing": "The sealed Build could not be read or written safely",
+    "network": "Fetching those bytes did not succeed",
+    "platform": "This machine is missing filesystem features this step needs",
+    "handoff": "Packaging this Build for Studio, or reading a job back, did not succeed",
+    "hosted authoring": "One hosted recipe proposal could not be authored from its bundle",
+    "hosted resources": "This hosted worker does not have enough bounded memory for graph work",
+    "dataset handoff": "Bringing the released Build back here did not finish",
+    "source catalog": "That entry in the Source Catalog could not be written",
+    "catalog fill": "Filling the Source Catalog from that provider did not succeed",
+    "catalog authoring": "The entries of that public catalog could not be written",
+    "catalog generation": "That generation of the public catalog could not be published",
+    "catalog update": "That published catalog release could not be installed on this computer",
+    "local search": "That search over what is already on this machine could not be answered",
+    "search model": "The search model on this machine could not be used",
+    "login": "The credential on this machine could not be used",
+    "viewer": "The local notebook viewer could not be started or used",
+}
+
+# One per code whose raise sites use an internal word today. Ordered by prefix, and within a prefix
+# by the code itself, so the list reads as a table rather than as a history.
+HEADLINES: dict[str, str] = {
+    "GRAPH_PACKAGE_UNSUPPORTED": "This graph Recipe cannot use packaged inputs yet",
+    # Opening a Build folder and everything under it.
+    # Neither headline says "folder" because it is printed unchanged with no path observation,
+    # and both codes are reached
+    # at paths that are not folders: `CANDIDATE_ABSENT` where nothing is at the path at all, and
+    # `CANDIDATE_ANCESTOR_INVALID` on the `ENOTDIR` that a plain file, a pipe, a bound socket and a
+    # character device all give. "There is no Build in that folder" and "The Build folder could not
+    # be opened" were the first line a person read in every one of those cases.
+    "CANDIDATE_ABSENT": "Nothing here can be read as a Build",
+    "CANDIDATE_ANCESTOR_INVALID": "The Build could not be opened",
+    "CANDIDATE_ANCESTOR_RACE": "The folders leading to the Build changed while they were "
+    "being opened",
+    "CANDIDATE_ANCESTOR_SYMLINK": "A folder on the way to the Build is a link",
+    "CANDIDATE_CONSTRUCTION_INVALID": "The Build could not be written out safely",
+    "CANDIDATE_CONSTRUCTION_UNSUPPORTED": "This machine cannot write a Build safely",
+    "CANDIDATE_DIGEST_MISMATCH": "The Build fingerprint does not match",
+    "CANDIDATE_ENVELOPE_INVALID": "The packaged Build is not valid",
+    "CANDIDATE_HASH_MISMATCH": "A file inside the Build changed",
+    "CANDIDATE_INPUT_REQUIRED": "This job has nothing to build from",
+    "CANDIDATE_INSTALL_INVALID": "The Build that was put in place is not the one that was made",
+    "CANDIDATE_INVALID": "This Build is missing something it has to have",
+    "CANDIDATE_LIMIT_INVALID": "A size limit this Build is held to is not one the harness can use",
+    "PROFILE_INVALID": "The Build's column summary could not be made into the service's own",
+    "CANDIDATE_MEMBER_INVALID": "A file inside the Build could not be read safely",
+    "CANDIDATE_MEMBER_MISMATCH": "The files in the Build are not the files its Receipt lists",
+    "CANDIDATE_MISSING": "The record points at a Build that is not there",
+    "CANDIDATE_NAMESPACE_RACE": "The Build folder changed while it was being checked",
+    "CANDIDATE_NOT_COMMITTED": "This Workbench folder has no finished Build yet",
+    "CANDIDATE_PLATFORM_UNSUPPORTED": "This machine is missing filesystem features this step needs",
+    "CANDIDATE_PRODUCER_MISMATCH": "The Build already there was not made by this job",
+    "CANDIDATE_RACE": "The Build changed while it was being read",
+    "CANDIDATE_REPLAY_MISMATCH": "Replaying the Build did not reproduce its files",
+    "CANDIDATE_SCOPE_MISMATCH": "That Build does not belong to the job that asked for it",
+    "CANDIDATE_SNAPSHOT_INVALID": "The Build moved while it was being read",
+    "CANDIDATE_STATE_MISMATCH": "The Build does not match this Workbench folder's record",
+    "CANDIDATE_TOO_LARGE": "This Build is larger than the harness will handle",
+    # The Courier, and what it brought back.
+    "CRAWLER_ADAPTER_UNAVAILABLE": "The Courier has no approved way to reach that source",
+    "CRAWLER_DOWNLOAD_FAILED": "The Courier could not fetch those bytes",
+    "CRAWLER_DOWNLOAD_INVALID": "What the Courier fetched is not what was asked for",
+    "CRAWLER_ENVIRONMENT_FORBIDDEN": "The Courier was handed a setting it is not allowed to carry",
+    "CRAWLER_NORMALIZATION_INPUT_INVALID": "What the Courier brought back could not be turned "
+    "into exact bytes",
+    "CRAWLER_POLICY_MISMATCH": "The rules the Courier was given for what it may fetch are not "
+    "the ones in force",
+    "CRAWLER_POLICY_REQUIRED": "The rules for what the Courier may fetch are not available",
+    "CRAWLER_POLL_TIMEOUT": "The Courier did not answer in time",
+    "CRAWLER_PROTOCOL_BINDING": "The Courier's answer is not tied to the request that was sent",
+    "CRAWLER_PROTOCOL_FAILURE": "The Courier returned a failure this harness cannot safely carry",
+    "CRAWLER_PROTOCOL_LIMIT": "That message to or from the Courier is larger than the harness "
+    "will carry",
+    "CRAWLER_PROTOCOL_SCHEMA": "The Courier's failure message uses a version this harness does "
+    "not know",
+    "ACQUIRE_HOSTED_COLLECTION_UNSUPPORTED": "This bounded collection needs the local attested "
+    "clean room",
+    "HOSTED_COLLECTION_UNSUPPORTED": "This bounded collection needs the local attested clean room",
+    "CRAWLER_PROTOCOL_TYPE": "The Courier's answer is not the shape an answer has to be",
+    "CRAWLER_PROTOCOL_VERSION": "The Courier is speaking a version this harness does not know",
+    "CRAWLER_REMOTE_FAILED": "The Courier reported a failure",
+    "CRAWLER_REMOTE_REQUIRED": "This fetch has to go through the Courier",
+    "CRAWLER_RESULT_INVALID": "The Courier's answer is not valid",
+    "CRAWLER_QUERY_INVALID": "The Courier was given a source request it cannot safely run",
+    "CRAWLER_SESSION_INVALID": "The Courier's session is not valid",
+    "CRAWLER_SESSION_SCOPE_MISMATCH": "The Courier's session belongs to a different job",
+    "SOURCE_CADENCE_CONTEXT_INVALID": "The source update evidence does not match this job",
+    "SOURCE_ADAPTER_UNREGISTERED": "No approved hosted adapter can refresh that source",
+    "CRAWLER_SOURCE_SCOPE_MISMATCH": "The Courier fetched a source this job did not name",
+    # Reading a source's bytes for one question in a research session.
+    "PROBE_SOURCE_ACQUISITION_MISBOUND": "The fetched source does not belong to the question that "
+    "asked for it",
+    "PROBE_SOURCE_RESULT_INVALID": "What came back for that source does not match what was fetched",
+    # Packaging for Studio, and the jobs it hands back.
+    "DEPLOY_REQUEST_INVALID": "This Recipe cannot be sent to Studio in its current form",
+    "DEPLOY_WORKER_POLICY_MISMATCH": "This Recipe would be checked under different rules after "
+    "it is sent",
+    "ARTIFACT_DOWNLOAD_BUDGET_EXCEEDED": "That download is larger than this job allows",
+    "ARTIFACT_SCOPE_MISMATCH": "That file belongs to a different job",
+    "ARTIFACT_SPLIT_VIEW": "That file read back differently the second time",
+    "BOOTSTRAP_CONFIG_INVALID": "The start-up settings are not valid",
+    "JOB_INVALID": "The job description is not valid",
+    "MANIFEST_INVALID": "The Receipt is not valid",
+    "PLAN_SCOPE_MISMATCH": "That plan belongs to a different job",
+    "PREDECESSOR_SCOPE_MISMATCH": "The Build this one follows belongs to a different job",
+    "PRODUCER_MISMATCH": "The Builder that ran is not the Builder this job enrolled",
+    "SESSION_LEASE_EXPIRY_UNREASONABLE": "This session has more time than this worker may "
+    "safely use",
+    "SIGNED_SESSION_SCOPE_MISMATCH": "That signed session belongs to a different job",
+    "SIGNING_KEY_STALE": "That signing key is no longer the enrolled one",
+    "VERIFIER_SCOPE_INVALID": "The Checker's assignment is not valid",
+    "VERIFIER_SCOPE_STALE": "The Checker's assignment is out of date",
+    # Reaching a source through its connector, and what the Clean room hands back.
+    "ACQUIRED_SNAPSHOT": "The saved copy of that source does not match its Receipt",
+    "ACQUISITION_SNAPSHOT": "The saved copy of that source could not be read safely",
+    "AUTHENTICATED_SOURCE_REQUIRES_TRUSTED_GATEWAY": "That source needs a sign-in, and the "
+    "Courier is never given one",
+    "REJECTED_NOT_RECEIPT": "Content that was refused cannot be given a Receipt saying it was "
+    "admitted",
+    "SANDBOX_ATTESTATION_MISMATCH": "The Clean room ran under different rules from the ones "
+    "pinned for this job",
+    "SANDBOX_ATTESTATION_REQUIRED": "This fetch needs the Clean room rules pinned for this job, "
+    "and none were given",
+    "SANDBOX_RESULT": "What came out of the Clean room is not tied to the exact bytes it was given",
+    "SNAPSHOT_CONTENT": "The saved copy of that source does not match its Receipt",
+    "STREAM_CONTENT_BINDING": "What came out of the Clean room is not tied to the exact stream "
+    "bytes",
+    "STREAM_QUERY_BINDING": "What came back from that stream does not match what was asked for",
+    "STREAM_STATE": "The record of where that stream had got to is not valid",
+    "STREAM_STATE_LIMIT": "The record of what that stream has already been shown is larger than "
+    "the harness will hold",
+    # Opening the bytes of a source file.
+    "PARSE_EXTERNAL_REFERENCE": "That file points at something outside itself, and the Reader "
+    "will not follow it",
+    "PARSE_INPUT": "The Reader was not given exact bytes to read",
+    "PARSE_INPUT_LIMIT": "That file is empty, or larger than the Reader will open",
+    "PARSE_MEDIA_MISMATCH": "The declared file type does not match the Reader that was chosen",
+    "PARSE_SUFFIX_MISMATCH": "The filename ending does not match the Reader that was chosen",
+    "READER_CONTRACT": "That file does not meet the Reader's required shape",
+    "READER_OPTIONS": "Those Reader settings are not valid for this file",
+    # A Recipe, its pinned inputs, and the evidence a run leaves behind.
+    "CONTEXT_REQUIRED": "This Recipe run is missing part of the package it has to be given",
+    "TABLE_PREVIEW_INVALID": "The preview of this table is not valid",
+    "ENGINE_NOT_ALLOWLISTED": "That engine is not one this harness will build with",
+    "ENGINE_RUNTIME_MISMATCH": "The engine that ran is not the engine recorded",
+    "RECIPE_CANDIDATE": "That Receipt was not written by a Recipe run",
+    "RECIPE_MATERIALIZATION": "What was written out does not match the Recipe",
+    "RECIPE_PREDECESSOR": "This run does not follow on from the last good one",
+    "RECIPE_TEMPLATE": "This Recipe does not match the approved template",
+    "RECIPE_RECEIPT_FIELDS": "That Receipt names a version it does not have the fields for",
+    "RECIPE_RESULT_MISMATCH": "The sealed Recipe evidence does not match what was built",
+    "RECIPE_SOURCE_CLASSIFICATION": "A source's exact bytes were refused by this Recipe's rules",
+    "RECIPE_SOURCE_STATE_INVALID": "The record of which sources were used is not exact",
+    "RECIPE_SOURCE_STATE_MISMATCH": "The sources used do not match the ones replayed independently",
+    "RECIPE_WATERMARK": "The Bookmark for a source is not where this run needs it to be",
+    "RECOMMENDATION_PARTITION": "The suggested source list is not split into valid groups",
+    "REQUIREMENT_BINDING": "The suggested sources do not match this question's requirements",
+    "UNSUPPORTED": "This question was answered as one the harness cannot support, so nothing "
+    "can be built from it",
+    "URL_HOST": "That source address does not name a valid host",
+    # The sealed review of a Build: who was enrolled to review it, what they signed, and what was
+    # sealed from it. Only the refusals whose own wording uses an internal word are here; the rest
+    # of `review.py` reads plainly already and comes through untouched.
+    "ASSIGNMENT_ATTEMPTS_NOT_DISTINCT": "One attempt at this job is enrolled in two roles of its "
+    "review",
+    "ASSIGNMENT_CANDIDATE_MISMATCH": "This review was assigned for a different Build",
+    "ASSIGNMENT_CYCLE_COUNT_INVALID": "This review assignment records a repair round, and this "
+    "version reviews first builds only",
+    "ASSIGNMENT_KEYS_NOT_DISTINCT": "The reviewers and the Checker have to sign with different "
+    "keys",
+    "ASSIGNMENT_PRINCIPALS_NOT_DISTINCT": "One person cannot hold two roles in one review",
+    "ASSIGNMENT_PRODUCER_ATTEMPT_MISMATCH": "This review was assigned for a different build "
+    "attempt",
+    "ASSIGNMENT_PRODUCER_MISMATCH": "This review was assigned for a build by somebody else",
+    "ASSIGNMENT_VERIFIER_KEY_MISMATCH": "That is not the signing key this review enrolled for the "
+    "Checker",
+    "ASSIGNMENT_VERIFIER_NOT_ENROLLED": "The Checker is not the one this review enrolled",
+    "DECISION_SNAPSHOT_MISSING": "The Build was not held still while it was checked",
+    "REPORT_CYCLE_COUNT_INVALID": "That review report records a repair round, and this version "
+    "reviews first builds only",
+    "REPORT_FIELD_MISMATCH": "That review report is about a different Build or a different "
+    "assignment",
+    # The Workbench folder's own durable record.
+    "RESUME_NOT_STARTED": "This Workbench folder has not been run yet, so there is nothing to "
+    "pick up",
+    "REVIEW_CANDIDATE_MISMATCH": "The review points at a different Build",
+    "RUN_STATE_INVALID": "This Workbench folder's record is not valid",
+    # Searching the Source Catalog and the private index over the Builds on this machine, and the
+    # record each search keeps of what it looked at. Only the refusals whose own wording uses an
+    # internal word are here; the rest of that area reads plainly and comes through untouched.
+    "CATALOG_TRACE_CANDIDATES": "The record of what this search looked at is not exact",
+    "CATALOG_TRACE_PARTITION": "The groups this search sorted its results into are not the "
+    "results it had",
+    "LOCAL_SEARCH_SERVICE_BINDING": "The Build this search chose is not the one that was "
+    "re-checked",
+    "LOCAL_SEARCH_TRACE_BINDING": "The record of this search does not match the Builds it read",
+    "NEURAL_PIN_MISMATCH": "The search model on this machine is not the one it is pinned to",
+    # Filling the Source Catalog and writing its entries. Both of these say "the payload", "the
+    # facts and citation" or "the parser" in their own wording, which is a sentence written for
+    # somebody reading the code rather than for somebody who ran a command.
+    "CATALOG_DELTA_RECORD_BINDING": "That catalog entry says something the provider's record does "
+    "not",
+    "HARVEST_XML_ENCODING": "That provider's answer is not written in the text encoding it says "
+    "it is",
+}
+
+# For the refusals raised without a typed code at all, keyed by the class that carries them.
+# `naming` resolves a class through its hierarchy, so a subclass answers through its parent's
+# sentence unless it is written here itself.
+EXCEPTION_HEADLINES: dict[str, str] = {
+    "ReviewError": "This review was not accepted",
+    "SignerProviderError": "That signing key could not be used",
+    # An `OSError` the harness raised itself, rather than one the operating system handed it. The
+    # ones the system raises say things like "No such file or directory" and are already plain, so
+    # they never reach this map; the ones written here are safety refusals from putting a Build in
+    # place or starting a Clean room, and they read like the inside of the machine.
+    "OSError": "This step could not be completed safely on this machine",
+}
+
+
+class SystemRefusal(NamedTuple):
+    """What a person reads for one errno, and the key its remediation is written under.
+
+    One record rather than two tables. The sentence lived here and the remediation key lived in
+    `cli.py`, in a second `if` chain over the same errnos, and nothing held the two together: an
+    errno with a sentence and no key printed advice-free, an errno with a key and no sentence
+    printed as a number. They are the same decision and they are made once.
+
+    ``observed`` is what the errno itself establishes, in the nouns :mod:`ux.path_kind` publishes,
+    and ``None`` where it establishes nothing. It is declared here rather than borrowed from
+    ``code`` because one code serves two errnos that found different things: ``EISDIR`` is the
+    kernel saying it is a directory, ``ENOTDIR`` is the kernel saying only that a component is not
+    one, and both answer through ``PATH_NOT_A_FILE``. ``scripts/path_kind_gate.py`` reads this
+    field and refuses a headline that names any other kind.
+    """
+
+    headline: str
+    code: str
+    observed: str | None = None
+
+
+# Refusals a filesystem step was stopped by, keyed by errno. An errno message is English already --
+# that is why it never reaches the term map above -- but `str(OSError)` is not that message: it is
+# `[Errno 62] Too many levels of symbolic links: '/some/path'`, which opens with a number in
+# brackets and quotes the path like a value in a log. `OSError.filename` carries that path as a
+# value, so the line a person reads can be a sentence with the path at the end of it.
+#
+# Every entry is one a workbench command can surface, including self-referential links and names
+# longer than the filesystem accepts.
+SYSTEM_REFUSALS: dict[int, SystemRefusal] = {
+    errno.EACCES: SystemRefusal("This machine did not allow that", "PERMISSION_DENIED"),
+    # `EISDIR` is the kernel saying the target is a directory, so the noun is the refusal itself.
+    errno.EISDIR: SystemRefusal(
+        "That path is a folder, and this command needs a file", "PATH_NOT_A_FILE", observed=A_FOLDER
+    ),
+    # `ELOOP` is the kernel saying it followed links until it gave up, so the noun is the refusal.
+    errno.ELOOP: SystemRefusal(
+        "That path is a link that leads back to itself", "PATH_LINK_LOOP", observed=A_LINK
+    ),
+    errno.ENAMETOOLONG: SystemRefusal(
+        "That name is longer than this machine allows", "PATH_NAME_TOO_LONG"
+    ),
+    # `ENOENT` does not establish that a file or folder is absent: the kernel says the *name did not
+    # resolve*, and a link that leads nowhere is a name that does not resolve while the entry it
+    # names sits right there in `ls -l`. So the sentence says what the errno knows -- the path led
+    # nowhere -- and the three commands whose own reads meet a link now type their own code before
+    # they ever reach here.
+    errno.ENOENT: SystemRefusal("That path did not lead to anything", "PATH_ABSENT"),
+    # `ENOTDIR` establishes only that a component used as a directory is not one; the kernel says
+    # a component was used as a
+    # directory and is not one, and a pipe, a socket and a device all return it. The sentence
+    # reaches `show`, `diff`, `peek`, `author` and `recipe-validate`, so `--output /dev/null/x`
+    # and every read through a device called that device a file. It now says what the errno says
+    # and nothing more, and `observed` is `None` because nothing was observed.
+    errno.ENOTDIR: SystemRefusal("A step of that path is not a folder", "PATH_NOT_A_FILE"),
+    errno.EPERM: SystemRefusal("This machine did not allow that", "PERMISSION_DENIED"),
+}
+
+# The safety net, and the reason the table above no longer has to be complete to be safe. It used
+# to say that only errnos a command can put in front of someone were listed and that anything else
+# "keeps the operating system's own wording" -- a premise about reachability that was asserted
+# rather than measured, and false both ways round: `ELOOP` and `ENAMETOOLONG` are two commands and
+# one typed path away, and what an unlisted errno kept was not the system's wording but Python's
+# assembly of it, opening with a bracketed number.
+#
+# So an errno with no entry now reads as plainly as one with an entry, and says less rather than
+# saying it in engineering. The exact sentence is one `--json` away, which is the same trade every
+# other translation in this module makes. `FAMILY_HEADLINES` is the same net one layer up: a code
+# nobody has curated still reads plainly because its prefix has a family.
+ANY_SYSTEM_REFUSAL = SystemRefusal("This machine refused that", "SYSTEM_REFUSED")
+
+
+# The strict-JSON refusals are the one class whose first line is unreadable for a reason that has
+# nothing to do with internal words. A `CanonicalJSONError` assembles itself as
+# `<pointer>: <detail> [<code>]`, and the pointer for a whole document is `$` -- so the first thing
+# a person reads out of a terminal is a dollar sign and a colon, which is a shell prompt, not a
+# sentence. The three facts the error carries are right; only the assembly is wrong, so these are
+# rebuilt from those facts rather than substituted for.
+_JSON_SUBJECT = "That file is not JSON the harness can read"
+
+# The JSON pointer for the whole document. Any other pointer names a place inside the file, and that
+# is the half of the message worth keeping.
+_WHOLE_DOCUMENT = "$"
+
+
+def json_headline(error: BaseException) -> str | None:
+    """The plain first line for a strict-JSON refusal, or ``None`` when it is not one.
+
+    ``None`` for everything else, so the caller can fall through to the other translations. The
+    exact assembled string is untouched on the machine-readable object, exactly as it is for every
+    other rewriting at this boundary.
+    """
+
+    if not isinstance(error, CanonicalJSONError):
+        return None
+    pointer = error.path
+    if pointer and pointer != _WHOLE_DOCUMENT:
+        return f"{_JSON_SUBJECT}: {error.detail}, at {pointer}."
+    return f"{_JSON_SUBJECT}: {error.detail}."
+
+
+def refused_path(error: BaseException | None) -> str | None:
+    """The path an ``OSError`` names, when it names one that can be printed as a path.
+
+    ``filename`` is ``None`` for a refusal raised on a descriptor and may be an ``int`` file
+    descriptor or ``bytes``; neither is a path a person can act on, so both are declined rather
+    than rendered. One rule, used by the sentence below and by the command line when it decides
+    which path a refusal is about, because two answers to "which path is this" is how a block came
+    to name one file and its advice another.
+    """
+
+    if not isinstance(error, OSError):
+        return None
+    named = error.filename
+    if isinstance(named, str):
+        return named
+    if isinstance(named, os.PathLike):
+        return str(named)
+    return None
+
+
+def system_refusal(error: BaseException) -> SystemRefusal | None:
+    """What to say and where its fix is written, for a refusal carrying an errno.
+
+    ``None`` for anything with no errno, which is every `OSError` the harness assembles out of its
+    own wording without one. It is **not** ``None`` for the few the harness constructs *with* an
+    errno -- ``review.py`` and ``pipeline.py`` raise a handful for install-time safety -- and this
+    function cannot tell those from the system's own. It therefore treats this table as a
+    best-effort translation for both sources.
+    """
+
+    if not isinstance(error, OSError) or error.errno is None:
+        return None
+    return SYSTEM_REFUSALS.get(error.errno, ANY_SYSTEM_REFUSAL)
+
+
+def system_headline(error: BaseException) -> str | None:
+    """The plain first line for a refusal carrying an errno, or ``None``.
+
+    Total over the errnos: every one gets a sentence, a curated one where there is one and the net
+    otherwise, so no line a person reads is ever a bracketed error number.
+    """
+
+    refusal = system_refusal(error)
+    if refusal is None:
+        return None
+    named = refused_path(error)
+    return f"{refusal.headline}: {named}" if named else f"{refusal.headline}."
+
+
+def system_lookup_code(error: BaseException) -> str | None:
+    """The remediation key for a refusal that carries no typed code of its own.
+
+    Never printed as a code and never reaches the machine-readable object, because nothing raises
+    it: it exists so an untyped refusal a person can hit still gets plain sentences. It comes off
+    the same record as the sentence above, so a refusal that reads plainly always has a fix under
+    it and neither half can be added without the other.
+    """
+
+    refusal = system_refusal(error)
+    return None if refusal is None else refusal.code
+
+
+# What the plain block says about the sentence it replaced, so nothing looks hidden.
+EXACT_WORDING_HINT = "Exact wording: add --json to the same command."
+
+# What separates "what went wrong" from "which thing it was about". A colon followed by a space, so
+# a clock time or a Windows drive letter inside a path is never mistaken for that break.
+_SEPARATOR = re.compile(r":\s")
+
+# The typed classes that append their own code assemble as `<subject>: <detail> [CODE]`. The plain
+# block already prints the code on a line of its own, so carrying it inside the sentence as well is
+# a duplicate -- and it is a duplicate spelled out of exactly the engineering vocabulary the
+# sentence is being translated out of, so it can put an internal word back on a line the boundary
+# just cleaned.
+_TRAILING_CODE = re.compile(r"\s*\[[A-Z0-9_]+\]\s*$")
+
+
+def without_repeated_code(message: str, code: str | None) -> str:
+    """``message`` with its trailing ``[CODE]`` dropped when the block prints that code anyway.
+
+    Several typed classes assemble themselves as ``<subject>: <detail> [CODE]``. The plain block
+    prints ``Code: <CODE>`` on a line of its own two lines below, so the bracketed copy is the same
+    fact twice -- and it is the copy spelled in the engineering vocabulary, which is how an internal
+    word gets back onto a line that carries none in its wording.
+
+    Only an exact match for the code being printed is removed, so nothing can be lost here that is
+    not already on screen. Removing it is not a translation and is not flagged as one: no wording
+    changes, and the machine-readable object is untouched as always.
+    """
+
+    if not code:
+        return message
+    return re.sub(rf"\s*\[{re.escape(code)}\]\s*$", "", message)
+
+
+def _subject_carries_internal_wording(message: str) -> bool:
+    """Whether the thing a message opens with is named with an internal word.
+
+    A refusal is written ``<subject>: <what went wrong>``, and the subject is usually a field path
+    inside a contract record. The rule above deliberately treats a path as a name rather than as
+    wording, because `candidate` buried inside `.work/run/candidate/manifest.json` is nobody's
+    sentence. That exemption is right in the middle of a line and wrong at the start of one:
+    ``sandbox.parsed: ...`` puts an internal word in front of a person as the subject of what they
+    are about to read. So a subject that carries one is grounds for substituting, even though the
+    same token further along the line would not be -- and the exact string is still one flag away.
+    """
+
+    head = _SEPARATOR.split(message, maxsplit=1)
+    if len(head) < 2:
+        return False
+    return any(pattern.search(head[0]) for pattern in _PATTERNS)
+
+
+def naming(error: BaseException) -> str:
+    """The class name this refusal's plain sentence is written against.
+
+    The class hierarchy is followed, so the eight `OSError` subclasses answer through `OSError`:
+    what a person is being told is that a filesystem step was refused, not which class carried the
+    refusal.
+    """
+
+    for cls in type(error).__mro__:
+        if cls.__name__ in EXCEPTION_HEADLINES:
+            return cls.__name__
+    return type(error).__name__
+
+
+def plain_headline(code: str | None, message: str, *, raised_as: str | None = None) -> str | None:
+    """The plain first line for one failure, or ``None`` when the message is already plain.
+
+    ``None`` rather than the message itself, because the caller has to know whether it substituted:
+    a replaced sentence has to say where the exact one went, and an untouched one must not.
+
+    ``code`` is the typed code the error carries; ``raised_as`` is the name of the class that raised
+    it, used only for the refusals that carry no code.
+    """
+
+    if not carries_internal_wording(message) and not _subject_carries_internal_wording(message):
+        return None
+    plain = HEADLINES.get(code or "")
+    if plain is None and code:
+        # The compound table corrects a prefix the way remediation's family_for does, so the
+        # headline and the remediation paragraph under it always answer as the same family.
+        compound = "_".join(code.split("_", 2)[:2])
+        family = COMPOUND_PREFIX_FAMILY.get(compound) or PREFIX_FAMILY.get(
+            code.split("_", 1)[0], ""
+        )
+        plain = FAMILY_HEADLINES.get(family)
+    if plain is None:
+        plain = EXCEPTION_HEADLINES.get(raised_as or "", _LAST_RESORT)
+    tail = _plain_tail(message)
+    return f"{plain}: {tail}" if tail else f"{plain}."
+
+
+def _plain_tail(message: str) -> str | None:
+    """The longest trailing part of ``message``, after a colon, that names something plainly.
+
+    Most refusals are written ``what went wrong: which thing``. The left half is the part that uses
+    the engineering words; the right half is a path, a member name, or a field path, and it is the
+    half that says which of a thousand files this is about. Taking the longest clean suffix keeps
+    that detail without carrying any of the wording the boundary is here to replace.
+
+    The class's own trailing ``[CODE]`` is dropped first: the plain block prints the code on its own
+    line, so keeping it here would both repeat it and re-introduce an internal word spelled in
+    upper case.
+    """
+
+    trimmed = _TRAILING_CODE.sub("", message)
+    for separator in _SEPARATOR.finditer(trimmed):
+        tail = trimmed[separator.end() :].strip()
+        if tail and not carries_internal_wording(tail) and _TRAILING_CODE.search(tail) is None:
+            return tail
+    return None
+
+
+__all__ = [
+    "ANY_SYSTEM_REFUSAL",
+    "EXACT_WORDING_HINT",
+    "EXCEPTION_HEADLINES",
+    "FAMILY_HEADLINES",
+    "HEADLINES",
+    "INTERNAL_TERMS",
+    "SYSTEM_REFUSALS",
+    "SystemRefusal",
+    "carries_internal_wording",
+    "json_headline",
+    "naming",
+    "plain_headline",
+    "refused_path",
+    "system_headline",
+    "system_lookup_code",
+    "system_refusal",
+    "without_repeated_code",
+]