mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/preflight.py

@@ -0,0 +1,918 @@
+"""What would stop a build on this machine, asked before the build rather than during it.
+
+Three refusals are decided by the operating system: creating an output safely, re-checking a sealed
+Build, and noticing a folder swapped underneath either operation. Preflight asks those platform
+questions before expensive source reads and transformations begin.
+
+The remaining checks cover absent or invalid Workbench and input folders, an output path that is
+already taken, an engine this machine does not have installed, and -- the one that is about the
+job rather than the machine -- whether *this workload* fits the ceilings the deterministic engine
+holds whatever it is run on. That last one is answered from the plan and one ``lstat`` per source,
+so a job that cannot run is refused here rather than inside a container after its sources have
+been uploaded and its deployment approved.
+
+**It writes nothing and looks at nothing it was not pointed at.** No environment variable is read,
+no credential material is touched, and the only paths opened are the ones named in the call. The
+stored stage of a workbench folder is read through the coordinator's own reader rather than by
+opening ``state.json`` directly, so a folder that is mid-repair is reported the way every other
+command reports it.
+
+**The stored stage words never move.** ``initialized``, ``planned``, ``building``,
+``candidate_built``, ``review_recorded`` and ``failed`` are contract values living in folders
+already on disk. :data:`PHASE_SENTENCES` maps them to plain sentences at display time only; nothing
+here writes a stage, and nothing here renames one.
+
+**No engine is imported unless one is named.** The engine table is deliberately lazy -- constructing
+a backend does not import its library -- and a preflight that probed all three on every run would
+undo that. The probe happens inside :func:`_engine_check`, which is reached only when ``engine`` is
+passed.
+
+Nothing here prints. :meth:`Preflight.to_dict` returns the one payload both renderings are built
+from, so the same answer can be shown in a browser later without re-deriving it.
+"""
+
+from __future__ import annotations
+
+import os
+import select
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.offline import CONTROL_PATH
+from mostlyright.data_harness.pipeline import _VERIFY_ALLOWLISTED_ENGINES
+from mostlyright.data_harness.ux.headline import (
+    json_headline,
+    naming,
+    plain_headline,
+    system_headline,
+    without_repeated_code,
+)
+from mostlyright.data_harness.ux.path_kind import (
+    A_FOLDER,
+    A_LINK,
+    NOTHING_THERE,
+    UNKNOWN_KIND,
+    kind_at,
+    presence_at,
+)
+from mostlyright.data_harness.ux.remediation import remediation_for
+from mostlyright.data_harness.ux.render import render_human
+from mostlyright.data_harness.ux.workload import (
+    Workload,
+    WorkloadUnreadable,
+    read_workload,
+)
+
+# The one status this command reports. It reports it whether anything is blocking or not: "nothing
+# would stop you" is an answer, and an answer is not an error.
+PREFLIGHT_STATUS = "preflight_completed"
+
+# The version of the payload below, carried the way every sibling command carries one -- `index`
+# emits `mr-data-private-index.v1`, `whoami` emits `mr-data-whoami.v1`. This command emitted none
+# while it answered one question about one machine; now that it also answers what a *workload*
+# needs, a consumer has to be able to tell which shape of answer it is holding.
+PREFLIGHT_SCHEMA_VERSION = "mr-data-preflight.v1"
+
+# What one check can come back as. `not_applicable` is the honest word for a check that was never
+# asked -- an omitted check reads as "unknown", and those are different answers.
+OK = "ok"
+BLOCKED = "blocked"
+NOT_APPLICABLE = "not_applicable"
+
+_MARKS = {OK: "[ok]", BLOCKED: "[stops you]", NOT_APPLICABLE: "[not asked]"}
+
+# The eight checks, by the name a person reads. They are values in the payload, never keys, so a
+# name is shown exactly as it is written here. The first seven are about this machine; the last is
+# about the job, and is the only one that reads anything the job itself declares.
+WRITING_CHECK = "writing a file safely"
+VERIFYING_CHECK = "re-checking a build"
+WATCHING_CHECK = "noticing a folder that changes underneath"
+WORKBENCH_CHECK = "the workbench folder"
+INPUT_CHECK = "the input folder"
+OUTPUT_CHECK = "where it would write"
+ENGINE_CHECK = "the engine"
+WORKLOAD_CHECK = "the workload itself"
+
+# Where the rendered lines and the closing advice sit in the payload. Both are keys a person reads.
+CHECKS_KEY = "checks"
+BLOCKED_KEY = "blocked"
+WHAT_TO_DO_KEY = "what to do"
+WORKLOAD_KEY = "the workload"
+
+NOTHING_TO_DO = "Nothing here would stop a build."
+
+# The error map ends its platform advice by naming this command. Printed inside this command that
+# line answers a question the reader has already acted on, so it is the one line dropped.
+_SELF_REFERENCE = "Run: mr-data preflight"
+
+# The stored stage of a workbench folder, in plain words. The keys are persisted contract values
+# and are never written or renamed here; only the sentence shown to a person is plain language.
+PHASE_SENTENCES: dict[str, str] = {
+    "initialized": "This workbench folder is set up; the plan has not been checked yet.",
+    "planned": "The plan here is checked and recorded; nothing has been built yet.",
+    "building": "A build is running here, or one stopped part way through.",
+    "candidate_built": "A build is sealed here; run mr-data show to read it.",
+    "review_recorded": "A review decision is sealed here.",
+    "failed": "The last build here failed.",
+}
+
+# The three steps a workbench folder records, and the four words it records against them. Both sets
+# are contract values on disk; both are mapped to plain words at display time only.
+STEP_NAMES: dict[str, str] = {
+    "plan": "checking the plan",
+    "build": "building",
+    "review": "review",
+}
+STEP_STATES: dict[str, str] = {
+    "pending": "not started",
+    "running": "in progress",
+    "completed": "done",
+    "failed": "failed",
+}
+
+# What each engine needs before it can build. The reference engine is pure Python and needs
+# nothing; the other two are asked for their own version, which is the call that imports them.
+_BUILT_IN = "is built in here and needs nothing installed"
+
+# Said about a path that is not a Workbench folder, whichever of the three ways it is not one: it
+# is not there, it is not a folder at all, or it is a folder nothing has been set up in. The second
+# line said "that folder" until the branch above it learned to tell those apart, which put the same
+# false claim in the advice that the sentence had just stopped making.
+_NOT_A_WORKBENCH = (
+    "Run mr-data init on a path that does not exist yet to set one up.",
+    "Nothing was read from that path, so nothing has to be undone.",
+)
+
+
+@dataclass(frozen=True)
+class PreflightCheck:
+    """One thing that was checked, how it came out, and what to do when it did not.
+
+    ``sentence`` is written for a person who has not read the source: it says what was looked at
+    and what was found, never only that something failed. ``remediation`` comes from the error map
+    wherever the same failure has a typed code, so this command and the refusal it predicts say
+    one thing rather than two.
+    """
+
+    name: str
+    outcome: str
+    sentence: str
+    remediation: tuple[str, ...] = ()
+
+    @property
+    def blocking(self) -> bool:
+        return self.outcome == BLOCKED
+
+    @property
+    def line(self) -> str:
+        """This check as one plain line: outcome first, then what it was, then what was found."""
+
+        return f"{_MARKS[self.outcome]} {self.name}: {self.sentence}"
+
+
+@dataclass(frozen=True)
+class Preflight:
+    """Every check this machine can answer before a build, and whether any of them stops you.
+
+    ``workload`` is the bounded facts of the job itself when one was named -- what its sources
+    weigh, and how each of those weights compares with the ceiling the engine will judge it by.
+    It is carried as a value beside the checks rather than folded into one of them, because a
+    check is one line and a workload is a table; the line summarising it is still in ``checks``,
+    so a reader who only reads the lines is not told less than the payload knows.
+    """
+
+    checks: tuple[PreflightCheck, ...]
+    workload: Workload | None = None
+
+    @property
+    def blocked(self) -> bool:
+        return any(check.blocking for check in self.checks)
+
+    @property
+    def what_to_do(self) -> str:
+        """The advice for every blocking check, in check order, each line said once."""
+
+        lines: list[str] = []
+        for check in self.checks:
+            if not check.blocking:
+                continue
+            for line in check.remediation or (check.sentence,):
+                if line not in lines:
+                    lines.append(line)
+        return "\n".join(lines) if lines else NOTHING_TO_DO
+
+    def to_dict(self) -> dict[str, Any]:
+        """The one payload both renderings are built from."""
+
+        width = len(str(max(len(self.checks), 1)))
+        payload: dict[str, Any] = {
+            "schema_version": PREFLIGHT_SCHEMA_VERSION,
+            "status": PREFLIGHT_STATUS,
+            BLOCKED_KEY: self.blocked,
+            WHAT_TO_DO_KEY: self.what_to_do,
+            CHECKS_KEY: {
+                f"check {index:0{width}d}": check.line
+                for index, check in enumerate(self.checks, start=1)
+            },
+        }
+        if self.workload is not None:
+            payload[WORKLOAD_KEY] = self.workload.to_block()
+        return payload
+
+    def lines(self) -> list[str]:
+        """Exactly the plain lines the command line prints, from exactly the same payload."""
+
+        return render_human(self.to_dict()).splitlines()
+
+
+def run_preflight(
+    *,
+    workspace: Path | str | None = None,
+    input_root: Path | str | None = None,
+    output: Path | str | None = None,
+    engine: str | None = None,
+    workload: Path | str | None = None,
+) -> Preflight:
+    """Answer what would stop a build here, without starting one and without writing anything.
+
+    The three platform checks are always run: they are what this command exists for, and they cost
+    nothing. The other five are run only when the caller names the thing to check, and are reported
+    as not asked otherwise -- an omitted check would read as an unknown one.
+
+    ``workload`` is the job: a workbench folder, a plan, or a frozen recipe. It is the only
+    argument whose answer is about the *data* rather than about this machine, and it is the one a
+    person about to deploy actually needs, because a job the engine will refuse is refused here
+    before a byte of it is uploaded.
+    """
+
+    facts = _workload_facts(workload, input_root=input_root)
+    checks = [
+        *_platform_checks(),
+        _workbench_check(workspace),
+        _input_check(input_root),
+        _output_check(output),
+        _engine_check(engine),
+        facts.check,
+    ]
+    return Preflight(checks=tuple(checks), workload=facts.workload)
+
+
+# ------------------------------------------------------------------------------------------------
+# What the operating system will and will not do
+# ------------------------------------------------------------------------------------------------
+
+
+def _platform_checks() -> list[PreflightCheck]:
+    """The three refusals this machine decides on its own, asked before any work is started."""
+
+    # Imported here, not at the top: the command line imports this package while it is still being
+    # set up. Asking the command line's own booleans rather than restating them is what keeps this
+    # answer and the refusal it predicts the same answer.
+    from mostlyright.data_harness import cli
+
+    return [
+        _platform_check(
+            WRITING_CHECK,
+            supported=cli._secure_cli_output_supported(),
+            yes="this machine can create a file exactly once, without following a link into it",
+            no="this machine cannot create a file safely, so nothing can be written here",
+            code="PLATFORM_OUTPUT_UNSUPPORTED",
+        ),
+        _platform_check(
+            VERIFYING_CHECK,
+            supported=cli._secure_cli_verification_supported(),
+            yes="this machine can re-read a sealed build without the folders moving underneath",
+            no="this machine cannot re-check a sealed build, so a build made here cannot be "
+            "re-checked here",
+            code="PLATFORM_VERIFY_UNSUPPORTED",
+        ),
+        _platform_check(
+            WATCHING_CHECK,
+            supported=_watching_supported(),
+            yes="this machine reports a folder that is moved or replaced while it is in use",
+            no="this machine cannot report a folder that is moved while it is in use, and both "
+            "writing and re-checking need that",
+            code=None,
+        ),
+    ]
+
+
+def _platform_check(
+    name: str,
+    *,
+    supported: bool,
+    yes: str,
+    no: str,
+    code: str | None,
+) -> PreflightCheck:
+    if supported:
+        return PreflightCheck(name=name, outcome=OK, sentence=yes)
+    return PreflightCheck(name=name, outcome=BLOCKED, sentence=no, remediation=_advice(code))
+
+
+def _watching_supported() -> bool:
+    """Whether a folder-watch can be opened at all, in the same order the command line tries.
+
+    This mirrors ``cli._create_cli_ancestor_monitor``, which takes descriptors and would therefore
+    have to be handed a folder to answer for. A test opens a real folder, asks that function, and
+    asserts the two agree, so the mirror cannot drift into a comfortable lie.
+    """
+
+    return hasattr(select, "kqueue") or sys.platform.startswith("linux")
+
+
+def _advice(code: str | None, **subject: Any) -> tuple[str, ...]:
+    """The error map's own sentences, minus the one that names the command already running."""
+
+    return tuple(line for line in remediation_for(code, **subject) if line != _SELF_REFERENCE)
+
+
+def _plainly(error: BaseException) -> str:
+    """A caught refusal's own wording, in plain words, ready to sit inside a check's sentence.
+
+    A check that stops you is a *successful* answer to the question this command asks, so its
+    sentence is carried on a payload that never passes through the command line's error boundary.
+    That boundary is where the one-direction translation happens, and a raise-site message
+    interpolated into a success payload would go around it -- which is exactly how ``durable state
+    references a missing candidate`` reached a person's screen with an internal word in it.
+
+    So the same boundary is applied here, from the same functions, in the same order the command
+    line applies them: the strict-JSON assembly, then a refusal the operating system raised, then
+    the term translation. A message that is already plain comes through untouched, as it does
+    everywhere else. No detail is lost: the trailing name a refusal ends in is carried onto the
+    plain sentence by ``plain_headline``, and the exact wording is still one ``--json`` away on
+    every command that raises rather than reports.
+
+    The closing full stop is dropped because the caller is embedding this after a colon inside a
+    longer sentence, not printing it as a headline of its own.
+    """
+
+    code = getattr(error, "code", None)
+    message = without_repeated_code(str(error), code if isinstance(code, str) else None)
+    plain = (
+        json_headline(error)
+        or system_headline(error)
+        or plain_headline(
+            code if isinstance(code, str) else None,
+            message,
+            raised_as=naming(error),
+        )
+    )
+    return (plain if plain is not None else message).rstrip(".")
+
+
+# ------------------------------------------------------------------------------------------------
+# The workbench folder
+# ------------------------------------------------------------------------------------------------
+
+
+def _workbench_check(workspace: Path | str | None) -> PreflightCheck:
+    """What stage the folder is at, what its three steps say, and whether it already holds a build.
+
+    A path that is not there is named as a path that is not there. The reader's own refusal for
+    that case is about the safety of the folders leading to it, which is true but unhelpful for an
+    absent path that is usually a typo.
+
+    "Not a folder" and "a folder that is not a workbench" are asked as two questions, in that
+    order, the way ``_input_check`` and ``peek`` ask them. Deciding from the control tree inside the
+    path cannot distinguish the two and would call a plain file, pipe, socket, or device "a folder,
+    but not a workbench folder". The noun therefore comes from a single ``lstat`` shared with the
+    writers rather than a second classification rule written here.
+
+    The ``lstat`` is taken once at the top, and its answer decides both the branch and the sentence.
+    ``Path.exists`` and ``Path.is_dir`` cannot participate because both follow links. At a *link to
+    a Workbench folder*, a following check says yes while the command refuses: ``offline`` opens
+    the folder chain with ``O_NOFOLLOW`` and stops at the link. The preview would otherwise report
+    a folder that is ready even though the Build cannot start. ``Path.is_dir`` also raises under a
+    parent this account may not search. :func:`kind_at` is the same look the
+    sentence already uses and answers ``None`` for a failed observation, allowing preflight to
+    report the unknown kind rather than emit a traceback.
+    """
+
+    if workspace is None:
+        return _not_asked(WORKBENCH_CHECK, "no workbench folder was named, so none was looked at")
+    path = Path(workspace)
+    found = presence_at(path)
+    if found == NOTHING_THERE:
+        return PreflightCheck(
+            name=WORKBENCH_CHECK,
+            outcome=BLOCKED,
+            # `presence_at` answers existence and kind from the same non-following lookup. A
+            # dangling link is therefore not described as an absent path simply because its target
+            # is absent.
+            sentence=f"there is {found} at {path}, "
+            "and a workbench has to be a folder this harness set up",
+            remediation=_NOT_A_WORKBENCH,
+        )
+    if found != A_FOLDER:
+        return PreflightCheck(
+            name=WORKBENCH_CHECK,
+            outcome=BLOCKED,
+            # "has to be" rather than "is": the phrase "is a folder" is exactly what this branch
+            # was found saying about a file, and a sentence that clears the finding while leaving
+            # the words that carried it in place is a sentence a reader still has to parse twice.
+            sentence=f"there is {found or UNKNOWN_KIND} at {path}, "
+            "and a workbench has to be a folder",
+            remediation=_NOT_A_WORKBENCH,
+        )
+    if kind_at(path / CONTROL_PATH) != A_FOLDER:
+        return PreflightCheck(
+            name=WORKBENCH_CHECK,
+            outcome=BLOCKED,
+            sentence=f"there is {found or UNKNOWN_KIND} at {path}, "
+            "but it is not a workbench folder",
+            remediation=_NOT_A_WORKBENCH,
+        )
+    # Imported here for the same reason the platform booleans are: this package is loaded while the
+    # command line is still being set up.
+    from mostlyright.data_harness.offline import OfflineRunError, status_workspace
+
+    try:
+        # Never waited for. A build holds the folder's durable lock for its whole length, and this
+        # is the command a person and a script are told to run *before* a build -- so a preflight
+        # that queued behind a running one would print nothing at all for as long as that build
+        # ran. Asked this way it says the folder is busy, which is an answer and is the answer.
+        recorded = status_workspace(path, wait=False)
+    except (OfflineRunError, OSError) as error:
+        code = getattr(error, "code", None)
+        return PreflightCheck(
+            name=WORKBENCH_CHECK,
+            outcome=BLOCKED,
+            sentence=f"the workbench folder at {path} could not be read: {_plainly(error)}",
+            remediation=_advice(code, path=str(path), path_exists=True),
+        )
+    return PreflightCheck(
+        name=WORKBENCH_CHECK,
+        outcome=OK,
+        sentence=_workbench_sentence(recorded),
+    )
+
+
+def _workbench_sentence(recorded: Mapping[str, Any]) -> str:
+    """The stage, the three steps, and whether there is already a build, in one plain line."""
+
+    phase = str(recorded.get("status", ""))
+    stage = PHASE_SENTENCES.get(phase, f"this folder records the stage {phase}.")
+    steps = ", ".join(_step_phrases(recorded.get("tasks", ())))
+    built = (
+        # `idempotent: true` on a second run means exactly "this build already existed and nothing
+        # was rebuilt" (recorded in 29-03's A7), so saying so here is safe.
+        "There is already a build in this folder, and building again would report that one "
+        "rather than making another."
+        if recorded.get("candidate") is not None
+        else "Nothing has been built here yet."
+    )
+    return f"{stage} Steps: {steps}. {built}"
+
+
+def _step_phrases(tasks: Any) -> list[str]:
+    phrases: list[str] = []
+    for task in tasks if isinstance(tasks, Sequence) else ():
+        if not isinstance(task, Mapping):
+            continue
+        task_id = str(task.get("task_id", ""))
+        status = str(task.get("status", ""))
+        phrases.append(
+            f"{STEP_NAMES.get(task_id, task_id)} {STEP_STATES.get(status, status)}",
+        )
+    return phrases
+
+
+# ------------------------------------------------------------------------------------------------
+# The folder read from, and the path written to
+# ------------------------------------------------------------------------------------------------
+
+
+def _input_check(input_root: Path | str | None) -> PreflightCheck:
+    """Whether there is anything to read, and whether this account may read it.
+
+    Anything that is not a folder is named from the same single ``lstat`` the rest of this module
+    and the writers share. A pipe, bound socket, or ``/dev/zero`` must not be called a file.
+
+    The link rule is applied here because the build applies it here.
+    ``pipeline._open_source_root`` opens every component of the input root with ``O_NOFOLLOW`` and
+    refuses the whole build on the first link, exactly as the output side does -- and this check
+    never asked. On this platform ``/tmp`` is a link, so *every* ``/tmp`` input root was previewed
+    as "nothing here would stop a build" and then refused with ``SOURCE_SYMLINK``, which is the
+    commonest path anyone points a first build at. The rule is asked first because the writer meets
+    it first: it walks down from the anchor, so a link above an input folder that is not there is
+    what stops the build, not the folder that is not there.
+
+    Unlike the output side, the root **itself** is included in the walk. The writer stats every
+    component of the input root, the last one included, and a root that is a link is refused on that
+    same test; an output's own name is not walked, because the writer creates it.
+    """
+
+    if input_root is None:
+        return _not_asked(INPUT_CHECK, "no input folder was named, so none was looked at")
+    root = Path(input_root)
+    linked = _first_link_in(Path(os.fspath(root)).absolute())
+    if linked is not None:
+        return _blocked(
+            INPUT_CHECK,
+            f"{linked} is {kind_at(linked) or UNKNOWN_KIND}, and a build refuses to read "
+            "through one",
+            _advice("SOURCE_SYMLINK", path=str(linked), path_exists=True),
+        )
+    found = presence_at(root)
+    # The same non-following observation drives both the message and remediation. A dangling link
+    # is an entry in its own right and must not be treated as an absent root.
+    advice = _advice(
+        "SOURCE_ROOT_INVALID",
+        path=str(root),
+        # Three answers rather than two: a look that failed is not a look that found nothing, and
+        # the map has a kind-neutral wording for exactly that.
+        path_exists=None if found is None else found != NOTHING_THERE,
+    )
+    if found == NOTHING_THERE:
+        return _blocked(
+            INPUT_CHECK,
+            f"there is {found} at {root} to read your sources from",
+            advice,
+        )
+    if found != A_FOLDER:
+        # Use the shared observation rather than a second `is_dir` lookup. The latter raises under
+        # an unsearchable parent, while the shared look reports an unknown kind without a traceback.
+        return _blocked(
+            INPUT_CHECK,
+            f"there is {found or UNKNOWN_KIND} at {root}, and sources are read from a folder",
+            advice,
+        )
+    if not os.access(root, os.R_OK | os.X_OK):
+        return _blocked(INPUT_CHECK, f"{root} cannot be opened by this account", advice)
+    try:
+        count = _readable_file_count(root)
+    except OSError as error:
+        return _blocked(INPUT_CHECK, f"{root} could not be listed: {_plainly(error)}", advice)
+    if not count:
+        return _blocked(INPUT_CHECK, f"there are no files in {root} to read", advice)
+    if count >= _INPUT_SCAN_CEILING:
+        return PreflightCheck(
+            name=INPUT_CHECK,
+            outcome=OK,
+            sentence=f"{root} holds {_INPUT_SCAN_CEILING} files or more",
+        )
+    noun = "file" if count == 1 else "files"
+    return PreflightCheck(name=INPUT_CHECK, outcome=OK, sentence=f"{root} holds {count} {noun}")
+
+
+# How far down to look for something a build could read, and how many files are worth counting
+# before the answer stops changing. A source path in a plan is a relative path that may name a
+# subfolder -- `raw/temps.csv` is legal, and the contract that validates source paths accepts any
+# relative path that does not climb out of the input folder -- so counting only the top level told
+# input folders that hold their sources one level down that they held nothing, and stopped a build
+# that would have worked. Both bounds are here so a yes/no question never becomes a scan of
+# somebody's home directory.
+_INPUT_SCAN_DEPTH = 6
+_INPUT_SCAN_CEILING = 1000
+
+
+def _readable_file_count(root: Path) -> int:
+    """How many plain files a build could read under ``root``, looking a bounded way down.
+
+    Links are not counted and not followed, which is the same rule the build itself applies to a
+    source path. A subfolder this account may not open is skipped rather than treated as an empty
+    input folder; the folder the caller actually named is the one whose refusal reaches them.
+    """
+
+    found = 0
+    pending: list[tuple[Path, int]] = [(root, 0)]
+    while pending and found < _INPUT_SCAN_CEILING:
+        directory, depth = pending.pop()
+        try:
+            names = sorted(os.listdir(directory))
+        except OSError:
+            if directory == root:
+                raise
+            continue
+        for name in names:
+            child = directory / name
+            if child.is_symlink():
+                continue
+            if child.is_file():
+                found += 1
+                if found >= _INPUT_SCAN_CEILING:
+                    break
+            elif depth < _INPUT_SCAN_DEPTH and child.is_dir():
+                pending.append((child, depth + 1))
+    return found
+
+
+def _output_check(output: Path | str | None) -> PreflightCheck:
+    """Whether the path is free, has no link above it, and sits in a folder that can be written to.
+
+    Nothing is ever overwritten, so a path that is already taken stops a build. Meeting that after
+    the build rather than before it wastes the completed work, so this asks the same refusal first.
+
+    The link check is the same rule stated the same way: sealing opens every component of the
+    output's parent chain without following links and refuses the whole build the moment one of
+    them is a link. On this platform ``/tmp`` is such a link, and ``/tmp`` is the commonest place
+    to write a first build to, so a preflight that omitted the rule reported "nothing here would
+    stop a build" about exactly the case it exists for.
+    """
+
+    if output is None:
+        return _not_asked(OUTPUT_CHECK, "no path to write to was named, so none was looked at")
+    destination = Path(output)
+    parent = destination.parent
+    linked = _linked_ancestor(destination)
+    if linked is not None:
+        return _blocked(
+            OUTPUT_CHECK,
+            # Derive the noun from the same observation `_linked_ancestor` selected on. Importing a
+            # constant into the sentence would assert the kind without binding it to that lookup.
+            f"{linked} is {kind_at(linked) or UNKNOWN_KIND}, and a build refuses to write "
+            "through one",
+            _advice("OUTPUT_SYMLINK", path=str(linked), path_exists=True),
+        )
+    if os.path.lexists(destination):
+        return _blocked(
+            OUTPUT_CHECK,
+            f"{destination} already holds something, and nothing is ever overwritten",
+            # This command looked, so it says what it found. `--output` is documented as an output
+            # path and README's own author and approve steps point it at Recipe files, so what is
+            # in the way here is regularly a file rather than a Build -- and the wording that calls
+            # it an overwritten build, and ends by naming `mr-data show`, is then two false
+            # sentences and a command that exits 1. `holds_a_build` is the same question the
+            # command line's error boundary asks about the same paths.
+            _advice(
+                "OUTPUT_EXISTS",
+                path=str(destination),
+                path_exists=True,
+                build_present=_holds_a_build(destination),
+            ),
+        )
+    above = presence_at(parent)
+    if above == NOTHING_THERE:
+        # `--output` is the path a Build would be written to, and
+        # `pipeline._open_output_parent` *creates* every missing component of it -- so
+        # `mr-data preflight --output .work/new/run` said you were blocked and
+        # `mr-data build --output .work/new/run` then built, which is the expensive direction to
+        # be wrong in: it stops work that would have finished. The refusal being quoted,
+        # `OUTPUT_PARENT_ABSENT`, belongs to `cli._write_output_exclusive` -- author, approve and
+        # export-hosted-candidate, the writers that really do make nothing on the way -- and its
+        # third sentence stated that as a property of every output, which the build does not have.
+        # A rewording would have left the two answers contradicting each other, so what changed is
+        # which answer this gives.
+        return PreflightCheck(
+            name=OUTPUT_CHECK,
+            outcome=OK,
+            sentence=f"{destination} is free, and there is {above} at {parent} yet; "
+            "a build creates the folders on the way to its output",
+        )
+    if above != A_FOLDER:
+        return _blocked(
+            OUTPUT_CHECK,
+            f"there is {above or UNKNOWN_KIND} at {parent}, so nothing can be written inside it",
+            # The writer's own code for this exact path, not the missing-folder one: `mkdir -p` on
+            # a path whose parent is a file fails with "File exists", so the warning surface used
+            # to name a fix that cannot be carried out and disagreed with the refusal it predicts
+            # (`cli._write_output_exclusive` raises `OUTPUT_PARENT_INVALID` here).
+            #
+            # The subject is the output rather than its parent, because the refusal's subject is
+            # the output and the two surfaces are meant to print one wording. The observation is
+            # the parent's, which is what the sentence names.
+            _advice(
+                "OUTPUT_PARENT_INVALID",
+                path=str(destination),
+                path_exists=False,
+                path_kind=above,
+            ),
+        )
+    if not os.access(parent, os.W_OK | os.X_OK):
+        return _blocked(
+            OUTPUT_CHECK,
+            f"{parent} cannot be written to by this account",
+            _advice("PERMISSION_DENIED", path=str(parent), path_exists=True),
+        )
+    return PreflightCheck(
+        name=OUTPUT_CHECK,
+        outcome=OK,
+        sentence=f"{destination} is free, and {parent} can be written to",
+    )
+
+
+def _holds_a_build(destination: Path) -> bool | None:
+    """Whether what is already at that path is a Build, or ``None`` when it cannot be told.
+
+    The reader the command line's error boundary uses, asked here for the same reason: a sentence
+    about an overwritten build, and a command that opens one, are answers only where a Build is
+    what is in the way.
+    """
+
+    from mostlyright.data_harness.ux.readers import holds_a_build
+
+    try:
+        return holds_a_build(destination)
+    except OSError:
+        return None
+
+
+def _linked_ancestor(destination: Path) -> Path | None:
+    """The first component of the output's parent chain that is a link, if any.
+
+    The walk is the writer's own walk, deliberately: the path is made absolute the way the writer
+    makes it absolute -- ``Path.absolute``, which prepends the working directory and collapses
+    nothing -- and each component above the output is then checked without following anything,
+    which is what ``pipeline._open_output_parent`` and ``cli._open_cli_directory_chain`` do before
+    they raise ``OUTPUT_SYMLINK``. A component that is not there yet cannot be a link and is
+    created by the writer, so it is passed over rather than reported.
+
+    ``os.path.abspath`` was used here and is the one thing this walk may not do: it collapses
+    ``..`` *lexically*, so ``/tmp/link/../out`` became ``/tmp/out`` and the link component the
+    writer meets on the way down was deleted from the path before it was ever looked at. Preflight
+    then reported ``[ok]`` about a path the write refuses as a blocker.
+
+    The output's own name is not walked, because the writer creates it. That is the one difference
+    from the input side, which walks its root's own name too -- see :func:`_input_check` -- and it
+    is why the shared walk below takes the path to walk rather than deciding for itself.
+    """
+
+    return _first_link_in(Path(os.fspath(destination)).absolute().parent)
+
+
+def _first_link_in(walked_to: Path) -> Path | None:
+    """The first component of ``walked_to``, its own name included, that is a link.
+
+    One walk serves both input and output checks because ``pipeline._open_source_root`` and the
+    output writer apply the same non-following ancestor rule.
+    """
+
+    walked = Path(walked_to.anchor)
+    for part in walked_to.parts[1:]:
+        walked = walked / part
+        # Use `ux.path_kind` for the decision as well as the rendered noun so the test and sentence
+        # cannot drift into different answers about the same entry.
+        if kind_at(walked) == A_LINK:
+            return walked
+    return None
+
+
+# ------------------------------------------------------------------------------------------------
+# The engine, asked for only when one is named
+# ------------------------------------------------------------------------------------------------
+
+
+def _engine_check(engine: str | None) -> PreflightCheck:
+    """Whether this build has that engine, and whether its library is installed here.
+
+    The library import happens through the backend's own version call, which is the same call a
+    build makes. Nothing on the default path reaches this function, so asking for a preflight does
+    not import an engine the caller never mentioned.
+    """
+
+    if engine is None:
+        return _not_asked(ENGINE_CHECK, "no engine was named, so the default one is assumed")
+    offered = ", ".join(sorted(_VERIFY_ALLOWLISTED_ENGINES))
+    if engine not in _VERIFY_ALLOWLISTED_ENGINES:
+        return _blocked(
+            ENGINE_CHECK,
+            f"there is no {engine} engine in this build; it has: {offered}",
+            (f"Ask for one of: {offered}.",),
+        )
+    from mostlyright.data_harness.backends import registry
+
+    try:
+        versions = registry.get_backend(engine).versions()
+    except Exception as error:
+        # Deliberately broad: an engine whose library will not load is an answer this command was
+        # asked for, and every way a library fails to load is that same answer.
+        return _blocked(
+            ENGINE_CHECK,
+            f"the {engine} engine is in this build, but its library will not load here: "
+            f"{_plainly(error)}",
+            (f"Install {engine} in the environment you are running mr-data from.",),
+        )
+    if not versions:
+        return PreflightCheck(
+            name=ENGINE_CHECK,
+            outcome=OK,
+            sentence=f"{engine} {_BUILT_IN}",
+        )
+    installed = ", ".join(f"{name} {value}" for name, value in sorted(versions.items()))
+    return PreflightCheck(
+        name=ENGINE_CHECK,
+        outcome=OK,
+        sentence=f"{engine} is installed here: {installed}",
+    )
+
+
+# ------------------------------------------------------------------------------------------------
+# The workload, asked for only when one is named
+# ------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _WorkloadAnswer:
+    """One line for the check list, and the table behind it when there was one."""
+
+    check: PreflightCheck
+    workload: Workload | None
+
+
+def _workload_facts(
+    workload: Path | str | None,
+    *,
+    input_root: Path | str | None,
+) -> _WorkloadAnswer:
+    """What this job weighs, against what the engine allows, before any of it is uploaded.
+
+    This is the one check that reads the data rather than the machine, and it is deliberately the
+    cheapest reading of it there is: the plan, and one ``lstat`` per source. No source is opened,
+    no graph is executed, and nothing is fetched, so the answer costs about what the six checks
+    above it cost and can honestly be the first thing anybody runs.
+
+    A workload that cannot be read is reported as a blocking check rather than raised, for the
+    same reason every other branch here is: "that is not a plan I can read" is an answer to the
+    question this command asks. The reason travels through the same plain-language boundary the
+    caught refusals above go through, so a raise-site message never reaches a person untranslated.
+    """
+
+    if workload is None:
+        return _WorkloadAnswer(
+            check=_not_asked(
+                WORKLOAD_CHECK,
+                "no workload was named, so nothing was measured about the job itself; without "
+                "one this command answers only for this machine",
+            ),
+            workload=None,
+        )
+    try:
+        facts = read_workload(workload, input_root=input_root)
+    except (WorkloadUnreadable, OSError) as error:
+        # The refusal underneath is preferred where the reader that raised it carried a code of
+        # its own: `plan.schema_version is unsupported` has a sentence written for it, and
+        # "the workload could not be read" is the class of failure rather than the failure.
+        code = getattr(error, "refused_as", None) or getattr(error, "code", None)
+        return _WorkloadAnswer(
+            check=PreflightCheck(
+                name=WORKLOAD_CHECK,
+                outcome=BLOCKED,
+                sentence=f"the workload at {workload} could not be read: {_plainly(error)}",
+                remediation=_advice(
+                    code if isinstance(code, str) else None,
+                    path=str(workload),
+                ),
+            ),
+            workload=None,
+        )
+    return _WorkloadAnswer(
+        check=PreflightCheck(
+            name=WORKLOAD_CHECK,
+            outcome=BLOCKED if facts.blocked else OK,
+            sentence=facts.sentence,
+            remediation=facts.remediation,
+        ),
+        workload=facts,
+    )
+
+
+# ------------------------------------------------------------------------------------------------
+# Small shared shapes
+# ------------------------------------------------------------------------------------------------
+
+
+def _not_asked(name: str, sentence: str) -> PreflightCheck:
+    return PreflightCheck(name=name, outcome=NOT_APPLICABLE, sentence=sentence)
+
+
+def _blocked(name: str, sentence: str, remediation: Sequence[str]) -> PreflightCheck:
+    return PreflightCheck(
+        name=name,
+        outcome=BLOCKED,
+        sentence=sentence,
+        remediation=tuple(remediation),
+    )
+
+
+# The stage sentences are held to cover every stored stage by a test rather than by an assertion
+# here, so a new stage cannot arrive without a plain sentence to show for it.
+__all__ = [
+    "BLOCKED",
+    "BLOCKED_KEY",
+    "CHECKS_KEY",
+    "ENGINE_CHECK",
+    "INPUT_CHECK",
+    "NOTHING_TO_DO",
+    "NOT_APPLICABLE",
+    "OK",
+    "OUTPUT_CHECK",
+    "PHASE_SENTENCES",
+    "PREFLIGHT_SCHEMA_VERSION",
+    "PREFLIGHT_STATUS",
+    "STEP_NAMES",
+    "STEP_STATES",
+    "VERIFYING_CHECK",
+    "WATCHING_CHECK",
+    "WHAT_TO_DO_KEY",
+    "WORKBENCH_CHECK",
+    "WORKLOAD_CHECK",
+    "WORKLOAD_KEY",
+    "WRITING_CHECK",
+    "Preflight",
+    "PreflightCheck",
+    "run_preflight",
+]